PeriodFormatterBuilder (Joda-Time 2.13.0 API)

java.lang.Object
- org.joda.time.format.PeriodFormatterBuilder

```
public class PeriodFormatterBuilder
extends Object
```
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 ")
     .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.
Since:

1.0

See Also:

PeriodFormat

Constructor Summary

Constructors
Constructor and Description

PeriodFormatterBuilder()

Constructors
Constructor and Description
`PeriodFormatterBuilder()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`PeriodFormatterBuilder`	`append(PeriodFormatter formatter)` Appends another formatter.
`PeriodFormatterBuilder`	`append(PeriodPrinter printer, PeriodParser parser)` Appends a printer parser pair.
`PeriodFormatterBuilder`	`appendDays()` Instruct the printer to emit an integer days field, if supported.
`PeriodFormatterBuilder`	`appendHours()` Instruct the printer to emit an integer hours field, if supported.
`PeriodFormatterBuilder`	`appendLiteral(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.
`PeriodFormatterBuilder`	`appendPrefix(String text)` Append a field prefix which applies only to the next appended field.
`PeriodFormatterBuilder`	`appendPrefix(String[] regularExpressions, String[] prefixes)` Append a field prefix which applies only to the next appended field.
`PeriodFormatterBuilder`	`appendPrefix(String singularText, 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(String text)` Append a separator, which is output if fields are printed both before and after the separator.
`PeriodFormatterBuilder`	`appendSeparator(String text, String finalText)` Append a separator, which is output if fields are printed both before and after the separator.
`PeriodFormatterBuilder`	`appendSeparator(String text, String finalText, String[] variants)` Append a separator, which is output if fields are printed both before and after the separator.
`PeriodFormatterBuilder`	`appendSeparatorIfFieldsAfter(String text)` Append a separator, which is output only if fields are printed after the separator.
`PeriodFormatterBuilder`	`appendSeparatorIfFieldsBefore(String text)` Append a separator, which is output only if fields are printed before the separator.
`PeriodFormatterBuilder`	`appendSuffix(String text)` Append a field suffix which applies only to the last appended field.
`PeriodFormatterBuilder`	`appendSuffix(String[] regularExpressions, String[] suffixes)` Append a field suffix which applies only to the last appended field.
`PeriodFormatterBuilder`	`appendSuffix(String singularText, 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.
`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 appended 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 reject)` Reject signed values when parsing the next and following appended fields.
`PeriodFormatter`	`toFormatter()` Constructs a PeriodFormatter using all the appended elements.
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PeriodFormatterBuilder
```
public PeriodFormatterBuilder()
```
- Method Detail
  - toFormatter
```
public PeriodFormatter toFormatter()
```
    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.
    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.
    
    Returns:
    
    the newly created formatter
    
    Throws:
    
    IllegalStateException - if the builder can produce neither a printer nor a parser
  - toPrinter
```
public PeriodPrinter toPrinter()
```
    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 toFormatter() and just use the printing API.
    Subsequent changes to this builder do not affect the returned printer.
    
    Returns:
    
    the newly created printer, null if builder cannot create a printer
  - toParser
```
public PeriodParser toParser()
```
    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 toFormatter() and just use the printing API.
    Subsequent changes to this builder do not affect the returned parser.
    
    Returns:
    
    the newly created parser, null if builder cannot create a parser
  - clear
```
public void clear()
```
    Clears out all the appended elements, allowing this builder to be reused.
  - append
```
public PeriodFormatterBuilder append(PeriodFormatter formatter)
```
    Appends another formatter.
    
    Parameters:
    
    formatter - the formatter to append
    
    Returns:
    
    this PeriodFormatterBuilder
  - append
```
public PeriodFormatterBuilder append(PeriodPrinter printer,
                                     PeriodParser parser)
