Period formatting is performed by the
class.
Three classes provide factory methods to create formatters, and this is one.
The others are PeriodFormatter
and PeriodFormat
.
ISOPeriodFormat
PeriodFormatterBuilder is used for constructing formatters which are then used to print or parse. The formatters are built by appending specific fields or other formatters to an instance of this builder.
For example, a formatter that prints years and months, like "15 years and 8 months", can be constructed as follows:
PeriodFormatter yearsAndMonths = new PeriodFormatterBuilder() .printZeroAlways() .appendYears() .appendSuffix(" year", " years") .appendSeparator(" and ") .printZeroRarelyLast() .appendMonths() .appendSuffix(" month", " months") .toFormatter();
PeriodFormatterBuilder itself is mutable and not thread-safe, but the formatters that it builds are thread-safe and immutable.
PeriodFormat
This is the main method used by applications at the end of the build process to create a usable formatter.
Subsequent changes to this builder do not affect the returned formatter.
The returned formatter may not support both printing and parsing.
The methods
and
PeriodFormatter.isPrinter()
will help you determine the state
of the formatter.
PeriodFormatter.isParser()
java.lang.IllegalStateException
if the builder can produce neither a printer nor a parser
Most applications will not use this method.
If you want a printer in an application, call
and just use the printing API.
toFormatter()
Subsequent changes to this builder do not affect the returned printer.
Most applications will not use this method.
If you want a printer in an application, call
and just use the printing API.
toFormatter()
Subsequent changes to this builder do not affect the returned parser.
Either the printer or the parser may be null, in which case the builder will be unable to produce a parser or printer repectively.
printer
appends a printer to the builder, null if printing is not supportedparser
appends a parser to the builder, null if parsing is not supportedjava.lang.IllegalArgumentException
if both the printer and parser are nulljava.lang.IllegalArgumentException
if text is nulltext
text to print before field only if field is printedappendSuffix(java.lang.String)
During parsing, the singular and plural versions are accepted whether or not the actual value matches plurality.
singularText
text to print if field value is onepluralText
text to print if field value is not oneappendSuffix(java.lang.String)
prefix
custom prefixappendSuffix(java.lang.String)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of printed and parsed digits can be controlled using
and minimumPrintedDigits(int)
.
maximumParsedDigits(int)
The number of arsed digits can be controlled using
.
maximumParsedDigits(int)
text
text to print after field only if field is printedjava.lang.IllegalStateException
if no field exists to append toappendPrefix(java.lang.String)
During parsing, the singular and plural versions are accepted whether or not the actual value matches plurality.
singularText
text to print if field value is onepluralText
text to print if field value is not onejava.lang.IllegalStateException
if no field exists to append toappendPrefix(java.lang.String)
suffix
custom suffixjava.lang.IllegalStateException
if no field exists to append toappendPrefix(java.lang.String)
For example, builder.appendDays().appendSeparator(",").appendHours()
will only output the comma if both the days and hours fields are output.
The text will be parsed case-insensitively.
Note: appending a separator discontinues any further work on the latest appended field.
text
the text to use as a separatorjava.lang.IllegalStateException
if this separator follows a previous one
For example,
builder.appendDays().appendSeparatorIfFieldsAfter(",").appendHours()
will only output the comma if the hours fields is output.
The text will be parsed case-insensitively.
Note: appending a separator discontinues any further work on the latest appended field.
text
the text to use as a separatorjava.lang.IllegalStateException
if this separator follows a previous one
For example,
builder.appendDays().appendSeparatorIfFieldsBefore(",").appendHours()
will only output the comma if the days fields is output.
The text will be parsed case-insensitively.
Note: appending a separator discontinues any further work on the latest appended field.
text
the text to use as a separatorjava.lang.IllegalStateException
if this separator follows a previous oneThis method changes the separator depending on whether it is the last separator to be output.
For example, builder.appendDays().appendSeparator(",", "&").appendHours().appendSeparator(",", "&").appendMinutes()
will output '1,2&3' if all three fields are output, '1&2' if two fields are output
and '1' if just one field is output.
The text will be parsed case-insensitively.
Note: appending a separator discontinues any further work on the latest appended field.
text
the text to use as a separatorfinalText
the text used used if this is the final separator to be printedjava.lang.IllegalStateException
if this separator follows a previous oneThis method changes the separator depending on whether it is the last separator to be output.
For example, builder.appendDays().appendSeparator(",", "&").appendHours().appendSeparator(",", "&").appendMinutes()
will output '1,2&3' if all three fields are output, '1&2' if two fields are output
and '1' if just one field is output.
The text will be parsed case-insensitively.
Note: appending a separator discontinues any further work on the latest appended field.
text
the text to use as a separatorfinalText
the text used used if this is the final separator to be printedvariants
set of text values which are also acceptable when parsedjava.lang.IllegalStateException
if this separator follows a previous oneprivate static PeriodFormattertoFormatter(List<Object> elementPairs, boolean notPrinter, boolean notParser) {