ChronoFormatter.Builder (Time4J-Core 2.2 API)

java.lang.Object
- net.time4j.format.ChronoFormatter.Builder<T>

Type Parameters:
T - generic type of chronological entity (subtype of ChronoEntity)

Enclosing class:

ChronoFormatter<T extends ChronoEntity<T>>
```
public static final class ChronoFormatter.Builder<T extends ChronoEntity<T>>
extends Object
```
Builder for creating a new ChronoFormatter.

This class is not thread-safe so a new instance is necessary per thread. A new instance can be created by ChronoFormatter.setUp(Class, Locale).

Author:

Meno Hochschild

Method Summary

Methods
Modifier and Type	Method and Description
`<V extends ChronoEntity<V>> ChronoFormatter.Builder<T>`	`addCustomized(ChronoElement<V> element, ChronoFormatter<V> formatter)` Defines a customized format element for given chronological element.
`<V> ChronoFormatter.Builder<T>`	`addCustomized(ChronoElement<V> element, ChronoPrinter<V> printer, ChronoParser<V> parser)` Defines a customized format element for given chronological element.
`ChronoFormatter.Builder<T>`	`addEnglishOrdinal(ChronoElement<Integer> element)` Defines an ordinal format for given chronological element in english language.
`ChronoFormatter.Builder<T>`	`addFixedDecimal(ChronoElement<BigDecimal> element, int precision, int scale)` Defines a fixed unsigned decimal format for given chronological element.
`ChronoFormatter.Builder<T>`	`addFixedInteger(ChronoElement<Integer> element, int digits)` Defines an integer format without sign and with fixed width for given chronological element.
`<V extends Enum<V>> ChronoFormatter.Builder<T>`	`addFixedNumerical(ChronoElement<V> element, int digits)` Defines an integer format without sign and with fixed width for given chronological enumeration element.
`ChronoFormatter.Builder<T>`	`addFraction(ChronoElement<Integer> element, int minDigits, int maxDigits, boolean decimalSeparator)` Defines a fractional format for given chronological element including a possible decimal separator char but without any integer part by mapping the context-dependent value range to the interval [0.0-1.0).
`ChronoFormatter.Builder<T>`	`addIgnorableWhitespace()` Defines a sequence of optional white space.
`ChronoFormatter.Builder<T>`	`addInteger(ChronoElement<Integer> element, int minDigits, int maxDigits)` Defines an integer format without sign for given chronological element.
`ChronoFormatter.Builder<T>`	`addInteger(ChronoElement<Integer> element, int minDigits, int maxDigits, SignPolicy signPolicy)` Defines an integer format for given chronological element.
`ChronoFormatter.Builder<T>`	`addLiteral(AttributeKey<Character> attribute)` Defines a literal element with a char which will be searched in given format attribute.
`ChronoFormatter.Builder<T>`	`addLiteral(char literal)` Defines a literal element with exactly one char.
`ChronoFormatter.Builder<T>`	`addLiteral(String literal)` Defines a literal element with any chars.
`ChronoFormatter.Builder<T>`	`addLongLocalizedOffset()` Adds a timezone offset in long localized notation.
`ChronoFormatter.Builder<T>`	`addLongNumber(ChronoElement<Long> element, int minDigits, int maxDigits, SignPolicy signPolicy)` Defines an integer format for given chronological element.
`ChronoFormatter.Builder<T>`	`addLongTimezoneName()` Adds a long localized timezone name.
`ChronoFormatter.Builder<T>`	`addLongTimezoneName(Set<TZID> preferredZones)` Adds a long localized timezone name.
`<V extends Enum<V>> ChronoFormatter.Builder<T>`	`addNumerical(ChronoElement<V> element, int minDigits, int maxDigits)` Defines an integer format without sign for given chronological enumeration element.
`ChronoFormatter.Builder<T>`	`addOrdinal(ChronoElement<Integer> element, Map<PluralCategory,String> indicators)` Defines an ordinal format for given chronological element.
`ChronoFormatter.Builder<T>`	`addPattern(String formatPattern, ChronoPattern patternType)` Processes given format pattern of given pattern type to a sequence of format elements.
`ChronoFormatter.Builder<T>`	`addShortLocalizedOffset()` Adds a timezone offset in short localized notation.
`ChronoFormatter.Builder<T>`	`addShortTimezoneName()` Adds a short localized timezone name (an abbreviation).
`ChronoFormatter.Builder<T>`	`addShortTimezoneName(Set<TZID> preferredZones)` Adds a short localized timezone name (an abbreviation).
`<V extends Enum<V>> ChronoFormatter.Builder<T>`	`addText(ChronoElement<V> element)` Defines a text format for given chronological element.
`<V extends Enum<V>> ChronoFormatter.Builder<T>`	`addText(ChronoElement<V> element, Map<V,String> lookup)` Defines a text format for given chronological element with user-defined string resources.
`ChronoFormatter.Builder<T>`	`addText(TextElement<?> element)` Defines a text format for given chronological element.
`ChronoFormatter.Builder<T>`	`addTimezoneID()` Adds a timezone identifier.
`ChronoFormatter.Builder<T>`	`addTimezoneOffset()` Adds a timezone offset in typical ISO-8601-notation.
`ChronoFormatter.Builder<T>`	`addTimezoneOffset(DisplayMode precision, boolean extended, List<String> zeroOffsets)` Adds a timezone offset in canonical notation.
`ChronoFormatter.Builder<T>`	`addTwoDigitYear(ChronoElement<Integer> element)` Defines a special format element for a two-digit-year.
`ChronoFormatter<T>`	`build()` Finishes the build and creates a new `ChronoFormatter`.
`ChronoFormatter.Builder<T>`	`endSection()` Removes the last sectional attribute.
`Chronology<T>`	`getChronology()` Returns the associated chronology.
`ChronoFormatter.Builder<T>`	`padNext(int width)` Defines for the next format element of the same section so many pad chars until the element width has reached the width specified.
`ChronoFormatter.Builder<T>`	`padPrevious(int width)` Defines for the previous format element of the same section so many pad chars until the element width has reached the width specified.
`ChronoFormatter.Builder<T>`	`startOptionalSection()` Starts a new optional section where errors in parsing will not cause an exception but just be ignored.
`ChronoFormatter.Builder<T>`	`startOptionalSection(ChronoCondition<ChronoDisplay> printCondition)` Starts a new optional section where errors in parsing will not cause an exception but just be ignored.
`<A extends Enum<A>> ChronoFormatter.Builder<T>`	`startSection(AttributeKey<A> key, A value)` Starts a new section with given sectional attribute.
`ChronoFormatter.Builder<T>`	`startSection(AttributeKey<Boolean> key, boolean value)` Starts a new section with given sectional attribute.
`ChronoFormatter.Builder<T>`	`startSection(AttributeKey<Character> key, char value)` Starts a new section with given sectional attribute.
`ChronoFormatter.Builder<T>`	`startSection(AttributeKey<Integer> key, int value)` Starts a new section with given sectional attribute.

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

