org.joda.time.format

Class PeriodFormatter

java.lang.Object

org.joda.time.format.PeriodFormatter

public class PeriodFormatter
extends 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

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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, 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(String text) Parses a period from the given text, returning a new MutablePeriod.
Period	parsePeriod(String text) Parses a period from the given text, returning a new Period.
String	print(ReadablePeriod period) Prints a ReadablePeriod to a new String.
void	printTo(StringBuffer buf, ReadablePeriod period) Prints a ReadablePeriod to a StringBuffer.
void	printTo(Writer out, ReadablePeriod period) Prints a ReadablePeriod to a Writer.
PeriodFormatter	withLocale(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(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.

A null locale indicates that no specific locale override is in use.

Parameters:

locale - the locale to use

Returns:

the new formatter

getLocale

public Locale getLocale()

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

A null locale indicates that no specific locale override is in use.

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(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(Writer out,
                    ReadablePeriod period)
             throws IOException

Prints a ReadablePeriod to a Writer.

Parameters:

out - the formatted period is written out

period - the period to format, not null

Throws:

IOException

print

public 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,
                     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:

IllegalArgumentException - if any field is out of range

parsePeriod

public Period parsePeriod(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:

IllegalArgumentException - if any field is out of range

parseMutablePeriod

public MutablePeriod parseMutablePeriod(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:

IllegalArgumentException - if any field is out of range