net.time4j.format.expert

Class ChronoFormatter.Builder<T>

java.lang.Object

net.time4j.format.expert.ChronoFormatter.Builder<T>

Type Parameters:

T - generic type of chronological entity (subtype of ChronoEntity)

Enclosing class:

ChronoFormatter<T>

public static final class ChronoFormatter.Builder<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

Concurrency:

This class is mutable and hence intended for use in a single thread only.

Method Summary

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>	addDayPeriod(Map<PlainTime,String> timeToLabels) Defines a text format for a custom day period.
ChronoFormatter.Builder<T>	addDayPeriodApproximate() Defines a text format for a flexible day period (morning/afternoon etc).
ChronoFormatter.Builder<T>	addDayPeriodFixed() Defines a text format for a fixed day period (am/pm/midnight/noon).
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(char literal, char alt) Defines a literal element with exactly one char which can also be an alternative char during parsing.
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 (in specific non-location format).
ChronoFormatter.Builder<T>	addLongTimezoneName(Set<TZID> preferredZones) Adds a long localized timezone name (in specific non-location format).
<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, PatternType 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 in specific non-location format).
ChronoFormatter.Builder<T>	addShortTimezoneName(Set<TZID> preferredZones) Adds a short localized timezone name (an abbreviation in specific non-location format).
<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<T>	build(Attributes attributes) Finishes the build and creates a new ChronoFormatter.
ChronoFormatter.Builder<T>	endSection() Removes the last sectional attribute.
Chronology<?>	getChronology() Returns the calendar override if set else the associated chronology.
ChronoFormatter.Builder<T>	or() Starts a new block inside the current section such that the following parts will only be taken into account in case of failure according to or-logic.
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.
<V> ChronoFormatter.Builder<T>	setDefault(ChronoElement<V> element, V value) Defines a default value if the parser has not parsed or found a value for given element.
<V> ChronoFormatter.Builder<T>	setDefaultSupplier(ChronoElement<V> element, Supplier<V> supplier) Defines a supplier for a default value if the parser has not parsed or found a value for given element.
ChronoFormatter.Builder<T>	skipUnknown(int keepRemainingChars) Skips all characters from input as unparseable until at least given count of characters is left.
ChronoFormatter.Builder<T>	skipUnknown(IntPredicate unparseableCondition, int maxIterations) Skips all characters accepted by given condition as unparseable.
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

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getChronology

public Chronology<?> getChronology()

Returns the calendar override if set else the associated chronology.

Returns:

Chronology

Since:

3.11/4.8

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.

Note: The argument maxDigits will only be taken into account if the arabic number system is used.

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 decimal 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 but only in strict mode. 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, "<sup>er</sup>");
  indicators.put(PluralCategory.OTHER, "<sup>e</sup>");

  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: 1<sup>er</sup> 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.

Equivalent to addLiteral(String.valueOf(literal)).

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(char literal,
                                             char alt)

Defines a literal element with exactly one char which can also be an alternative char during parsing.

The literal char is a punctuation mark or a letter symbol. Decimal digits as literal chars are not permitted.

Parameters:

literal - single non-digit literal char (preferred in printing)

alt - alternative non-digit literal char for parsing

Returns:

this instance for method chaining

Throws:

IllegalArgumentException - if any char represents a non-printable ASCII-char or a decimal digit

Since:

3.1

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. Exceptionally, digit chars are possible although such chars will only be parsed as literals and not associated with any chronological meaning.

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 which must be a non-digit 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

skipUnknown

public ChronoFormatter.Builder<T> skipUnknown(int keepRemainingChars)

Skips all characters from input as unparseable until at least given count of characters is left.

Note: This method is only relevant for parsing. During printing, this method does nothing.

Parameters:

keepRemainingChars - minimum count of characters which should be reserved for following steps

Returns:

this instance for method chaining

Throws:

IllegalArgumentException - if keepRemainingChars < 0

Since:

3.18/4.14

See Also:

skipUnknown(IntPredicate, int), Attributes.TRAILING_CHARACTERS

skipUnknown

public ChronoFormatter.Builder<T> skipUnknown(IntPredicate unparseableCondition,
                                              int maxIterations)

Skips all characters accepted by given condition as unparseable.

Every input character will be handled by given condition as code point. If the condition always returns true then maxIterations effectively models a fixed width of characters to be skipped.

Note: This method is only relevant for parsing. During printing, this method does nothing.

Parameters:

unparseableCondition - condition which marks accepted characters as unparseable

maxIterations - maximum count of invocations on given condition

Returns:

this instance for method chaining

Throws:

IllegalArgumentException - if maxIterations < 1

Since:

4.14

See Also:

skipUnknown(int)

addPattern

public ChronoFormatter.Builder<T> addPattern(String formatPattern,
                                             PatternType 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 char "|" starts a new or-block. And 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)

addDayPeriodFixed

public ChronoFormatter.Builder<T> addDayPeriodFixed()

Defines a text format for a fixed day period (am/pm/midnight/noon).

Returns:

this instance for method chaining

Throws:

IllegalStateException - if the underlying chronology does not support day periods

Since:

3.13/4.10

See Also:

DayPeriod.fixed()

addDayPeriodApproximate

public ChronoFormatter.Builder<T> addDayPeriodApproximate()

Defines a text format for a flexible day period (morning/afternoon etc).

Returns:

this instance for method chaining

Throws:

IllegalStateException - if the underlying chronology does not support day periods

Since:

3.13/4.10

See Also:

DayPeriod.approximate()

addDayPeriod

public ChronoFormatter.Builder<T> addDayPeriod(Map<PlainTime,String> timeToLabels)

Defines a text format for a custom day period.

Parameters:

timeToLabels - mapping from start times to custom dayperiod labels

Returns:

this instance for method chaining

Throws:

IllegalStateException - if already called once or if the underlying chronology does not support day periods

IllegalArgumentException - if given map is empty or contains empty values

Since:

3.13/4.10

See Also:

DayPeriod.of(Map)

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.

Equivalent to addCustomized(element, formatter, formatter).

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(ChronoElement, ChronoPrinter, ChronoParser)

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.

If the printer or the parser are of type ChronoFormatter then the outer format attributes and default values will be overtaken by the embedded printer or parser.

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 - if the underlying chronology does not correspond to the type UnixTime

addShortTimezoneName

public ChronoFormatter.Builder<T> addShortTimezoneName()

Adds a short localized timezone name (an abbreviation in specific non-location format).

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

Throws:

IllegalStateException - if the underlying chronology does not correspond to the type UnixTime

See Also:

addShortTimezoneName(Set)

addLongTimezoneName

public ChronoFormatter.Builder<T> addLongTimezoneName()

Adds a long localized timezone name (in specific non-location format).

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

Throws:

IllegalStateException - if the underlying chronology does not correspond to the type UnixTime

See Also:

addLongTimezoneName(Set)

addShortTimezoneName

public ChronoFormatter.Builder<T> addShortTimezoneName(Set<TZID> preferredZones)

Adds a short localized timezone name (an abbreviation in specific non-location format).

Parsing of timezone names is case-sensitive.

Parameters:

preferredZones - preferred timezone ids for resolving duplicates

Returns:

this instance for method chaining

Throws:

IllegalStateException - if the underlying chronology does not correspond to the type UnixTime

See Also:

addLongTimezoneName(Set)

addLongTimezoneName

public ChronoFormatter.Builder<T> addLongTimezoneName(Set<TZID> preferredZones)

Adds a long localized timezone name (in specific non-location format).

Parsing of timezone names is case-sensitive.

Parameters:

preferredZones - preferred timezone ids for resolving duplicates

Returns:

this instance for method chaining

Throws:

IllegalStateException - if the underlying chronology does not correspond to the type UnixTime

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:

