Package 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 threadsafe so a new instance is necessary per thread. A new instance can be created by ChronoFormatter.setUp(Class, Locale).

Author:
Meno Hochschild

  • Method Details

    • 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-10
      maxDigits - maximum count of digits in range 1-10
      Returns:
      this instance for method chaining
      Throws:
      IllegalArgumentException - if any of minDigits and maxDigits are out of range 1-10 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 = 10.

      Note: The arguments minDigits and maxDigits will only be taken into account if a decimal 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-10
      maxDigits - maximum count of digits in range 1-10
      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-10 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-10
      Returns:
      this instance for method chaining
      Throws:
      IllegalArgumentException - if digits is out of range 1-10 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)

      Equivalent to addFixedDecimal(element, 11, 9).

      This method is mainly suitable for parsing. When printing the overloaded method with two extra integer arguments allow more control.

      Parameters:
      element - chronological element
      Returns:
      this instance for method chaining
      Since:
      3.29/4.25
      See Also:
      addFixedDecimal(ChronoElement, int, int)

    • 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. The strict mode also mandates precision - scale digits before the decimal separator. If the lax mode is applied then as many digits are parsed as available and found. The smart mode is strict before the decimal separator and lax after the decimal separator.

      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, Attributes.DECIMAL_SEPARATOR

    • 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:
      addEnglishOrdinal(ChronoElement), 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. If the argument is zero then the method is equivalent to setting the format attribute Attributes.TRAILING_CHARACTERS. 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.

      Notes: This method is only relevant for parsing. During printing, this method does nothing. The first condition argument must be immutable or even stateless (for example a lambda expression).

      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 enum PatternType.

      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 or its preparser
      See Also:
      Chronology.isSupported(ChronoElement)

    • addText

      public <V extends Enum<V>> ChronoFormatter.Builder<T> addText​(ChronoElement<V> element, Function<V,​String> converter)

      Defines a text format for given chronological element with a user-defined string conversion.

      Example for upper-case-conversion (here in English): 

           ChronoFormatter<PlainDate> formatter =
          ChronoFormatter.setUp(PlainDate.class, Locale.US)
              .addText(PlainDate.DAY_OF_WEEK, Enum::name)
              .build();
     assertThat(
          formatter.format(PlainDate.of(2015, 1, 3)),
          is("SATURDAY"));
      Type Parameters:
      V - generic type of enum element values
      Parameters:
      element - chronological element
      converter - text converter
      Returns:
      this instance for method chaining
      Throws:
      IllegalArgumentException - if given element is not supported by chronology or its preparser
      Since:
      5.0
      See Also:
      Chronology.isSupported(ChronoElement), addText(ChronoElement, Map)

    • addText

      public <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 or if there are not enough text resources to match all values of an enum element type
      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. Both winter- and summer-time-names will be processed.

      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), NameStyle.SHORT_STANDARD_TIME, NameStyle.SHORT_DAYLIGHT_TIME

    • 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. Both winter- and summer-time-names will be processed.

      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), NameStyle.LONG_STANDARD_TIME, NameStyle.LONG_DAYLIGHT_TIME

    • 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. Both winter- and summer-time-names will be processed.

      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), NameStyle.SHORT_STANDARD_TIME, NameStyle.SHORT_DAYLIGHT_TIME

    • 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. Both winter- and summer-time-names will be processed.

      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), NameStyle.LONG_STANDARD_TIME, NameStyle.LONG_DAYLIGHT_TIME

    • addTimezoneName

      public ChronoFormatter.Builder<T> addTimezoneName​(NameStyle style)

      Adds a localized timezone name in given style.

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

      Parameters:
      style - naming style
      Returns:
      this instance for method chaining
      Since:
      3.27/4.23
      See Also:
      addLongTimezoneName(), addShortTimezoneName()

    • addTimezoneName

      public ChronoFormatter.Builder<T> addTimezoneName​(NameStyle style, Set<TZID> preferredZones)

      Adds a localized timezone name in given style.

      The parsing of timezone names is case-sensitive.

      Parameters:
      style - naming style
      preferredZones - preferred timezone ids for resolving duplicates
      Returns:
      this instance for method chaining
      Since:
      3.27/4.23
      See Also:
      addLongTimezoneName(), addShortTimezoneName()

    • 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

      @Deprecated public ChronoFormatter.Builder<T> addTimezoneOffset​(DisplayMode precision, boolean extended, List<String> zeroOffsets)
      Deprecated.
      Use addTimezoneOffset(FormatStyle, boolean, List)

      Adds a timezone offset in canonical notation.

      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()

    • addTimezoneOffset

      public ChronoFormatter.Builder<T> addTimezoneOffset​(FormatStyle 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 - style 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
      Since:
      5.8
      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