Method Detail

getChronology
```
public Chronology<T> getChronology()
```
Returns the associated chronology.

Returns:
Chronology

addInteger
```
public ChronoFormatter.Builder<T> addInteger(ChronoElement<Integer> element,
 int minDigits,
 int maxDigits)
```
Defines an integer format without sign for given chronological element.

Equivalent to addInteger(element, minDigits, maxDigits, SignPolicy.SHOW_NEVER.

Parameters:
element - chronological element
minDigits - minimum count of digits in range 1-9
maxDigits - maximum count of digits in range 1-9

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if any of minDigits and maxDigits are out of range 1-9 or if maxDigits < minDigits or if given element is not supported by chronology or its preparser

IllegalStateException - if a numerical element is added multiple times in a row
See Also:
Chronology.isSupported(ChronoElement), SignPolicy.SHOW_NEVER, addInteger(ChronoElement, int, int, SignPolicy)

addInteger
```
public ChronoFormatter.Builder<T> addInteger(ChronoElement<Integer> element,
 int minDigits,
 int maxDigits,
 SignPolicy signPolicy)
```
Defines an integer format for given chronological element.

First a sign is expected (positive or negative) where the last argument signPolicy controls the output and interpretation. Following rules hold for the sequence of digits to be formatted:
1. PRINT => If the resulting sequence of digits has less than minDigits then it will be left-padded with zero digit char until the sequence has minDigits digits. But if there are more digits than maxDigits then an IllegalArgumentException will be thrown.
2. PARSE => At most maxDigits chars will be interpreted as digits. If there are less than minDigits then the text input will be invalid. Note: If there is no strict or smart mode (lax) then the parser will always assume minDigits == 0 and maxDigits = 9.
Example:
```
 ChronoElement<Integer> element = PlainTime.MILLI_OF_SECOND;
 int minDigits = 3;
 int maxDigits = 6;

 ChronoFormatter<PlainTime> formatter =
 ChronoFormatter.setUp(PlainTime.class, Locale.US)
 .addInteger(
 element,
 minDigits,
 maxDigits,
 SignPolicy.SHOW_ALWAYS)
 .build();
 System.out.println(
 formatter.format(PlainTime.of(12, 0, 0, 12345678)));
 // output: +012
 
```
Parameters:
element - chronological element
minDigits - minimum count of digits in range 1-9
maxDigits - maximum count of digits in range 1-9
signPolicy - controls output of numeric sign

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if any of minDigits and maxDigits are out of range 1-9 or if maxDigits < minDigits or if given element is not supported by chronology or its preparser

IllegalStateException - if a numerical element is added multiple times in a row
See Also:
Chronology.isSupported(ChronoElement), Attributes.LENIENCY

addLongNumber
```
public ChronoFormatter.Builder<T> addLongNumber(ChronoElement<Long> element,
 int minDigits,
 int maxDigits,
 SignPolicy signPolicy)
```
Defines an integer format for given chronological element.

Like addInteger(ChronoElement, int, int, SignPolicy) but on long-basis.

Parameters:
element - chronological element
minDigits - minimum count of digits in range 1-18
maxDigits - maximum count of digits in range 1-18
signPolicy - controls output of numeric sign

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if any of minDigits and maxDigits are out of range 1-18 or if maxDigits < minDigits or if given element is not supported by chronology or its preparser

IllegalStateException - if a numerical element is added multiple times in a row
See Also:
Chronology.isSupported(ChronoElement)

addFixedInteger
```
public ChronoFormatter.Builder<T> addFixedInteger(ChronoElement<Integer> element,
 int digits)
```
Defines an integer format without sign and with fixed width for given chronological element.

Almost equivalent to addInteger(element, digits, digits, SignPolicy.SHOW_NEVER) but with following important difference:

If this method directly follow after other numerical elements then the fixed width defined here will be preserved in preceding elements so parsing of those ancestors will not consume too many digits (adjacent digit parsing).

Parameters:
element - chronological element
digits - fixed count of digits in range 1-9

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if digits is out of range 1-9 or if given element is not supported by chronology or its preparser
See Also:
Chronology.isSupported(ChronoElement), SignPolicy.SHOW_NEVER, addInteger(ChronoElement, int, int, SignPolicy)

addNumerical
```
public <V extends Enum<V>> ChronoFormatter.Builder<T> addNumerical(ChronoElement<V> element,
 int minDigits,
 int maxDigits)
```
Defines an integer format without sign for given chronological enumeration element.

If the element is compatible to the interface NumericalElement then its value will first converted to an integer else the ordinal number of enum will be used. A sign is never printed or expected. Example:
```
 ChronoFormatter<PlainDate> formatter =
 ChronoFormatter.setUp(PlainDate.class, Locale.US)
 .addNumerical(Weekmodel.of(Locale.US).localDayOfWeek(), 1, 1)
 .build();
 System.out.println(
 formatter.format(PlainDate.of(2013, 6, 14))); // Freitag
 // output: 6 (next to last day of US week)
 
```
Type Parameters:
V - generic type of element values
Parameters:
element - chronological element
minDigits - minimum count of digits in range 1-9
maxDigits - maximum count of digits in range 1-9

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if any of minDigits and maxDigits are out of range 1-9 or if maxDigits < minDigits or if given element is not supported by chronology or its preparser

IllegalStateException - if a numerical element is added multiple times in a row
See Also:
Chronology.isSupported(ChronoElement), NumericalElement.numerical(V), SignPolicy.SHOW_NEVER

addFixedNumerical
```
public <V extends Enum<V>> ChronoFormatter.Builder<T> addFixedNumerical(ChronoElement<V> element,
 int digits)
```
Defines an integer format without sign and with fixed width for given chronological enumeration element.

Almost equivalent to addNumerical(element, digits, digits) but with following important difference:

If this method directly follow after other numerical elements then the fixed width defined here will be preserved in preceding elements so parsing of those ancestors will not consume too many digits (adjacent digit parsing).

Type Parameters:
V - generic type of element values
Parameters:
element - chronological element
digits - fixed count of digits in range 1-9

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if digits is out of range 1-9 or if given element is not supported by chronology or its preparser
See Also:
Chronology.isSupported(ChronoElement), addNumerical(ChronoElement, int, int)

addFraction
```
public ChronoFormatter.Builder<T> addFraction(ChronoElement<Integer> element,
 int minDigits,
 int maxDigits,
 boolean decimalSeparator)
```
Defines a fractional format for given chronological element including a possible decimal separator char but without any integer part by mapping the context-dependent value range to the interval [0.0-1.0).

First a leading decimal separator char will be formatted if required by last argument (for example in US the dot, in Germany a comma). Then the fractional digits follow by mean of the formula (value - min) / (max - min + 1). Possible gaps like offset-jumps in the value range mapping will be kept. The fractional representation is most suitable for elements with a fixed value range, for example MINUTE_OF_HOUR or MILLI_OF_SECOND.
1. PRINT => If the resulting sequence of digits after the decimal separator char has less than minDigits then it will be right-padded with zero digit char until there are minDigits digits. But if there are more than maxDigits then the sequence of digits will be truncated. In the special case of minDigits == 0 and if the sequence to be formatted has no digits then the diecimal separator char will be left out.
2. PARSE => At most maxDigits chars will be interpreted as digits. If there are less than minDigits then the text input will be invalid. Note: If there is just a lax mode then the parser will always assume minDigits == 0 and maxDigits = 9 unless a fixed width was implicitly specified by setting minDigits == maxDigits and without decimal separator char (then adjacent digit parsing).
Example:
```
 ChronoElement<Integer> element = PlainTime.MICRO_OF_SECOND;
 int minDigits = 3;
 int maxDigits = 6;

 ChronoFormatter<PlainTime> formatter =
 ChronoFormatter.setUp(PlainTime.class, Locale.US)
 .addFraction(
 element,
 minDigits,
 maxDigits,
 true
 ).build();
 System.out.println(
 formatter.format(PlainTime.of(12, 0, 0, 12345678)));
 // output in US: .012345
 
```
Note: A fractional element must not be directly preceded by another numerical element.
Parameters:
element - chronological element
minDigits - minimum count of digits after decimal separator in range 0-9
maxDigits - maximum count of digits after decimal separator in range 1-9
decimalSeparator - shall decimal separator be visible?

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if minDigits is out of range 0-9 or if maxDigits is out of range 1-9 or if maxDigits < minDigits or if given element is not supported by chronology or its preparser or if there is already a fractional or decimal part defined
See Also:
Chronology.isSupported(ChronoElement), Attributes.LENIENCY

addFixedDecimal
```
public ChronoFormatter.Builder<T> addFixedDecimal(ChronoElement<BigDecimal> element,
 int precision,
 int scale)
```
Defines a fixed unsigned decimal format for given chronological element.
1. PRINT => If the resulting sequence of digits before the decimal separator char has less than precision - scale digits then it will be left-padded with zero digit chars. Otherwise if there are more integer digits than allowed then an exception will be thrown.
 
 If the resulting sequence of digits after the decimal separator is smaller than scale then the sequence will be right-padded with zero digit chars. Otherwise the sequence of decimal digits will be truncated if necessary.
2. PARSE => Exactly precision chars will be interpreted as digits in strict mode. Otherwise as many digits are parsed as available and found.
Example:
```
 ChronoElement<BigDecimal> element = PlainTime.DECIMAL_MINUTE;
 int precision = 3;
 int scale = 1;

 ChronoFormatter<PlainTime> formatter =
 ChronoFormatter.setUp(PlainTime.class, Locale.US)
 .addPattern("HH:", PatternType.CLDR)
 .addFixedDecimal(element, precision, scale)
 .build();
 System.out.println(formatter.format(PlainTime.of(12, 8, 30)));
 // output: 12:08.5
 
```
Note: A decimal element must not be directly preceded by another numerical element.
Parameters:
element - chronological element
precision - total count of digits >= 2
scale - digits after decimal separator >= 1

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if precision is smaller than 2 or if scale is smaller than 1 or if precision <= scale or if given element is not supported by chronology or its preparser or if there is already a fractional or decimal part defined
See Also:
Chronology.isSupported(ChronoElement), Attributes.LENIENCY

addEnglishOrdinal
```
public ChronoFormatter.Builder<T> addEnglishOrdinal(ChronoElement<Integer> element)
```
Defines an ordinal format for given chronological element in english language.

An ordinal indicator will be printed or parsed after a given sequence of digits. In English the indicators "st", "nd", "rd" and "th" are used dependent on the value of the element.

Parameters:
element - chronological element

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given element is not supported by the underlying chronology or its preparser

IllegalStateException - if a numerical element is added multiple times in a row
Since:

1.2

See Also:
Chronology.isSupported(ChronoElement), addOrdinal(ChronoElement,Map)

addOrdinal
```
public ChronoFormatter.Builder<T> addOrdinal(ChronoElement<Integer> element,
 Map<PluralCategory,String> indicators)
```
Defines an ordinal format for given chronological element.

An ordinal indicator will be printed or parsed after a given sequence of digits. In English the indicators "st", "nd", "rd" and "th" are used dependent on the value of the element. In many other languages a fixed literal can be sufficient (although often context-dependent). This method is necessary if the indicators of a given language depend on the numerical value of the element.

Example for French generating HTML-text:
```
 ChronoElement<Integer> element = PlainDate.DAY_OF_MONTH;
 Map<PluralCategory, String> indicators =
 new HashMap<PluralCategory, String>();
 indicators.put(PluralCategory.ONE, "er");
 indicators.put(PluralCategory.OTHER, "e");

 ChronoFormatter<PlainDate> formatter =
 ChronoFormatter.setUp(PlainDate.class, Locale.FRENCH)
 .addOrdinal(element, indicators)
 .addLiteral(" jour")
 .build();
 System.out.println(
 formatter.format(PlainDate.of(2014, 8, 1)));
 // output: 1er jour
 
```
Note that dependent on the context other strings can be necessary, for example French also uses feminine forms (for the week etc.).
Parameters:
element - chronological element
indicators - ordinal indicators to be used as suffixes

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if there is no indicator at least for the plural category OTHER or if given element is not supported by the underlying chronology or its preparser

IllegalStateException - if a numerical element is added multiple times in a row
Since:

1.2

See Also:
Chronology.isSupported(ChronoElement)

addLiteral
```
public ChronoFormatter.Builder<T> addLiteral(char literal)
```
Defines a literal element with exactly one char.

Usually the literal char is a punctuation mark or a letter symbol. Decimal digits as literal chars are not recommended, especially not after preceding numerical elements.

Parameters:
literal - single literal char

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if the char represents a non-printable ASCII-char

addLiteral
```
public ChronoFormatter.Builder<T> addLiteral(String literal)
```
Defines a literal element with any chars.

Usually the literal char sequence consists of punctuation marks or letter symbols. Leading decimal digits as literal chars are not recommended, especially not after preceding numerical elements.

Parameters:
literal - literal char sequence

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given literal is empty or starts with a non-printable ASCII-char

addLiteral
```
public ChronoFormatter.Builder<T> addLiteral(AttributeKey<Character> attribute)
```
Defines a literal element with a char which will be searched in given format attribute.

A localized decimal separator char as literal will be possible if the argument is equal to Attributes.DECIMAL_SEPARATOR. Note: If given format attribute does not exist at runtime then the formatting will fail.

Parameters:
attribute - attribute defining a literal char

Returns:
this instance for method chaining

addIgnorableWhitespace
```
public ChronoFormatter.Builder<T> addIgnorableWhitespace()
```
Defines a sequence of optional white space.

If printed a space char will be used. In parsing however, any white space of arbitrary length will be ignored and skipped.

Returns:
this instance for method chaining

addPattern
```
public ChronoFormatter.Builder<T> addPattern(String formatPattern,
 ChronoPattern patternType)
```
Processes given format pattern of given pattern type to a sequence of format elements.

The letters a-z and A-Z are treated as format symbols. The square brackets "[" and "]" define an optional section which can be nested, too.. The chars "#", "{" and "}" are reserved for the future. All other chars will be interpreted as literals. If a reserved char shall be treated as literal then it must be escaped by the apostroph "'". The apostroph itself can be treated as literal by double apostroph.

For exact interpretation and description of format symbols see the implementations of interface ChronoPattern.

Parameters:
formatPattern - pattern of symbols to be used in formatting
patternType - type of pattern how to interprete symbols

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if resolving of pattern fails
See Also:
PatternType

addText
```
public ChronoFormatter.Builder<T> addText(TextElement<?> element)
```
Defines a text format for given chronological element.

Parameters:
element - chronological text element

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given element is not supported by chronology or its preparser
See Also:
Chronology.isSupported(ChronoElement)

addText
```
public <V extends Enum<V>> ChronoFormatter.Builder<T> addText(ChronoElement<V> element)
```
Defines a text format for given chronological element.

Type Parameters:
V - generic type of element values
Parameters:
element - chronological element

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given element is not supported by chronology
See Also:
Chronology.isSupported(ChronoElement)

addText
```
public <V extends Enum<V>> ChronoFormatter.Builder<T> addText(ChronoElement<V> element,
 Map<V,String> lookup)
```
Defines a text format for given chronological element with user-defined string resources.

Type Parameters:
V - generic type of element values
Parameters:
element - chronological element
lookup - text resources for lookup

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given element is not supported by chronology or its preparser
See Also:
Chronology.isSupported(ChronoElement)

addCustomized
```
public <V extends ChronoEntity<V>> ChronoFormatter.Builder<T> addCustomized(ChronoElement<V> element,
 ChronoFormatter<V> formatter)
```
Defines a customized format element for given chronological element.

Type Parameters:
V - generic type of element values
Parameters:
element - chronological element
formatter - customized formatter object as delegate

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given element is not supported by chronology or its preparser
See Also:
Chronology.isSupported(ChronoElement)

addCustomized
```
public <V> ChronoFormatter.Builder<T> addCustomized(ChronoElement<V> element,
 ChronoPrinter<V> printer,
 ChronoParser<V> parser)
```
Defines a customized format element for given chronological element.

Type Parameters:
V - generic type of element values
Parameters:
element - chronological element
printer - customized printer
parser - customized parser

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given element is not supported by chronology or its preparser
See Also:
Chronology.isSupported(ChronoElement)

addTwoDigitYear
```
public ChronoFormatter.Builder<T> addTwoDigitYear(ChronoElement<Integer> element)
```
Defines a special format element for a two-digit-year.

It is possible to specify a pivot year by setting the attribute Attributes.PIVOT_YEAR to a meaningful year. If this attribute is missing then Time4J will set the year twenty years after now as pivot year by default.

If this format element is directly preceded by other numerical elements with variable width then the fixed width of 2 will be preserved such that the preceding elements will not consume too many digits (adjacent digit parsing). Otherwise this format element can also parse more than two digits if there is no strict mode with the consequence that the parsed year will be interpreted as absolute full year.

Parameters:
element - year element (name must start with the prefix "YEAR")

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given element is not supported by chronology
See Also:
Attributes.PIVOT_YEAR

addTimezoneID
```
public ChronoFormatter.Builder<T> addTimezoneID()
```
Adds a timezone identifier.

Parsing of a timezone ID is case-sensitive. All timezone IDs which will be provided by Timezone.getAvailableIDs() will be supported - with the exception of old IDs like "Asia/Riyadh87" or "CST6CDT" which contain some digits. Offset-IDs like the canonical form of ZonalOffset or "GMT" are supported, too. An exceptional case are again deprecated IDs like "Etc/GMT+12".

Returns:
this instance for method chaining

Throws:

IllegalStateException - wenn die zugrundeliegende Chronologie nicht dem Typ UnixTime entspricht

addShortTimezoneName
```
public ChronoFormatter.Builder<T> addShortTimezoneName()
```
Adds a short localized timezone name (an abbreviation).

Dependent on the current locale, the preferred timezone IDs in a country will be determined first. The parsing of timezone names is case-sensitive.

Note that Time4J will try to find a unique mapping from names to IDs for US in smart parsing mode. However, this is only an imperfect approximation to current practice. A counter example is Phoenix which does not observe daylight savings although it has the same name "MST" as Denver.

Returns:
this instance for method chaining
See Also:
addShortTimezoneName(Set)

addLongTimezoneName
```
public ChronoFormatter.Builder<T> addLongTimezoneName()
```
Adds a long localized timezone name.

Dependent on the current locale, the preferred timezone IDs in a country will be determined first. The parsing of timezone names is case-sensitive.

Note that Time4J will try to find a unique mapping from names to IDs for US in smart parsing mode. However, this is only an imperfect approximation to current practice. A counter example is Phoenix which does not observe daylight savings although it has the same name "Mountain Standard Time" as Denver.

Returns:
this instance for method chaining
See Also:
addLongTimezoneName(Set)

addShortTimezoneName
```
public ChronoFormatter.Builder<T> addShortTimezoneName(Set<TZID> preferredZones)
```
Adds a short localized timezone name (an abbreviation).

Parsing of timezone names is case-sensitive.

Parameters:
preferredZones - preferred timezone ids for resolving duplicates

Returns:
this instance for method chaining
See Also:
addLongTimezoneName(Set)

addLongTimezoneName
```
public ChronoFormatter.Builder<T> addLongTimezoneName(Set<TZID> preferredZones)
```
Adds a long localized timezone name.

Parsing of timezone names is case-sensitive.

Parameters:
preferredZones - preferred timezone ids for resolving duplicates

Returns:
this instance for method chaining
See Also:
addShortTimezoneName(Set)

addTimezoneOffset
```
public ChronoFormatter.Builder<T> addTimezoneOffset()
```
Adds a timezone offset in typical ISO-8601-notation.

The offset format is "±HH:mm" or in case of zero offset simply "Z". Equivalent to the expression addTimezoneOffset(DisplayMode.MEDIUM, true, Collections.singletonList("Z")).

Returns:
this instance for method chaining

addTimezoneOffset

public ChronoFormatter.Builder<T> addTimezoneOffset(DisplayMode precision,
                                           boolean extended,
                                           List<String> zeroOffsets)

Adds a timezone offset in canonical notation.

This format element is also applicable on chronological entities without timezone reference like PlainTime provided that a timezone offset is set as format attribute. Dependent on given arguments following formats are defined:

	SHORT	MEDIUM	LONG	FULL
basic	±HH[mm]	±HHmm	±HHmm[ss[.{fraction}]]	±HHmmss[.{fraction}]
extended	±HH[:mm]	±HH:mm	±HH:mm[:ss[.{fraction}]]	±HH:mm:ss[.{fraction}]

Notes: All components given in square brackets are optional. They will only appear if they are different from 0. A fractional second part with 9 digits is always optional and is only possible in case of a longitudinal offset. The modes SHORT and MEDIUM correspond to ISO-8601 where an offset should only have hours and minutes.

The third argument determines what kind of text should be interpreted as zero offset. The formatted output always uses the first list entry while parsing expects any list entries.

Parameters:: precision - display mode of offset format; extended - extended or basic ISO-8601-mode; zeroOffsets - list of replacement texts if offset is zero
Returns:: this instance for method chaining
Throws:: IllegalArgumentException - if any replacement text consists of white-space only or if given replacement list is empty
See Also:: ChronoEntity.getTimezone()

addShortLocalizedOffset
```
public ChronoFormatter.Builder<T> addShortLocalizedOffset()
```
Adds a timezone offset in short localized notation.

This format element is also applicable on chronological entities without timezone reference like PlainTime provided that a timezone offset is set as format attribute. The format "GMT±H[:mm]" will be used.

Notes: The minute component given in square brackets is optional in short format and appears only if it is different from 0. The GMT-prefix can also be like "UTC" or "UT" when parsing. A localized GMT-notation is possible provided that the resource files "iso8601.properties" have an entry with the key "prefixGMTOffset".

Returns:
this instance for method chaining
See Also:
ChronoEntity.getTimezone(), addLongLocalizedOffset()

addLongLocalizedOffset
```
public ChronoFormatter.Builder<T> addLongLocalizedOffset()
```
Adds a timezone offset in long localized notation.

This format element is also applicable on chronological entities without timezone reference like PlainTime provided that a timezone offset is set as format attribute. The format "GMT±HH:mm" will be used.

Notes: The GMT-prefix can also be like "UTC" or "UT" when parsing. A localized GMT-notation is possible provided that the resource files "iso8601.properties" have an entry with the key "prefixGMTOffset".

Returns:
this instance for method chaining
See Also:
ChronoEntity.getTimezone(), addShortLocalizedOffset()

padNext
```
public ChronoFormatter.Builder<T> padNext(int width)
```
Defines for the next format element of the same section so many pad chars until the element width has reached the width specified.

Note: This method will be ignored if it is directly followed by a new section or if the current section is closed or if there are no more format elements.

Parameters:
width - fixed width of following format step

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given width is negative
See Also:
Attributes.PAD_CHAR, padPrevious(int)

padPrevious
```
public ChronoFormatter.Builder<T> padPrevious(int width)
```
Defines for the previous format element of the same section so many pad chars until the element width has reached the width specified.

Parameters:
width - fixed width of previous format step

Returns:
this instance for method chaining

Throws:

IllegalArgumentException - if given width is negative
See Also:
Attributes.PAD_CHAR, padNext(int)

startOptionalSection
```
public ChronoFormatter.Builder<T> startOptionalSection()
```
Starts a new optional section where errors in parsing will not cause an exception but just be ignored.

Returns:
this instance for method chaining

startOptionalSection
```
public ChronoFormatter.Builder<T> startOptionalSection(ChronoCondition<ChronoDisplay> printCondition)
```
Starts a new optional section where errors in parsing will not cause an exception but just be ignored.

Parameters:
printCondition - optional condition for printing

Returns:
this instance for method chaining

startSection
```
public ChronoFormatter.Builder<T> startSection(AttributeKey<Boolean> key,
 boolean value)
```
Starts a new section with given sectional attribute.

The new section takes over all attributes of current section if available. Sectional attributes cannot be overridden by the default attributes of ChronoFormatter.

Parameters:
key - attribute key
value - attribute value

Returns:
this instance for method chaining

startSection
```
public ChronoFormatter.Builder<T> startSection(AttributeKey<Integer> key,
 int value)
```
Starts a new section with given sectional attribute.

The new section takes over all attributes of current section if available. Sectional attributes cannot be overridden by the default attributes of ChronoFormatter.

Parameters:
key - attribute key
value - attribute value

Returns:
this instance for method chaining

startSection
```
public ChronoFormatter.Builder<T> startSection(AttributeKey<Character> key,
 char value)
```
Starts a new section with given sectional attribute.

The new section takes over all attributes of current section if available. Sectional attributes cannot be overridden by the default attributes of ChronoFormatter.

Parameters:
key - attribute key
value - attribute value

Returns:
this instance for method chaining

startSection
```
public <A extends Enum<A>> ChronoFormatter.Builder<T> startSection(AttributeKey<A> key,
 A value)
```
Starts a new section with given sectional attribute.

The new section takes over all attributes of current section if available. Sectional attributes cannot be overridden by the default attributes of ChronoFormatter.

Type Parameters:
A - generic type of attribute (enum-based)
Parameters:
key - attribute key
value - attribute value

Returns:
this instance for method chaining

endSection
```
public ChronoFormatter.Builder<T> endSection()
```
Removes the last sectional attribute.

Returns:
this instance for method chaining

Throws:

NoSuchElementException - if there is no section which was started with startSection()
See Also:
startSection(AttributeKey, boolean), startSection(AttributeKey, Enum), startSection(AttributeKey, int), startSection(AttributeKey, char)

build
```
public ChronoFormatter<T> build()
```
Finishes the build and creates a new ChronoFormatter.

Returns:
new ChronoFormatter-instance

Class ChronoFormatter.Builder<T extends ChronoEntity<T>>

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getChronology

addInteger

addInteger

addLongNumber

addFixedInteger

addNumerical

addFixedNumerical

addFraction

addFixedDecimal

addEnglishOrdinal

addOrdinal

addLiteral

addLiteral

addLiteral

addIgnorableWhitespace

addPattern

addText

addText

addText

addCustomized

addCustomized

addTwoDigitYear

addTimezoneID

addShortTimezoneName

addLongTimezoneName

addShortTimezoneName

addLongTimezoneName

addTimezoneOffset

addTimezoneOffset

addShortLocalizedOffset

addLongLocalizedOffset

padNext

padPrevious

startOptionalSection

startOptionalSection

startSection

startSection

startSection

startSection

endSection

build