Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.joda.time.format
Class PeriodFormatter

    java.lang.Object
      org.joda.time.format.PeriodFormatter

    public class PeriodFormatter

extends java.lang.Object

Controls the printing and parsing of a time period to and from a string.

This class is the main API for printing and parsing used by most applications. Instances of this class are created via one of three factory classes:

- `PeriodFormat` - formats by pattern and style
- `ISOPeriodFormat` - ISO8601 formats
- `PeriodFormatterBuilder` - complex formats created via method calls

An instance of this class holds a reference internally to one printer and one parser. It is possible that one of these may be null, in which case the formatter cannot print/parse. This can be checked via the `isPrinter()` and `isParser()` methods.

The underlying printer/parser can be altered to behave exactly as required by using a decorator modifier:

- `withLocale(Locale)` - returns a new formatter that uses the specified locale

This returns a new formatter (instances of this class are immutable).

The main methods of the class are the `printXxx` and `parseXxx` methods. These are used as follows:

     // print using the default locale
     String periodStr = formatter.print(period);
     // print using the French locale
     String periodStr = formatter.withLocale(Locale.FRENCH).print(period);

     // parse using the French locale
     Period date = formatter.withLocale(Locale.FRENCH).parsePeriod(str);

Since:
  1.0
Author:
  Brian S O'Neill, Stephen Colebourne

Constructor Summary
`PeriodFormatter(PeriodPrinter printer, PeriodParser parser)` Creates a new formatter, however you will normally use the factory or the builder.

Method Summary
`java.util.Locale` | `getLocale()` Gets the locale that will be used for printing and parsing.
`PeriodParser` | `getParser()` Gets the internal parser object that performs the real parsing work.
`PeriodType` | `getParseType()` Gets the PeriodType that will be used for parsing.
`PeriodPrinter` | `getPrinter()` Gets the internal printer object that performs the real printing work.
`boolean` | `isParser()` Is this formatter capable of parsing.
`boolean` | `isPrinter()` Is this formatter capable of printing.
`int` | `parseInto(ReadWritablePeriod period, java.lang.String text, int position)` Parses a period from the given text, at the given position, saving the result into the fields of the given ReadWritablePeriod.
`MutablePeriod` | `parseMutablePeriod(java.lang.String text)` Parses a period from the given text, returning a new MutablePeriod.
`Period` | `parsePeriod(java.lang.String text)` Parses a period from the given text, returning a new Period.
`java.lang.String` | `print(ReadablePeriod period)` Prints a ReadablePeriod to a new String.
`void` | `printTo(java.lang.StringBuffer buf, ReadablePeriod period)` Prints a ReadablePeriod to a StringBuffer.
`void` | `printTo(java.io.Writer out, ReadablePeriod period)` Prints a ReadablePeriod to a Writer.
`PeriodFormatter` | `withLocale(java.util.Locale locale)` Returns a new formatter with a different locale that will be used for printing and parsing.
`PeriodFormatter` | `withParseType(PeriodType type)` Returns a new formatter with a different PeriodType for parsing.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### PeriodFormatter

    public PeriodFormatter(PeriodPrinter printer,
                           PeriodParser parser)

  Creates a new formatter, however you will normally use the factory or the builder.

  Parameters:
    `printer` - the internal printer, null if cannot print
    `parser` - the internal parser, null if cannot parse

Method Detail

### isPrinter

    public boolean isPrinter()

  Is this formatter capable of printing.

  Returns:
    true if this is a printer

### getPrinter

    public PeriodPrinter getPrinter()

  Gets the internal printer object that performs the real printing work.

  Returns:
    the internal printer

### isParser

    public boolean isParser()

  Is this formatter capable of parsing.

  Returns:
    true if this is a parser

### getParser

    public PeriodParser getParser()

  Gets the internal parser object that performs the real parsing work.

  Returns:
    the internal parser

### withLocale

    public PeriodFormatter withLocale(java.util.Locale locale)

  Returns a new formatter with a different locale that will be used for printing and parsing.

  A PeriodFormatter is immutable, so a new instance is returned, and the original is unaltered and still usable.

  Parameters:
    `locale` - the locale to use
  Returns:
    the new formatter

### getLocale

    public java.util.Locale getLocale()

  Gets the locale that will be used for printing and parsing.

  Returns:
    the locale to use

### withParseType

    public PeriodFormatter withParseType(PeriodType type)

  Returns a new formatter with a different PeriodType for parsing.

  A PeriodFormatter is immutable, so a new instance is returned, and the original is unaltered and still usable.

  Parameters:
    `type` - the type to use in parsing
  Returns:
    the new formatter

### getParseType

    public PeriodType getParseType()

  Gets the PeriodType that will be used for parsing.

  Returns:
    the parse type to use

### printTo

    public void printTo(java.lang.StringBuffer buf,
                        ReadablePeriod period)

  Prints a ReadablePeriod to a StringBuffer.

  Parameters:
    `buf` - the formatted period is appended to this buffer
    `period` - the period to format, not null

### printTo

    public void printTo(java.io.Writer out,
                        ReadablePeriod period)
                 throws java.io.IOException

  Prints a ReadablePeriod to a Writer.

  Parameters:
    `out` - the formatted period is written out
    `period` - the period to format, not null
  Throws:
    `java.io.IOException`

### print

    public java.lang.String print(ReadablePeriod period)

  Prints a ReadablePeriod to a new String.

  Parameters:
    `period` - the period to format, not null
  Returns:
    the printed result

### parseInto

    public int parseInto(ReadWritablePeriod period,
                         java.lang.String text,
                         int position)

  Parses a period from the given text, at the given position, saving the result into the fields of the given ReadWritablePeriod. If the parse succeeds, the return value is the new text position. Note that the parse may succeed without fully reading the text.

  The parse type of the formatter is not used by this method.

  If it fails, the return value is negative, but the period may still be modified. To determine the position where the parse failed, apply the one's complement operator (~) on the return value.

  Parameters:
    `period` - a period that will be modified
    `text` - text to parse
    `position` - position to start parsing from
  Returns:
    new position, if negative, parse failed. Apply complement operator (~) to get position of failure
  Throws:
    `java.lang.IllegalArgumentException` - if any field is out of range

### parsePeriod

    public Period parsePeriod(java.lang.String text)

  Parses a period from the given text, returning a new Period.

  Parameters:
    `text` - text to parse
  Returns:
    parsed value in a Period object
  Throws:
    `java.lang.IllegalArgumentException` - if any field is out of range

### parseMutablePeriod

    public MutablePeriod parseMutablePeriod(java.lang.String text)

  Parses a period from the given text, returning a new MutablePeriod.

  Parameters:
    `text` - text to parse
  Returns:
    parsed value in a MutablePeriod object
  Throws:
    `java.lang.IllegalArgumentException` - if any field is out of range

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD