public class PeriodFormatterBuilder
extends java.lang.Object
Period formatting is performed by the PeriodFormatter
class.
Three classes provide factory methods to create formatters, and this is one.
The others are PeriodFormat
and 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
Modifier and Type | Class and Description |
---|---|
(package private) static class |
PeriodFormatterBuilder.Composite
Composite implementation that merges other fields to create a full pattern.
|
(package private) static class |
PeriodFormatterBuilder.CompositeAffix
Builds a composite affix by merging two other affix implementations.
|
(package private) static class |
PeriodFormatterBuilder.FieldFormatter
Formats the numeric value of a field, potentially with prefix/suffix.
|
(package private) static class |
PeriodFormatterBuilder.IgnorableAffix
An affix that can be ignored.
|
(package private) static class |
PeriodFormatterBuilder.Literal
Handles a simple literal piece of text.
|
(package private) static interface |
PeriodFormatterBuilder.PeriodFieldAffix
Defines a formatted field's prefix or suffix text.
|
(package private) static class |
PeriodFormatterBuilder.PluralAffix
Implements an affix where the text varies by the amount of the field.
|
(package private) static class |
PeriodFormatterBuilder.RegExAffix
Implements an affix where the text varies by the amount of the field.
|
(package private) static class |
PeriodFormatterBuilder.Separator
Handles a separator, that splits the fields into multiple parts.
|
(package private) static class |
PeriodFormatterBuilder.SimpleAffix
Implements an affix where the text does not vary by the amount.
|
Modifier and Type | Field and Description |
---|---|
private static int |
DAYS |
private static int |
HOURS |
private java.util.List<java.lang.Object> |
iElementPairs |
private PeriodFormatterBuilder.FieldFormatter[] |
iFieldFormatters |
private int |
iMaxParsedDigits |
private int |
iMinPrintedDigits |
private boolean |
iNotParser
Set to true if the formatter is not a parser.
|
private boolean |
iNotPrinter
Set to true if the formatter is not a printer.
|
private PeriodFormatterBuilder.PeriodFieldAffix |
iPrefix |
private int |
iPrintZeroSetting |
private boolean |
iRejectSignedValues |
private static int |
MAX_FIELD |
private static int |
MILLIS |
private static int |
MINUTES |
private static int |
MONTHS |
private static java.util.concurrent.ConcurrentMap<java.lang.String,java.util.regex.Pattern> |
PATTERNS |
private static int |
PRINT_ZERO_ALWAYS |
private static int |
PRINT_ZERO_IF_SUPPORTED |
private static int |
PRINT_ZERO_NEVER |
private static int |
PRINT_ZERO_RARELY_FIRST |
private static int |
PRINT_ZERO_RARELY_LAST |
private static int |
SECONDS |
private static int |
SECONDS_MILLIS |
private static int |
SECONDS_OPTIONAL_MILLIS |
private static int |
WEEKS |
private static int |
YEARS |
Constructor and Description |
---|
PeriodFormatterBuilder() |
Modifier and Type | Method and Description |
---|---|
PeriodFormatterBuilder |
append(PeriodFormatter formatter)
Appends another formatter.
|
PeriodFormatterBuilder |
append(PeriodPrinter printer,
PeriodParser parser)
Appends a printer parser pair.
|
private PeriodFormatterBuilder |
append0(PeriodPrinter printer,
PeriodParser parser) |
PeriodFormatterBuilder |
appendDays()
Instruct the printer to emit an integer days field, if supported.
|
private void |
appendField(int type) |
private void |
appendField(int type,
int minPrinted) |
PeriodFormatterBuilder |
appendHours()
Instruct the printer to emit an integer hours field, if supported.
|
PeriodFormatterBuilder |
appendLiteral(java.lang.String text)
Instructs the printer to emit specific text, and the parser to expect it.
|
PeriodFormatterBuilder |
appendMillis()
Instruct the printer to emit an integer millis field, if supported.
|
PeriodFormatterBuilder |
appendMillis3Digit()
Instruct the printer to emit an integer millis field, if supported.
|
PeriodFormatterBuilder |
appendMinutes()
Instruct the printer to emit an integer minutes field, if supported.
|
PeriodFormatterBuilder |
appendMonths()
Instruct the printer to emit an integer months field, if supported.
|
private PeriodFormatterBuilder |
appendPrefix(PeriodFormatterBuilder.PeriodFieldAffix prefix)
Append a field prefix which applies only to the next appended field.
|
PeriodFormatterBuilder |
appendPrefix(java.lang.String text)
Append a field prefix which applies only to the next appended field.
|
PeriodFormatterBuilder |
appendPrefix(java.lang.String[] regularExpressions,
java.lang.String[] prefixes)
Append a field prefix which applies only to the next appended field.
|
PeriodFormatterBuilder |
appendPrefix(java.lang.String singularText,
java.lang.String pluralText)
Append a field prefix which applies only to the next appended field.
|
PeriodFormatterBuilder |
appendSeconds()
Instruct the printer to emit an integer seconds field, if supported.
|
PeriodFormatterBuilder |
appendSecondsWithMillis()
Instruct the printer to emit a combined seconds and millis field, if supported.
|
PeriodFormatterBuilder |
appendSecondsWithOptionalMillis()
Instruct the printer to emit a combined seconds and millis field, if supported.
|
PeriodFormatterBuilder |
appendSeparator(java.lang.String text)
Append a separator, which is output if fields are printed both before
and after the separator.
|
PeriodFormatterBuilder |
appendSeparator(java.lang.String text,
java.lang.String finalText)
Append a separator, which is output if fields are printed both before
and after the separator.
|
PeriodFormatterBuilder |
appendSeparator(java.lang.String text,
java.lang.String finalText,
java.lang.String[] variants)
Append a separator, which is output if fields are printed both before
and after the separator.
|
private PeriodFormatterBuilder |
appendSeparator(java.lang.String text,
java.lang.String finalText,
java.lang.String[] variants,
boolean useBefore,
boolean useAfter) |
PeriodFormatterBuilder |
appendSeparatorIfFieldsAfter(java.lang.String text)
Append a separator, which is output only if fields are printed after the separator.
|
PeriodFormatterBuilder |
appendSeparatorIfFieldsBefore(java.lang.String text)
Append a separator, which is output only if fields are printed before the separator.
|
private PeriodFormatterBuilder |
appendSuffix(PeriodFormatterBuilder.PeriodFieldAffix suffix)
Append a field suffix which applies only to the last appended field.
|
PeriodFormatterBuilder |
appendSuffix(java.lang.String text)
Append a field suffix which applies only to the last appended field.
|
PeriodFormatterBuilder |
appendSuffix(java.lang.String[] regularExpressions,
java.lang.String[] suffixes)
Append a field suffix which applies only to the last appended field.
|
PeriodFormatterBuilder |
appendSuffix(java.lang.String singularText,
java.lang.String pluralText)
Append a field suffix which applies only to the last appended field.
|
PeriodFormatterBuilder |
appendWeeks()
Instruct the printer to emit an integer weeks field, if supported.
|
PeriodFormatterBuilder |
appendYears()
Instruct the printer to emit an integer years field, if supported.
|
void |
clear()
Clears out all the appended elements, allowing this builder to be reused.
|
private void |
clearPrefix() |
private static java.lang.Object[] |
createComposite(java.util.List<java.lang.Object> elementPairs) |
PeriodFormatterBuilder |
maximumParsedDigits(int maxDigits)
Set the maximum digits parsed for the next and following appended
fields.
|
PeriodFormatterBuilder |
minimumPrintedDigits(int minDigits)
Set the minimum digits printed for the next and following appended
fields.
|
PeriodFormatterBuilder |
printZeroAlways()
Always print zero values for the next and following appended fields,
even if the period doesn't support it.
|
PeriodFormatterBuilder |
printZeroIfSupported()
Print zero values for the next and following appened fields only if the
period supports it.
|
PeriodFormatterBuilder |
printZeroNever()
Never print zero values for the next and following appended fields,
unless no fields would be printed.
|
PeriodFormatterBuilder |
printZeroRarelyFirst()
Never print zero values for the next and following appended fields,
unless no fields would be printed.
|
PeriodFormatterBuilder |
printZeroRarelyLast()
Never print zero values for the next and following appended fields,
unless no fields would be printed.
|
PeriodFormatterBuilder |
rejectSignedValues(boolean v)
Reject signed values when parsing the next and following appended fields.
|
PeriodFormatter |
toFormatter()
Constructs a PeriodFormatter using all the appended elements.
|
private static PeriodFormatter |
toFormatter(java.util.List<java.lang.Object> elementPairs,
boolean notPrinter,
boolean notParser) |
PeriodParser |
toParser()
Internal method to create a PeriodParser instance using all the
appended elements.
|
PeriodPrinter |
toPrinter()
Internal method to create a PeriodPrinter instance using all the
appended elements.
|
private static final int PRINT_ZERO_RARELY_FIRST
private static final int PRINT_ZERO_RARELY_LAST
private static final int PRINT_ZERO_IF_SUPPORTED
private static final int PRINT_ZERO_ALWAYS
private static final int PRINT_ZERO_NEVER
private static final int YEARS
private static final int MONTHS
private static final int WEEKS
private static final int DAYS
private static final int HOURS
private static final int MINUTES
private static final int SECONDS
private static final int MILLIS
private static final int SECONDS_MILLIS
private static final int SECONDS_OPTIONAL_MILLIS
private static final int MAX_FIELD
private static final java.util.concurrent.ConcurrentMap<java.lang.String,java.util.regex.Pattern> PATTERNS
private int iMinPrintedDigits
private int iPrintZeroSetting
private int iMaxParsedDigits
private boolean iRejectSignedValues
private PeriodFormatterBuilder.PeriodFieldAffix iPrefix
private java.util.List<java.lang.Object> iElementPairs
private boolean iNotPrinter
private boolean iNotParser
private PeriodFormatterBuilder.FieldFormatter[] iFieldFormatters
public PeriodFormatter toFormatter()
This is the main method used by applications at the end of the build process to create a usable formatter.
Once this method has been called, the builder is in an invalid state.
The returned formatter may not support both printing and parsing.
The methods PeriodFormatter.isPrinter()
and
PeriodFormatter.isParser()
will help you determine the state
of the formatter.
java.lang.IllegalStateException
- if the builder can produce neither a printer nor a parserpublic PeriodPrinter toPrinter()
Most applications will not use this method.
If you want a printer in an application, call toFormatter()
and just use the printing API.
Subsequent changes to this builder do not affect the returned printer.
public PeriodParser toParser()
Most applications will not use this method.
If you want a printer in an application, call toFormatter()
and just use the printing API.
Subsequent changes to this builder do not affect the returned parser.
public void clear()
public PeriodFormatterBuilder append(PeriodFormatter formatter)
public PeriodFormatterBuilder append(PeriodPrinter printer, PeriodParser 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 nullpublic PeriodFormatterBuilder appendLiteral(java.lang.String text)
java.lang.IllegalArgumentException
- if text is nullpublic PeriodFormatterBuilder minimumPrintedDigits(int minDigits)
public PeriodFormatterBuilder maximumParsedDigits(int maxDigits)
public PeriodFormatterBuilder rejectSignedValues(boolean v)
public PeriodFormatterBuilder printZeroRarelyLast()
This field setting is the default.
public PeriodFormatterBuilder printZeroRarelyFirst()
public PeriodFormatterBuilder printZeroIfSupported()
public PeriodFormatterBuilder printZeroAlways()
public PeriodFormatterBuilder printZeroNever()
This field setting is the default.
public PeriodFormatterBuilder appendPrefix(java.lang.String text)
text
- text to print before field only if field is printedappendSuffix(java.lang.String)
public PeriodFormatterBuilder appendPrefix(java.lang.String singularText, java.lang.String pluralText)
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)
public PeriodFormatterBuilder appendPrefix(java.lang.String[] regularExpressions, java.lang.String[] prefixes)
The value is converted to String. During parsing, the prefix is selected based on the match with the regular expression. The index of the first regular expression that matches value converted to String nominates the prefix. If none of the regular expressions match the value converted to String then the last prefix is selected.
An example usage for English might look like this:
appendPrefix(new String[] { "ˆ1$", ".*" }, new String[] { " year", " years" })
Please note that for languages with simple mapping (singular and plural prefix
only - like the one above) the appendPrefix(String, String)
method
will produce in a slightly faster formatter and that
appendPrefix(String[], String[])
method should be only used when the
mapping between values and prefixes is more complicated than the difference between
singular and plural.
regularExpressions
- an array of regular expressions, at least one
element, length has to match the length of prefixes parameterprefixes
- an array of prefixes, at least one element, length has to
match the length of regularExpressions parameterjava.lang.IllegalStateException
- if no field exists to append toappendPrefix(java.lang.String)
private PeriodFormatterBuilder appendPrefix(PeriodFormatterBuilder.PeriodFieldAffix prefix)
prefix
- custom prefixappendSuffix(java.lang.String)
public PeriodFormatterBuilder appendYears()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendMonths()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendWeeks()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendDays()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendHours()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendMinutes()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendSeconds()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendSecondsWithMillis()
public PeriodFormatterBuilder appendSecondsWithOptionalMillis()
public PeriodFormatterBuilder appendMillis()
The number of printed and parsed digits can be controlled using
minimumPrintedDigits(int)
and maximumParsedDigits(int)
.
public PeriodFormatterBuilder appendMillis3Digit()
The number of arsed digits can be controlled using maximumParsedDigits(int)
.
private void appendField(int type)
private void appendField(int type, int minPrinted)
public PeriodFormatterBuilder appendSuffix(java.lang.String text)
text
- text to print after field only if field is printedjava.lang.IllegalStateException
- if no field exists to append toappendPrefix(java.lang.String)
public PeriodFormatterBuilder appendSuffix(java.lang.String singularText, java.lang.String pluralText)
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)
public PeriodFormatterBuilder appendSuffix(java.lang.String[] regularExpressions, java.lang.String[] suffixes)
The value is converted to String. During parsing, the suffix is selected based on the match with the regular expression. The index of the first regular expression that matches value converted to String nominates the suffix. If none of the regular expressions match the value converted to String then the last suffix is selected.
An example usage for English might look like this:
appendSuffix(new String[] { "ˆ1$", ".*" }, new String[] { " year", " years" })
Please note that for languages with simple mapping (singular and plural suffix
only - like the one above) the appendSuffix(String, String)
method
will result in a slightly faster formatter and that
appendSuffix(String[], String[])
method should be only used when the
mapping between values and prefixes is more complicated than the difference between
singular and plural.
regularExpressions
- an array of regular expressions, at least one
element, length has to match the length of suffixes parametersuffixes
- an array of suffixes, at least one element, length has to
match the length of regularExpressions parameterjava.lang.IllegalStateException
- if no field exists to append toappendPrefix(java.lang.String)
private PeriodFormatterBuilder appendSuffix(PeriodFormatterBuilder.PeriodFieldAffix suffix)
suffix
- custom suffixjava.lang.IllegalStateException
- if no field exists to append toappendPrefix(java.lang.String)
public PeriodFormatterBuilder appendSeparator(java.lang.String text)
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 onepublic PeriodFormatterBuilder appendSeparatorIfFieldsAfter(java.lang.String text)
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 onepublic PeriodFormatterBuilder appendSeparatorIfFieldsBefore(java.lang.String text)
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 onepublic PeriodFormatterBuilder appendSeparator(java.lang.String text, java.lang.String finalText)
This 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 onepublic PeriodFormatterBuilder appendSeparator(java.lang.String text, java.lang.String finalText, java.lang.String[] variants)
This 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 PeriodFormatterBuilder appendSeparator(java.lang.String text, java.lang.String finalText, java.lang.String[] variants, boolean useBefore, boolean useAfter)
private void clearPrefix() throws java.lang.IllegalStateException
java.lang.IllegalStateException
private PeriodFormatterBuilder append0(PeriodPrinter printer, PeriodParser parser)
private static PeriodFormatter toFormatter(java.util.List<java.lang.Object> elementPairs, boolean notPrinter, boolean notParser)
private static java.lang.Object[] createComposite(java.util.List<java.lang.Object> elementPairs)