| java.lang.Object
 org.joda.time.format.PeriodFormatterBuilder
| PeriodFormatterBuilder | | public class PeriodFormatterBuilder (Code) | | Factory that creates complex instances of PeriodFormatter via method calls.
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 ")
.printZeroRarely()
.appendMonths()
.appendSuffix(" month", " months")
.toFormatter();
PeriodFormatterBuilder itself is mutable and not thread-safe, but the
formatters that it builds are thread-safe and immutable.
author:
Brian S O'Neill
since:
1.0
See Also: PeriodFormat |
| Inner Class :static interface PeriodFieldAffix | |
| Inner Class :static class SimpleAffix implements PeriodFieldAffix | |
| Inner Class :static class PluralAffix implements PeriodFieldAffix | |
| Inner Class :static class CompositeAffix implements PeriodFieldAffix | |
| Method Summary | |
| public PeriodFormatterBuilder | append(PeriodFormatter formatter)
Appends another formatter. | | public PeriodFormatterBuilder | append(PeriodPrinter printer, PeriodParser parser)
Appends a printer parser pair. | | public PeriodFormatterBuilder | appendDays()
Instruct the printer to emit an integer days field, if supported. | | public PeriodFormatterBuilder | appendHours()
Instruct the printer to emit an integer hours field, if supported. | | public PeriodFormatterBuilder | appendLiteral(String text)
Instructs the printer to emit specific text, and the parser to expect it. | | public PeriodFormatterBuilder | appendMillis()
Instruct the printer to emit an integer millis field, if supported. | | public PeriodFormatterBuilder | appendMillis3Digit()
Instruct the printer to emit an integer millis field, if supported. | | public PeriodFormatterBuilder | appendMinutes()
Instruct the printer to emit an integer minutes field, if supported. | | public PeriodFormatterBuilder | appendMonths()
Instruct the printer to emit an integer months field, if supported. | | public PeriodFormatterBuilder | appendPrefix(String text)
Append a field prefix which applies only to the next appended field. | | public PeriodFormatterBuilder | appendPrefix(String singularText, String pluralText)
Append a field prefix which applies only to the next appended field. | | public PeriodFormatterBuilder | appendSeconds()
Instruct the printer to emit an integer seconds field, if supported. | | public PeriodFormatterBuilder | appendSecondsWithMillis()
Instruct the printer to emit a combined seconds and millis field, if supported. | | public PeriodFormatterBuilder | appendSecondsWithOptionalMillis()
Instruct the printer to emit a combined seconds and millis field, if supported. | | public PeriodFormatterBuilder | appendSeparator(String text)
Append a separator, which is output if fields are printed both before
and after the separator. | | public PeriodFormatterBuilder | appendSeparator(String text, String finalText)
Append a separator, which is output if fields are printed both before
and after the separator. | | public PeriodFormatterBuilder | appendSeparator(String text, String finalText, String[] variants)
Append a separator, which is output if fields are printed both before
and after the separator. | | public PeriodFormatterBuilder | appendSeparatorIfFieldsAfter(String text)
Append a separator, which is output only if fields are printed after the separator. | | public PeriodFormatterBuilder | appendSeparatorIfFieldsBefore(String text)
Append a separator, which is output only if fields are printed before the separator. | | public PeriodFormatterBuilder | appendSuffix(String text)
Append a field suffix which applies only to the last appended field. | | public PeriodFormatterBuilder | appendSuffix(String singularText, String pluralText)
Append a field suffix which applies only to the last appended field. | | public PeriodFormatterBuilder | appendWeeks()
Instruct the printer to emit an integer weeks field, if supported. | | public PeriodFormatterBuilder | appendYears()
Instruct the printer to emit an integer years field, if supported. | | public void | clear()
Clears out all the appended elements, allowing this builder to be reused. | | public PeriodFormatterBuilder | maximumParsedDigits(int maxDigits)
Set the maximum digits parsed for the next and following appended
fields. | | public PeriodFormatterBuilder | minimumPrintedDigits(int minDigits)
Set the minimum digits printed for the next and following appended
fields. | | public PeriodFormatterBuilder | printZeroAlways()
Always print zero values for the next and following appended fields,
even if the period doesn't support it. | | public PeriodFormatterBuilder | printZeroIfSupported()
Print zero values for the next and following appened fields only if the
period supports it. | | public PeriodFormatterBuilder | printZeroNever()
Never print zero values for the next and following appended fields,
unless no fields would be printed. | | public PeriodFormatterBuilder | printZeroRarelyFirst()
Never print zero values for the next and following appended fields,
unless no fields would be printed. | | public PeriodFormatterBuilder | printZeroRarelyLast()
Never print zero values for the next and following appended fields,
unless no fields would be printed. | | public PeriodFormatterBuilder | rejectSignedValues(boolean v)
Reject signed values when parsing the next and following appended fields. | | public PeriodFormatter | toFormatter()
Constructs a PeriodFormatter using all the appended elements. | | public PeriodParser | toParser()
Internal method to create a PeriodParser instance using all the
appended elements. | | public PeriodPrinter | toPrinter()
Internal method to create a PeriodPrinter instance using all the
appended elements. |
| PeriodFormatterBuilder | | public PeriodFormatterBuilder()(Code) | | |
| append | | public PeriodFormatterBuilder append(PeriodPrinter printer, PeriodParser parser)(Code) | | Appends a printer parser pair.
Either the printer or the parser may be null, in which case the builder will
be unable to produce a parser or printer repectively.
Parameters:
printer - appends a printer to the builder, null if printing is not supported
Parameters:
parser - appends a parser to the builder, null if parsing is not supported this PeriodFormatterBuilder
throws:
IllegalArgumentException - if both the printer and parser are null |
| appendPrefix | | public PeriodFormatterBuilder appendPrefix(String singularText, String pluralText)(Code) | | Append a field prefix which applies only to the next appended field. If
the field is not printed, neither is the prefix.
During parsing, the singular and plural versions are accepted whether
or not the actual value matches plurality.
Parameters:
singularText - text to print if field value is one
Parameters:
pluralText - text to print if field value is not one this PeriodFormatterBuilder
See Also: PeriodFormatterBuilder.appendSuffix |
| appendSecondsWithMillis | | public PeriodFormatterBuilder appendSecondsWithMillis()(Code) | | Instruct the printer to emit a combined seconds and millis field, if supported.
The millis will overflow into the seconds if necessary.
The millis are always output.
this PeriodFormatterBuilder |
| appendSecondsWithOptionalMillis | | public PeriodFormatterBuilder appendSecondsWithOptionalMillis()(Code) | | Instruct the printer to emit a combined seconds and millis field, if supported.
The millis will overflow into the seconds if necessary.
The millis are only output if non-zero.
this PeriodFormatterBuilder |
| appendSeparator | | public PeriodFormatterBuilder appendSeparator(String text)(Code) | | Append a separator, which is output if fields are printed both before
and after the separator.
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.
Parameters:
text - the text to use as a separator this PeriodFormatterBuilder
throws:
IllegalStateException - if this separator follows a previous one |
| appendSeparator | | public PeriodFormatterBuilder appendSeparator(String text, String finalText)(Code) | | Append a separator, which is output if fields are printed both before
and after the separator.
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.
Parameters:
text - the text to use as a separator
Parameters:
finalText - the text used used if this is the final separator to be printed this PeriodFormatterBuilder
throws:
IllegalStateException - if this separator follows a previous one |
| appendSeparator | | public PeriodFormatterBuilder appendSeparator(String text, String finalText, String[] variants)(Code) | | Append a separator, which is output if fields are printed both before
and after the separator.
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.
Parameters:
text - the text to use as a separator
Parameters:
finalText - the text used used if this is the final separator to be printed
Parameters:
variants - set of text values which are also acceptable when parsed this PeriodFormatterBuilder
throws:
IllegalStateException - if this separator follows a previous one |
| appendSeparatorIfFieldsAfter | | public PeriodFormatterBuilder appendSeparatorIfFieldsAfter(String text)(Code) | | Append a separator, which is output only if fields are printed after the separator.
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.
Parameters:
text - the text to use as a separator this PeriodFormatterBuilder
throws:
IllegalStateException - if this separator follows a previous one |
| appendSeparatorIfFieldsBefore | | public PeriodFormatterBuilder appendSeparatorIfFieldsBefore(String text)(Code) | | Append a separator, which is output only if fields are printed before the separator.
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.
Parameters:
text - the text to use as a separator this PeriodFormatterBuilder
throws:
IllegalStateException - if this separator follows a previous one |
| appendSuffix | | public PeriodFormatterBuilder appendSuffix(String singularText, String pluralText)(Code) | | Append a field suffix which applies only to the last appended field. If
the field is not printed, neither is the suffix.
During parsing, the singular and plural versions are accepted whether or
not the actual value matches plurality.
Parameters:
singularText - text to print if field value is one
Parameters:
pluralText - text to print if field value is not one this PeriodFormatterBuilder
throws:
IllegalStateException - if no field exists to append to
See Also: PeriodFormatterBuilder.appendPrefix |
| clear | | public void clear()(Code) | | Clears out all the appended elements, allowing this builder to be reused.
|
| maximumParsedDigits | | public PeriodFormatterBuilder maximumParsedDigits(int maxDigits)(Code) | | Set the maximum digits parsed for the next and following appended
fields. By default, the maximum digits parsed is ten.
this PeriodFormatterBuilder |
| minimumPrintedDigits | | public PeriodFormatterBuilder minimumPrintedDigits(int minDigits)(Code) | | Set the minimum digits printed for the next and following appended
fields. By default, the minimum digits printed is one. If the field value
is zero, it is not printed unless a printZero rule is applied.
this PeriodFormatterBuilder |
| printZeroAlways | | public PeriodFormatterBuilder printZeroAlways()(Code) | | Always print zero values for the next and following appended fields,
even if the period doesn't support it. The parser requires values for
fields that always print zero.
this PeriodFormatterBuilder |
| printZeroIfSupported | | public PeriodFormatterBuilder printZeroIfSupported()(Code) | | Print zero values for the next and following appened fields only if the
period supports it.
this PeriodFormatterBuilder |
| printZeroNever | | public PeriodFormatterBuilder printZeroNever()(Code) | | Never print zero values for the next and following appended fields,
unless no fields would be printed. If no fields are printed, the printer
forces the last "printZeroRarely" field to print a zero.
This field setting is the default.
this PeriodFormatterBuilder |
| printZeroRarelyFirst | | public PeriodFormatterBuilder printZeroRarelyFirst()(Code) | | Never print zero values for the next and following appended fields,
unless no fields would be printed. If no fields are printed, the printer
forces the first "printZeroRarely" field to print a zero.
this PeriodFormatterBuilder |
| printZeroRarelyLast | | public PeriodFormatterBuilder printZeroRarelyLast()(Code) | | Never print zero values for the next and following appended fields,
unless no fields would be printed. If no fields are printed, the printer
forces the last "printZeroRarely" field to print a zero.
This field setting is the default.
this PeriodFormatterBuilder |
| rejectSignedValues | | public PeriodFormatterBuilder rejectSignedValues(boolean v)(Code) | | Reject signed values when parsing the next and following appended fields.
this PeriodFormatterBuilder |
| toFormatter | | public PeriodFormatter toFormatter()(Code) | | Constructs a PeriodFormatter using all the appended elements.
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
PeriodFormatter.isPrinter and
PeriodFormatter.isParser will help you determine the state
of the formatter.
the newly created formatter
throws:
IllegalStateException - if the builder can produce neither a printer nor a parser |
| toParser | | public PeriodParser toParser()(Code) | | Internal method to create a PeriodParser instance using all the
appended elements.
Most applications will not use this method.
If you want a printer in an application, call
PeriodFormatterBuilder.toFormatter() and just use the printing API.
Subsequent changes to this builder do not affect the returned parser.
the newly created parser, null if builder cannot create a parser |
| toPrinter | | public PeriodPrinter toPrinter()(Code) | | Internal method to create a PeriodPrinter instance using all the
appended elements.
Most applications will not use this method.
If you want a printer in an application, call
PeriodFormatterBuilder.toFormatter() and just use the printing API.
Subsequent changes to this builder do not affect the returned printer.
the newly created printer, null if builder cannot create a printer |
|
|