Class PeriodFormatter
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 styleISOPeriodFormat
- ISO8601 formatsPeriodFormatterBuilder
- 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
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
ConstructorsConstructorDescriptionPeriodFormatter
(PeriodPrinter printer, PeriodParser parser) Creates a new formatter, however you will normally use the factory or the builder. -
Method Summary
Modifier and TypeMethodDescriptionGets the locale that will be used for printing and parsing.Gets the internal parser object that performs the real parsing work.Gets the PeriodType that will be used for parsing.Gets the internal printer object that performs the real printing work.boolean
isParser()
Is this formatter capable of parsing.boolean
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.parseMutablePeriod
(String text) Parses a period from the given text, returning a new MutablePeriod.parsePeriod
(String text) Parses a period from the given text, returning a new Period.print
(ReadablePeriod period) Prints a ReadablePeriod to a new String.void
printTo
(Writer out, ReadablePeriod period) Prints a ReadablePeriod to a Writer.void
printTo
(StringBuffer buf, ReadablePeriod period) Prints a ReadablePeriod to a StringBuffer.withLocale
(Locale locale) Returns a new formatter with a different locale that will be used for printing and parsing.withParseType
(PeriodType type) Returns a new formatter with a different PeriodType for parsing.
-
Constructor Details
-
PeriodFormatter
Creates a new formatter, however you will normally use the factory or the builder.- Parameters:
printer
- the internal printer, null if cannot printparser
- the internal parser, null if cannot parse
-
-
Method Details
-
isPrinter
public boolean isPrinter()Is this formatter capable of printing.- Returns:
- true if this is a printer
-
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
Gets the internal parser object that performs the real parsing work.- Returns:
- the internal parser
-
withLocale
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
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
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
Gets the PeriodType that will be used for parsing.- Returns:
- the parse type to use
-
printTo
Prints a ReadablePeriod to a StringBuffer.- Parameters:
buf
- the formatted period is appended to this bufferperiod
- the period to format, not null
-
printTo
Prints a ReadablePeriod to a Writer.- Parameters:
out
- the formatted period is written outperiod
- the period to format, not null- Throws:
IOException
-
print
Prints a ReadablePeriod to a new String.- Parameters:
period
- the period to format, not null- Returns:
- the printed result
-
parseInto
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 modifiedtext
- text to parseposition
- 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
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
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
-