```
    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 respectively.
    
    Parameters:
    
    printer - appends a printer to the builder, null if printing is not supported
    
    parser - appends a parser to the builder, null if parsing is not supported
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalArgumentException - if both the printer and parser are null
  - appendLiteral
```
public PeriodFormatterBuilder appendLiteral(String text)
```
    Instructs the printer to emit specific text, and the parser to expect it. The parser is case-insensitive.
    
    Parameters:
    
    text - the text to append
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalArgumentException - if text is null
  - minimumPrintedDigits
```
public PeriodFormatterBuilder minimumPrintedDigits(int minDigits)
```
    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.
    
    Parameters:
    
    minDigits - the minimum number of digits
    
    Returns:
    
    this PeriodFormatterBuilder
  - maximumParsedDigits
```
public PeriodFormatterBuilder maximumParsedDigits(int maxDigits)
```
    Set the maximum digits parsed for the next and following appended fields. By default, the maximum digits parsed is ten.
    
    Parameters:
    
    maxDigits - the maximum number of digits
    
    Returns:
    
    this PeriodFormatterBuilder
  - rejectSignedValues
```
public PeriodFormatterBuilder rejectSignedValues(boolean reject)
```
    Reject signed values when parsing the next and following appended fields.
    
    Parameters:
    
    reject - true to reject signed values
    
    Returns:
    
    this PeriodFormatterBuilder
  - printZeroRarelyLast
```
public PeriodFormatterBuilder printZeroRarelyLast()
```
    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.
    
    Returns:
    
    this PeriodFormatterBuilder
  - printZeroRarelyFirst
```
public PeriodFormatterBuilder printZeroRarelyFirst()
```
    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.
    
    Returns:
    
    this PeriodFormatterBuilder
  - printZeroIfSupported
```
public PeriodFormatterBuilder printZeroIfSupported()
```
    Print zero values for the next and following appended fields only if the period supports it.
    
    Returns:
    
    this PeriodFormatterBuilder
  - printZeroAlways
```
public PeriodFormatterBuilder printZeroAlways()
```
    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.
    
    Returns:
    
    this PeriodFormatterBuilder
  - printZeroNever
```
public PeriodFormatterBuilder printZeroNever()
```
    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.
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendPrefix
```
public PeriodFormatterBuilder appendPrefix(String text)
```
    Append a field prefix which applies only to the next appended field. If the field is not printed, neither is the prefix.
    
    Parameters:
    
    text - text to print before field only if field is printed
    
    Returns:
    
    this PeriodFormatterBuilder
    
    See Also:
    
    appendSuffix(java.lang.String)
  - appendPrefix
```
public PeriodFormatterBuilder appendPrefix(String singularText,
                                           String pluralText)
```
    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
    
    pluralText - text to print if field value is not one
    
    Returns:
    
    this PeriodFormatterBuilder
    
    See Also:
    
    appendSuffix(java.lang.String)
  - appendPrefix
```
public PeriodFormatterBuilder appendPrefix(String[] regularExpressions,
                                           String[] prefixes)