Legend

	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. During printing, they will only appear if they are different from 0. During parsing, they can be left out of the text to be parsed. A fractional second part with 9 digits is always optional (unless a dot exists) 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 hour part might consist of one digit only if the parsing mode is not strict.

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[:ss]]" 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 "tzname.properties" have an entry with the key "offset-pattern". If the format attribute Attributes.NO_GMT_PREFIX is set to true then the GMT-prefix will be suppressed. The format attribute Attributes.ZERO_DIGIT (usually set indirect via the locale) controls which localized set of digits will be used. The sign is possibly localized, too.

Returns:

this instance for method chaining

See Also:

ChronoEntity.getTimezone(), addLongLocalizedOffset(), Attributes.NO_GMT_PREFIX

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[:ss]" 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 "tzname.properties" have an entry with the key "offset-pattern". If the format attribute Attributes.NO_GMT_PREFIX is set to true then the GMT-prefix will be suppressed. The format attribute Attributes.ZERO_DIGIT (usually set indirect via the locale) controls which localized set of digits will be used. The sign is possibly localized, too.

Returns:

this instance for method chaining

See Also:

ChronoEntity.getTimezone(), addShortLocalizedOffset(), Attributes.NO_GMT_PREFIX

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.

Note: Printing is not optional and will always be enabled.

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.

Printing will only happen if given condition is true.

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)

or

public ChronoFormatter.Builder<T> or()

Starts a new block inside the current section such that the following parts will only be taken into account in case of failure according to or-logic.

Example of usage (here with format pattern char "|"):

   ChronoFormatter<PlainDate> f =
       ChronoFormatter.ofDatePattern("E, [dd.MM.|MM/dd/]uuuu", PatternType.CLDR, Locale.ENGLISH);
       PlainDate expected = PlainDate.of(2015, 12, 31);
       assertThat(f.parse("Thu, 31.12.2015"), is(expected));
       assertThat(f.parse("Thu, 12/31/2015"), is(expected));
 

Note: Or-blocks can also be used outside of an optional section.

General notes about usage:

a) If two patterns are combined then the order must be from the most complete pattern to the least complete one. Example: Use "MM/dd/yyyy HH:mm|MM/dd/yyyy" and not "MM/dd/yyyy|MM/dd/yyyy HH:mm". This is especially important if the formatter in question use default values because the single components will be processed before evaluating any default values (which is a late step in parsing).

b) If two patterns have the same degree of completeness then that component should be noted first which is more likely to be expected in input.

Returns:

this instance for method chaining

Throws:

IllegalStateException - if called twice or called after the end of an optional section or if there is not yet any defined format step in current section

Since:

3.14/4.11

setDefault

public <V> ChronoFormatter.Builder<T> setDefault(ChronoElement<V> element,
                                                 V value)

Defines a default value if the parser has not parsed or found a value for given element.

Type Parameters:

V - generic element value type

Parameters:

element - chronological element

value - replacement value, not null

Returns:

this instance for method chaining

Throws:

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

Since:

3.22/4.18

setDefaultSupplier

public <V> ChronoFormatter.Builder<T> setDefaultSupplier(ChronoElement<V> element,
                                                         Supplier<V> supplier)

Defines a supplier for a default value if the parser has not parsed or found a value for given element.

Type Parameters:

V - generic element value type

Parameters:

element - chronological element

supplier - supplier for replacement value, not null

Returns:

this instance for method chaining

Throws:

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

Since:

3.22/4.18

build

public ChronoFormatter<T> build()

Finishes the build and creates a new ChronoFormatter.

Returns:

new ChronoFormatter-instance with standard global format attributes

Throws:

IllegalStateException - if there is no format element at all or none after or-operator in same section

build

public ChronoFormatter<T> build(Attributes attributes)

Finishes the build and creates a new ChronoFormatter.

Parameters:

attributes - new set of global format attributes

Returns:

new ChronoFormatter-instance

Throws:

IllegalStateException - if there is no format element at all or none after or-operator in same section

Since:

3.22/4.18