public class PeriodFormatter
extends java.lang.Object
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);
Modifier and Type | Field and Description |
---|---|
private java.util.Locale |
iLocale
The locale to use for printing and parsing.
|
private PeriodParser |
iParser
The internal parser used to output the datetime.
|
private PeriodType |
iParseType
The period type used in parsing.
|
private PeriodPrinter |
iPrinter
The internal printer used to output the datetime.
|
Constructor and Description |
---|
PeriodFormatter(PeriodPrinter printer,
PeriodParser parser)
Creates a new formatter, however you will normally use the factory
or the builder.
|
PeriodFormatter(PeriodPrinter printer,
PeriodParser parser,
java.util.Locale locale,
PeriodType type)
Constructor.
|
Modifier and Type | Method and Description |
---|---|
private void |
checkParser()
Checks whether parsing is supported.
|
private void |
checkPeriod(ReadablePeriod period)
Checks whether the period is non-null.
|
private void |
checkPrinter()
Checks whether printing is supported.
|
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.
|
private final PeriodPrinter iPrinter
private final PeriodParser iParser
private final java.util.Locale iLocale
private final PeriodType iParseType
public PeriodFormatter(PeriodPrinter printer, PeriodParser parser)
printer
- the internal printer, null if cannot printparser
- the internal parser, null if cannot parsePeriodFormatter(PeriodPrinter printer, PeriodParser parser, java.util.Locale locale, PeriodType type)
printer
- the internal printer, null if cannot printparser
- the internal parser, null if cannot parselocale
- the locale to usetype
- the parse period typepublic boolean isPrinter()
public PeriodPrinter getPrinter()
public boolean isParser()
public PeriodParser getParser()
public PeriodFormatter withLocale(java.util.Locale locale)
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.
locale
- the locale to usepublic java.util.Locale getLocale()
A null locale indicates that no specific locale override is in use.
public PeriodFormatter withParseType(PeriodType type)
A PeriodFormatter is immutable, so a new instance is returned, and the original is unaltered and still usable.
type
- the type to use in parsingpublic PeriodType getParseType()
public void printTo(java.lang.StringBuffer buf, ReadablePeriod period)
buf
- the formatted period is appended to this bufferperiod
- the period to format, not nullpublic void printTo(java.io.Writer out, ReadablePeriod period) throws java.io.IOException
out
- the formatted period is written outperiod
- the period to format, not nulljava.io.IOException
public java.lang.String print(ReadablePeriod period)
period
- the period to format, not nullprivate void checkPrinter()
java.lang.UnsupportedOperationException
- if printing is not supportedprivate void checkPeriod(ReadablePeriod period)
java.lang.IllegalArgumentException
- if the period is nullpublic int parseInto(ReadWritablePeriod period, java.lang.String text, int position)
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.
period
- a period that will be modifiedtext
- text to parseposition
- position to start parsing fromjava.lang.IllegalArgumentException
- if any field is out of rangepublic Period parsePeriod(java.lang.String text)
text
- text to parsejava.lang.IllegalArgumentException
- if any field is out of rangepublic MutablePeriod parseMutablePeriod(java.lang.String text)
text
- text to parsejava.lang.IllegalArgumentException
- if any field is out of rangeprivate void checkParser()
java.lang.UnsupportedOperationException
- if parsing is not supported