```
    Append a field prefix which applies only to the next appended field. If the field is not printed, neither is the prefix.
    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.
    Parameters:
    
    regularExpressions - an array of regular expressions, at least one element, length has to match the length of prefixes parameter
    
    prefixes - an array of prefixes, at least one element, length has to match the length of regularExpressions parameter
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if no field exists to append to
    
    Since:
    
    2.5
    
    See Also:
    
    appendPrefix(java.lang.String)
  - appendYears
```
public PeriodFormatterBuilder appendYears()
```
    Instruct the printer to emit an integer years field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendMonths
```
public PeriodFormatterBuilder appendMonths()
```
    Instruct the printer to emit an integer months field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendWeeks
```
public PeriodFormatterBuilder appendWeeks()
```
    Instruct the printer to emit an integer weeks field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendDays
```
public PeriodFormatterBuilder appendDays()
```
    Instruct the printer to emit an integer days field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendHours
```
public PeriodFormatterBuilder appendHours()
```
    Instruct the printer to emit an integer hours field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendMinutes
```
public PeriodFormatterBuilder appendMinutes()
```
    Instruct the printer to emit an integer minutes field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendSeconds
```
public PeriodFormatterBuilder appendSeconds()
```
    Instruct the printer to emit an integer seconds field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendSecondsWithMillis
```
public PeriodFormatterBuilder appendSecondsWithMillis()
```
    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.
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendSecondsWithOptionalMillis
```
public PeriodFormatterBuilder appendSecondsWithOptionalMillis()
```
    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.
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendMillis
```
public PeriodFormatterBuilder appendMillis()
```
    Instruct the printer to emit an integer millis field, if supported.
    The number of printed and parsed digits can be controlled using minimumPrintedDigits(int) and maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendMillis3Digit
```
public PeriodFormatterBuilder appendMillis3Digit()
```
    Instruct the printer to emit an integer millis field, if supported.
    The number of parsed digits can be controlled using maximumParsedDigits(int).
    
    Returns:
    
    this PeriodFormatterBuilder
  - appendSuffix
```
public PeriodFormatterBuilder appendSuffix(String text)
```
    Append a field suffix which applies only to the last appended field. If the field is not printed, neither is the suffix.
    
    Parameters:
    
    text - text to print after field only if field is printed
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if no field exists to append to
    
    See Also:
    
    appendPrefix(java.lang.String)
  - appendSuffix
```
public PeriodFormatterBuilder appendSuffix(String singularText,
                                           String pluralText)
```
    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
    
    pluralText - text to print if field value is not one
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if no field exists to append to
    
    See Also:
    
    appendPrefix(java.lang.String)
  - appendSuffix
```
public PeriodFormatterBuilder appendSuffix(String[] regularExpressions,
                                           String[] suffixes)
```
    Append a field suffix which applies only to the last appended field. If the field is not printed, neither is the suffix.
    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.
    Parameters:
    
    regularExpressions - an array of regular expressions, at least one element, length has to match the length of suffixes parameter
    
    suffixes - an array of suffixes, at least one element, length has to match the length of regularExpressions parameter
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if no field exists to append to
    
    Since:
    
    2.5
    
    See Also:
    
    appendPrefix(java.lang.String)
  - appendSeparator
```
public PeriodFormatterBuilder appendSeparator(String text)
```
    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
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if this separator follows a previous one
  - appendSeparatorIfFieldsAfter
```
public PeriodFormatterBuilder appendSeparatorIfFieldsAfter(String text)
```
    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
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if this separator follows a previous one
  - appendSeparatorIfFieldsBefore
```
public PeriodFormatterBuilder appendSeparatorIfFieldsBefore(String text)
```
    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
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if this separator follows a previous one
  - appendSeparator
```
public PeriodFormatterBuilder appendSeparator(String text,
                                              String finalText)
```
    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
    
    finalText - the text used used if this is the final separator to be printed
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if this separator follows a previous one
  - appendSeparator
```
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.
    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
    
    finalText - the text used used if this is the final separator to be printed
    
    variants - set of text values which are also acceptable when parsed
    
    Returns:
    
    this PeriodFormatterBuilder
    
    Throws:
    
    IllegalStateException - if this separator follows a previous one

Class PeriodFormatterBuilder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PeriodFormatterBuilder

Method Detail

toFormatter

toPrinter

toParser

clear

append

append

appendLiteral

minimumPrintedDigits

maximumParsedDigits

rejectSignedValues

printZeroRarelyLast

printZeroRarelyFirst

printZeroIfSupported

printZeroAlways

printZeroNever

appendPrefix

appendPrefix

appendPrefix

appendYears

appendMonths

appendWeeks

appendDays

appendHours

appendMinutes

appendSeconds

appendSecondsWithMillis

appendSecondsWithOptionalMillis

appendMillis

appendMillis3Digit

appendSuffix

appendSuffix

appendSuffix

appendSeparator

appendSeparatorIfFieldsAfter

appendSeparatorIfFieldsBefore

appendSeparator

appendSeparator