Package net.time4j.format.expert

Class ChronoFormatter<T>

java.lang.Object
net.time4j.format.expert.ChronoFormatter<T>
Type Parameters:
T - generic type of chronological entity
All Implemented Interfaces:
ChronoParser<T>, ChronoPrinter<T>, TemporalFormatter<T>
public final class ChronoFormatter<T> extends Object implements ChronoPrinter<T>, ChronoParser<T>, TemporalFormatter<T>

Represents a chronological format for the conversion between a chronological text and the chronological value of type T.

An instance can either be created via a Builder obtainable by setUp(Class, Locale) or by some static factory methods. The class Iso8601Format provides additional formatters adapted for the ISO-8601-standard.

Interoperability note:

The static methods setUp(Chronology, Locale) and ofPattern(String, PatternType, Locale, Chronology) also allow the usage of foreign types by specifying a suitable bridge chronology. Even the old type java.util.Date can be used in conjunction with this formatter. Example: 

     ChronoFormatter<java.util.Date> f =
          ChronoFormatter.ofPattern(
              "MM/dd/yyyy",
              PatternType.CLDR,
              Locale.US,
              Moment.axis(TemporalType.JAVA_UTIL_DATE))
          .withDefault(PlainTime.COMPONENT, PlainTime.midnightAtStartOfDay())
          .withStdTimezone();
     System.out.println(f.format(new java.util.Date()));
     java.util.Date d = f.parse("10/26/2016");

Support for unicode extensions:

nu
All number systems listed in the enum NumberSystem support the nu-extension. Example: Locale.forLanguageTag(&quot;th-TH-u-nu-thai&quot;) will use Thai numerals in printing and parsing. Normally the number system is determined by the language and country but the nu-extension enables to override the default.
ca
All calendars compatible with the CLDR-pattern support the ca-extension. The support is realized by all static factory methods with the name ofGenericXYZ(...). Example: The expression ofGenericCalendarStyle(DisplayMode.FULL, Locale.forLanguageTag(&quot;ar-SA-u-ca-islamic-umalqura&quot;)) will use the calendar of Saudi-Arabia in printing and parsing.
Since:
3.0
Author:
Meno Hochschild

  • Field Details

    • RFC_1123

      public static final ChronoFormatter<Moment> RFC_1123

      Special formatter for printing or parsing moments according to the RFC-1123-specification.

      Note: Military timezones with the exception of Z (=UTC) are NOT supported because the specification had originally given the offset signs in reverse way from UTC (an error in RFC-822). However, north american timezone names are supported (EST/EDT/CST/CDT/MST/MDT/PST/PDT).

      Since:
      3.26/4.22

  • Method Details

    • getChronology

      public Chronology<T> getChronology()

      Returns the associated chronology.

      Returns:
      chronology to be used for formatting associated objects

    • getLocale

      public Locale getLocale()

      Returns the locale setting.

      If there is just a reference to ISO-8601 without any concrete language then this method will yield Locale.ROOT.

      Returns:
      Locale (empty if related to ISO-8601, never null)

    • getPattern

      public String getPattern()

      Returns the format pattern when this formatter was constructed by pattern.

      If no pattern was used then this method will only yield an empty string. This is also true if more than one pattern was used via the builder so that there is no longer a unique pattern.

      If this formatter is style-based then this method can find the generated format pattern although the format attribute for patterns is not filled for style-based formatters.

      Returns:
      pattern string, maybe empty
      Since:
      5.8
      See Also:
      Attributes.FORMAT_PATTERN

    • getAttributes

      public AttributeQuery getAttributes()

      Returns the global format attributes which are active if they are not overridden by sectional attributes.

      The global attributes can be adjusted by a suitable with()-method. Following attributes are predefined:

      Legend
      Attributes.CALENDAR_TYPE read-only, dependent on associated chronology
      Attributes.LANGUAGE dependent on associated locale
      Attributes.DECIMAL_SEPARATOR dependent on associated locale
      Attributes.ZERO_DIGIT dependent on associated locale
      Attributes.LENIENCY Leniency.SMART
      Attributes.PARSE_CASE_INSENSITIVE true
      Attributes.PARSE_PARTIAL_COMPARE false
      Attributes.TEXT_WIDTH TextWidth.WIDE
      Attributes.OUTPUT_CONTEXT OutputContext.FORMAT
      Attributes.PAD_CHAR (SPACE)
      Specified by:
      getAttributes in interface ChronoParser<T>
      Specified by:
      getAttributes in interface ChronoPrinter<T>
      Specified by:
      getAttributes in interface TemporalFormatter<T>
      Returns:
      global control attributes valid for the whole formatter (can be overridden by sectional attributes however)
      See Also:
      getChronology(), getLocale()

    • print

      public String print​(T formattable)
      Description copied from interface: ChronoPrinter

      Prints given chronological entity as formatted text.

      Specified by:
      print in interface ChronoPrinter<T>
      Specified by:
      print in interface TemporalFormatter<T>
      Parameters:
      formattable - object to be formatted
      Returns:
      formatted text

    • format

      public String format​(GeneralTimestamp<?> tsp)

      Prints given general timestamp.

      Parameters:
      tsp - general timestamp as combination of a date and a time
      Returns:
      formatted string
      Throws:
      IllegalArgumentException - if the timestamp is not formattable with this formatter
      Since:
      3.11/4.8

    • print

      public Set<ElementPosition> print​(T formattable, StringBuilder buffer, AttributeQuery attributes)
      Description copied from interface: ChronoPrinter

      Prints given chronological entity as formatted text and writes the text into given buffer.

      Specified by:
      print in interface ChronoPrinter<T>
      Parameters:
      formattable - object to be formatted
      buffer - text output buffer
      attributes - format attributes which can control formatting
      Returns:
      unmodifiable set of element positions in formatted text, maybe empty

    • print

      public Set<ElementPosition> print​(T formattable, Appendable buffer, AttributeQuery attributes) throws IOException

      Prints given chronological entity as formatted text and writes the text into given buffer.

      The given attributes cannot change the inner format structure (for example not change a localized weekmodel), but can override some format properties like language or certain text attributes for this run only.

      Parameters:
      formattable - object to be formatted
      buffer - text output buffer
      attributes - attributes for limited formatting control
      Returns:
      unmodifiable set of element positions in formatted text
      Throws:
      IllegalArgumentException - if given object is not formattable
      IOException - if writing to buffer fails

    • parse

      public T parse​(CharSequence text) throws ParseException
      Description copied from interface: ChronoParser

      Interpretes given text as chronological entity starting at the begin of text.

      Specified by:
      parse in interface ChronoParser<T>
      Specified by:
      parse in interface TemporalFormatter<T>
      Parameters:
      text - text to be parsed
      Returns:
      parse result
      Throws:
      ParseException - if the text is not parseable

    • parse

      public T parse​(CharSequence text, ParseLog status)
      Description copied from interface: ChronoParser

      Interpretes given text as chronological entity starting at the specified position in parse log.

      Equivalent to parse(text, status, getAttributes()).

      Specified by:
      parse in interface ChronoParser<T>
      Parameters:
      text - text to be parsed
      status - parser information (always as new instance)
      Returns:
      result or null if parsing does not work

    • parse

      public T parse​(CharSequence text, RawValues rawValues) throws ParseException
      Description copied from interface: TemporalFormatter

      Interpretes given text as chronological entity and updates given raw values.

      Specified by:
      parse in interface TemporalFormatter<T>
      Parameters:
      text - text to be parsed
      rawValues - holder for raw values (always as new instance)
      Returns:
      parsed result
      Throws:
      ParseException - if parsing does not work

    • parse

      public T parse​(CharSequence text, ParseLog status, AttributeQuery attributes)

      Interpretes given text as chronological entity starting at the specified position in parse log.

      The given attributes cannot change the inner format structure (for example not change a localized weekmodel), but can override some format properties like expected language or certain text attributes for this run only.

      Specified by:
      parse in interface ChronoParser<T>
      Parameters:
      text - text to be parsed
      status - parser information (always as new instance)
      attributes - attributes for limited parsing control
      Returns:
      result or null if parsing does not work
      Throws:
      IndexOutOfBoundsException - if the start position is at end of text or even behind

    • parseRaw

      public ChronoEntity<?> parseRaw​(String text)

      Translates given text as raw chronological entity without converting to the target type of the underlying chronology.

      Parameters:
      text - text to be parsed
      Returns:
      new map-like mutable entity (empty if parsing does not work)
      Since:
      2.0

    • parseRaw

      public ChronoEntity<?> parseRaw​(CharSequence text, int offset)

      Translates given text as raw chronological entity without converting to the target type of the underlying chronology.

      Parameters:
      text - text to be parsed
      offset - start position
      Returns:
      new map-like mutable entity (empty if parsing does not work)
      Since:
      2.0

    • with

      public ChronoFormatter<T> with​(Locale locale)

      Creates a copy of this formatter with given locale.

      Note: Sectional attributes will never be overridden. Is the locale not changed then the method will simply return this instance. Otherwise the copy will contain given locale and also adjusts the associated numerical symbols:

      Example for the support of unicode-nu-extension since v4.24: The parameter Locale.forLanguageTag("th-TH-u-nu-" + NumberSystem.THAI.getCode()) will set the Thai numbering system.

      If necessary all inner format elements which are locale-dependent will also be adjusted. Some country-specific extensions like Weekmodel.weekOfYear() or ChronoHistory.era() will only be adjusted if the country-part of given locale is not empty. However, fixed literals will remain unchanged hence this method might not be suitable for all languages. Example:

      new Locale("sv") will only change the language to swedish with no side effects, but new Locale("sv", "SE") will also set the week model and the historical swedish calendar which can be relevant for the years 1700-1712.

      Important: This method cannot adjust localized format patterns which were maybe generated by applying a format style like DisplayMode.FULL. Users have to call the style factory method again with different locale parameter in this case.

      Specified by:
      with in interface TemporalFormatter<T>
      Parameters:
      locale - new language and country configuration
      Returns:
      changed copy with given language and localized symbols while this instance remains unaffected
      Throws:
      IllegalArgumentException - if an unicode extension is not recognized or supported

    • with

      public ChronoFormatter<T> with​(Leniency leniency)
      Description copied from interface: TemporalFormatter

      Sets the leniency mode.

      By default any temporal formatter is smart.

      Specified by:
      with in interface TemporalFormatter<T>
      Parameters:
      leniency - determines how strict the parser should be
      Returns:
      changed copy with the new or changed attribute while this instance remains unaffected
      See Also:
      Attributes.LENIENCY

    • withAlternativeEraNames

      public ChronoFormatter<T> withAlternativeEraNames()

      Creates a copy of this formatter with alternative era names.

      Notes: Sectional attributes cannot be overridden. This method is only applicable for the gregorian calendar and its ancestors but not for other calendars which use eras different from HistoricEra.

      Returns:
      changed copy with alternative era names while this instance remains unaffected
      Since:
      3.0
      See Also:
      HistoricEra.getAlternativeName(Locale, TextWidth)

    • withLatinEraNames

      public ChronoFormatter<T> withLatinEraNames()

      Creates a copy of this formatter with latin era names.

      Note: Sectional attributes cannot be overridden.

      Returns:
      changed copy with latin era names while this instance remains unaffected
      Since:
      3.1

    • withGregorianCutOver

      public ChronoFormatter<T> withGregorianCutOver​(PlainDate date)

      Short-cut for with(ChronoHistory.ofGregorianReform(date)).

      Parameters:
      date - first gregorian date after gregorian calendar reform takes effect
      Returns:
      changed copy with given date of gregorian calendar reform while this instance remains unaffected
      Throws:
      IllegalArgumentException - if given date is before first introduction of gregorian calendar on 1582-10-15 and not the minimum on the date axis
      Since:
      3.0
      See Also:
      ChronoHistory.ofGregorianReform(PlainDate), with(ChronoHistory)

    • with

      public ChronoFormatter<T> with​(ChronoHistory history)

      Creates a copy of this formatter with the given chronological history of gregorian calendar reforms.

      Note that this configuration will override any gregorian cutover date which might be inferred from current locale.

      Parameters:
      history - chronological history describing historical calendar reforms
      Returns:
      changed copy with given history while this instance remains unaffected
      Since:
      3.1

    • with

      public ChronoFormatter<T> with​(Timezone tz)

      Creates a copy of this formatter with given timezone which shall be used in formatting or parsing.

      The timezone is in most cases only relevant for the type Moment. When formatting the timezone helps to convert the UTC value into a zonal representation. When parsing the timezone serves either as replacement value if the formatted text does not contain any timezone. Or it helps to resolve possibly ambivalent zone informations. Example: 

           // IST might also be Dublin/Ireland or Kolkata/India
     String input = "Dec 31 07:30:00 IST 2016";
     ChronoFormatter<Moment> f =
       ChronoFormatter.setUp(Moment.axis(), Locale.ENGLISH)
       .addPattern("MMM dd HH:mm:ss z yyyy", PatternType.CLDR)
       .build();
     assertThat(
       f.withTimezone(ASIA.JERUSALEM).parse(input), // preference for Israel Time set
       is(PlainTimestamp.of(2016, 12, 31, 5, 30).atUTC()));
      Parameters:
      tz - timezone
      Returns:
      changed copy with the new or changed timezone while this instance remains unaffected
      Since:
      3.11/4.8
      See Also:
      Attributes.TIMEZONE_ID, Attributes.TRANSITION_STRATEGY

    • withTimezone

      public ChronoFormatter<T> withTimezone​(TZID tzid)

      Equivalent to with(Timezone.of(tzid)).

      Specified by:
      withTimezone in interface TemporalFormatter<T>
      Parameters:
      tzid - timezone id
      Returns:
      changed copy with the new or changed attribute while this instance remains unaffected
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      See Also:
      Attributes.TIMEZONE_ID

    • withTimezone

      public ChronoFormatter<T> withTimezone​(String tzid)

      Equivalent to with(Timezone.of(tzid)).

      Specified by:
      withTimezone in interface TemporalFormatter<T>
      Parameters:
      tzid - timezone id
      Returns:
      changed copy with the new or changed attribute while this instance remains unaffected
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      1.1
      See Also:
      TemporalFormatter.withTimezone(TZID), Attributes.TIMEZONE_ID

    • withStdTimezone

      public ChronoFormatter<T> withStdTimezone()

      Equivalent to with(Timezone.ofSystem()).

      Returns:
      changed copy with the system timezone while this instance remains unaffected

    • withCalendarVariant

      public ChronoFormatter<T> withCalendarVariant​(String variant)

      Sets the calendar variant.

      Some calendars like HijriCalendar require the variant otherwise they cannot be successfully parsed.

      Parameters:
      variant - name of new calendar variant
      Returns:
      changed copy with the calendar variant while this instance remains unaffected
      Since:
      3.5/4.3
      See Also:
      Attributes.CALENDAR_VARIANT

    • withCalendarVariant

      public ChronoFormatter<T> withCalendarVariant​(VariantSource variantSource)

      Sets the calendar variant.

      Some calendars like HijriCalendar require the variant otherwise they cannot be successfully parsed.

      Parameters:
      variantSource - source of new calendar variant
      Returns:
      changed copy with the given calendar variant while this instance remains unaffected
      Since:
      3.6/4.4
      See Also:
      Attributes.CALENDAR_VARIANT

    • with

      public ChronoFormatter<T> with​(StartOfDay startOfDay)

      Sets the start of calendar day.

      Parameters:
      startOfDay - new start of day
      Returns:
      changed copy with the given start of day while this instance remains unaffected
      Since:
      3.11/4.8
      See Also:
      Attributes.START_OF_DAY

    • withDefault

      public <V> ChronoFormatter<T> withDefault​(ChronoElement<V> element, V value)

      Determines a default replacement value for given element.

      Example: 

        ChronoFormatter<PlainDate> fmt =
      ChronoFormatter.ofDatePattern("MM-dd", PatternType.CLDR, Locale.getDefault())
          .withDefault(PlainDate.YEAR, 2012);
  PlainDate date = fmt.parse("05-21");
  System.out.println(date); // 2012-05-21

      Default replacement values will be considered by Time4J if either the formatter does not contain the element in question at all or if there are no consumable characters for given element. Latter situation might sometimes require the use of sectional attribute PROTECTED_CHARACTERS in order to simulate an end-of-text situation.

      Type Parameters:
      V - generic element value type
      Parameters:
      element - chronological element to be updated
      value - replacement value or null if the default value shall be deregistered
      Returns:
      changed copy with new replacement value
      Throws:
      IllegalArgumentException - if given element is not supported by the underlying chronology
      See Also:
      Attributes.PROTECTED_CHARACTERS

    • withDefaultSupplier

      public <V> ChronoFormatter<T> withDefaultSupplier​(ChronoElement<V> element, Supplier<V> supplier)

      Determines a supplier for a default replacement value of given element.

      Example: 

        ChronoFormatter<PlainTimestamp> fmt =
      ChronoFormatter.ofTimestampPattern("HH:mm", PatternType.CLDR, Locale.ROOT)
          .withDefaultSupplier(PlainDate.COMPONENT, () -> SystemClock.inLocalView().today());
  PlainTimestamp tsp = fmt.parse("14:45");
  System.out.println(tsp); // 2012-05-21T14:45 (example for parsed time on today)

      Default replacement values will be considered by Time4J if either the formatter does not contain the element in question at all or if there are no consumable characters for given element. Latter situation might sometimes require the use of sectional attribute PROTECTED_CHARACTERS in order to simulate an end-of-text situation.

      Type Parameters:
      V - generic element value type
      Parameters:
      element - chronological element to be updated
      supplier - supplier for replacement value or null if the default value shall be deregistered
      Returns:
      changed copy with new replacement value
      Throws:
      IllegalArgumentException - if given element is not supported by the underlying chronology
      Since:
      4.14
      See Also:
      Attributes.PROTECTED_CHARACTERS

    • withDefaultSource

      public <V> ChronoFormatter<T> withDefaultSource​(ChronoElement<V> element, ChronoElement<V> source)

      Determines a source reference in parsed data for a default replacement value of given element.

      Default replacement values will be considered by Time4J if either the formatter does not contain the element in question at all or if there are no consumable characters for given element. Latter situation might sometimes require the use of sectional attribute PROTECTED_CHARACTERS in order to simulate an end-of-text situation.

      Type Parameters:
      V - generic element value type
      Parameters:
      element - chronological element to be updated
      source - element reference in parsed data whose value serves as replacement value or null if the default value shall be deregistered
      Returns:
      changed copy with new replacement value
      Throws:
      IllegalArgumentException - if the first argument is not supported by the underlying chronology or if both arguments are equal
      Since:
      4.20
      See Also:
      Attributes.PROTECTED_CHARACTERS

    • with

      public ChronoFormatter<T> with​(AttributeKey<Boolean> key, boolean value)

      Creates a copy of this formatter with given boolean-attribute.

      Note: Sectional attributes cannot be overridden.

      Parameters:
      key - attribute key
      value - attribute value
      Returns:
      changed copy with the new or changed attribute while this instance remains unaffected

    • with

      public ChronoFormatter<T> with​(AttributeKey<Integer> key, int value)

      Creates a copy of this formatter with given int-attribute.

      Note: Sectional attributes cannot be overridden.

      Parameters:
      key - attribute key
      value - attribute value
      Returns:
      changed copy with the new or changed attribute while this instance remains unaffected

    • with

      public ChronoFormatter<T> with​(AttributeKey<Character> key, char value)

      Creates a copy of this formatter with given char-attribute.

      Note: Sectional attributes cannot be overridden.

      Parameters:
      key - attribute key
      value - attribute value
      Returns:
      changed copy with the new or changed attribute while this instance remains unaffected

    • with

      public <A extends Enum<A>> ChronoFormatter<T> with​(AttributeKey<A> key, A value)

      Creates a copy of this formatter with given enum-attribute.

      Note: Sectional attributes cannot be overridden.

      Type Parameters:
      A - generic attribute value type
      Parameters:
      key - attribute key
      value - attribute value
      Returns:
      changed copy with the new or changed attribute while this instance remains unaffected

    • with

      public ChronoFormatter<T> with​(Attributes attributes)

      Creates a copy of this formatter with given standard attributes.

      Note: Sectional attributes cannot be overridden.

      Parameters:
      attributes - new default attributes
      Returns:
      changed copy with the new or changed attributes while this instance remains unaffected

    • toFormat

      public Format toFormat()

      Converts this formatter into a traditional java.text.Format-object.

      The returned format object also supports attributed strings such that all ChronoElement-structures are associated with field attributes of type DateFormat.Field. In ISO systems following mapping will be applied:

      Note: The returned Format-object is not serializable.

      Returns:
      new non-serializable java.text.Format-object which delegates all formatting and parsing work to this instance

    • ofDatePattern

      public static ChronoFormatter<PlainDate> ofDatePattern​(String pattern, PatternType type, Locale locale)

      Constructs a pattern-based formatter for plain date objects.

      Parameters:
      pattern - format pattern
      type - the type of the pattern to be used
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if resolving of pattern fails
      Since:
      3.1
      See Also:
      ofPattern(String, PatternType, Locale, Chronology)

    • ofTimePattern

      public static ChronoFormatter<PlainTime> ofTimePattern​(String pattern, PatternType type, Locale locale)

      Constructs a pattern-based formatter for clock time objects.

      Parameters:
      pattern - format pattern
      type - the type of the pattern to be used
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if resolving of pattern fails
      Since:
      3.1
      See Also:
      ofPattern(String, PatternType, Locale, Chronology)

    • ofTimestampPattern

      public static ChronoFormatter<PlainTimestamp> ofTimestampPattern​(String pattern, PatternType type, Locale locale)

      Constructs a pattern-based formatter for plain timestamps.

      Parameters:
      pattern - format pattern
      type - the type of the pattern to be used
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if resolving of pattern fails
      Since:
      3.1
      See Also:
      ofPattern(String, PatternType, Locale, Chronology)

    • ofMomentPattern

      public static ChronoParser<Moment> ofMomentPattern​(String pattern, PatternType type, Locale locale)

      Constructs a pattern-based parser for global timestamp objects.

      The input to be parsed must contain any timezone or offset information for successful parsing.

      Parameters:
      pattern - format pattern
      type - the type of the pattern to be used
      locale - format locale
      Returns:
      new format object for formatting Moment-objects using given locale and timezone
      Throws:
      IllegalArgumentException - if resolving of pattern fails
      Since:
      3.28/4.24
      See Also:
      ofMomentPattern(String, PatternType, Locale, TZID)

    • ofMomentPattern

      public static ChronoFormatter<Moment> ofMomentPattern​(String pattern, PatternType type, Locale locale, TZID tzid)

      Constructs a pattern-based formatter for global timestamp objects.

      The given timezone parameter can help to compensate missing timezone or offset informations in input or to resolve possibly ambivalent timezone names in input.

      Parameters:
      pattern - format pattern
      type - the type of the pattern to be used
      locale - format locale
      tzid - timezone id
      Returns:
      new format object for formatting Moment-objects using given locale and timezone
      Throws:
      IllegalArgumentException - if resolving of pattern fails or the timezone cannot be loaded
      Since:
      3.1
      See Also:
      ofPattern(String, PatternType, Locale, Chronology)

    • ofPattern

      public static <T> ChronoFormatter<T> ofPattern​(String pattern, PatternType type, Locale locale, Chronology<T> chronology)

      Constructs a pattern-based formatter for general chronologies.

      If given pattern type is equal to CLDR or derived from CLDR then an additional sanity check will be performed such that following combinations of symbols are excluded:

      • "h" or "K" without "a" or "b" or "B" (12-hour-clock requires am/pm-marker or dayperiod)
      • "Y" with "M" or "L" but without "w" (Y as week-based-year requires a week-date-format)
      • "D" with "M" or "L" but without "d" (D is the day of year but not the day of month)

      Note that this check will only be done here but not on builder level (since v4.20). The check does not claim to find all insane combinations of symbols but intends to prevent at least the most wide-spread pattern errors.

      Type Parameters:
      T - generic chronological type
      Parameters:
      pattern - format pattern
      type - the type of the pattern to be used
      locale - format locale
      chronology - chronology with format pattern support
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if resolving of pattern fails
      Since:
      3.14/4.11
      See Also:
      ChronoFormatter.Builder.addPattern(String, PatternType)

    • ofDateStyle

      @Deprecated public static ChronoFormatter<PlainDate> ofDateStyle​(DisplayMode style, Locale locale)
      Deprecated.
      Use ofDateStyle(FormatStyle, Locale)

      Constructs a style-based formatter for plain date objects.

      Parameters:
      style - format style
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      3.10/4.7
      See Also:
      CalendarText.patternForDate(DisplayMode, Locale)

    • ofDateStyle

      public static ChronoFormatter<PlainDate> ofDateStyle​(FormatStyle style, Locale locale)

      Constructs a style-based formatter for plain date objects.

      Parameters:
      style - format style
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      5.8
      See Also:
      CalendarText.patternForDate(FormatStyle, Locale)

    • ofTimeStyle

      @Deprecated public static ChronoFormatter<PlainTime> ofTimeStyle​(DisplayMode style, Locale locale)
      Deprecated.
      Use ofTimeStyle(FormatStyle, Locale)

      Constructs a style-based formatter for plain time objects.

      Parameters:
      style - format style
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      3.10/4.7
      See Also:
      CalendarText.patternForTime(DisplayMode, Locale)

    • ofTimeStyle

      public static ChronoFormatter<PlainTime> ofTimeStyle​(FormatStyle style, Locale locale)

      Constructs a style-based formatter for plain time objects.

      Parameters:
      style - format style
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      5.8
      See Also:
      CalendarText.patternForTime(FormatStyle, Locale)

    • ofTimestampStyle

      @Deprecated public static ChronoFormatter<PlainTimestamp> ofTimestampStyle​(DisplayMode dateStyle, DisplayMode timeStyle, Locale locale)
      Deprecated.
      Use ofTimestampStyle(FormatStyle, FormatStyle, Locale)

      Constructs a style-based formatter for plain timestamps.

      Parameters:
      dateStyle - format style of date part
      timeStyle - format style of time part
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      3.10/4.7
      See Also:
      CalendarText.patternForTimestamp(DisplayMode, DisplayMode, Locale)

    • ofTimestampStyle

      public static ChronoFormatter<PlainTimestamp> ofTimestampStyle​(FormatStyle dateStyle, FormatStyle timeStyle, Locale locale)

      Constructs a style-based formatter for plain timestamps.

      Parameters:
      dateStyle - format style of date part
      timeStyle - format style of time part
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      5.8
      See Also:
      CalendarText.patternForTimestamp(FormatStyle, FormatStyle, Locale)

    • ofMomentStyle

      @Deprecated public static ChronoFormatter<Moment> ofMomentStyle​(DisplayMode dateStyle, DisplayMode timeStyle, Locale locale, TZID tzid)
      Deprecated.
      Use ofMomentStyle(FormatStyle, FormatStyle, Locale, TZID)

      Constructs a style-based formatter for moments.

      Parameters:
      dateStyle - format style of date part
      timeStyle - format style of time part
      locale - format locale
      tzid - timezone identifier
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      3.10/4.7
      See Also:
      CalendarText.patternForMoment(DisplayMode, DisplayMode, Locale)

    • ofMomentStyle

      public static ChronoFormatter<Moment> ofMomentStyle​(FormatStyle dateStyle, FormatStyle timeStyle, Locale locale, TZID tzid)

      Constructs a style-based formatter for moments.

      Parameters:
      dateStyle - format style of date part
      timeStyle - format style of time part
      locale - format locale
      tzid - timezone identifier
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      5.8
      See Also:
      CalendarText.patternForMoment(FormatStyle, FormatStyle, Locale)

    • ofStyle

      @Deprecated public static <T extends LocalizedPatternSupport> ChronoFormatter<T> ofStyle​(DisplayMode style, Locale locale, Chronology<T> chronology)
      Deprecated.
      Use ofStyle(FormatStyle, Locale, Chronology)

      Constructs a style-based formatter for general chronologies.

      Type Parameters:
      T - generic chronological type
      Parameters:
      style - format style
      locale - format locale
      chronology - chronology with format pattern support
      Returns:
      new ChronoFormatter-instance
      Throws:
      UnsupportedOperationException - if given style is not supported
      Since:
      3.10/4.7

    • ofStyle

      public static <T extends LocalizedPatternSupport> ChronoFormatter<T> ofStyle​(FormatStyle style, Locale locale, Chronology<T> chronology)

      Constructs a style-based formatter for general chronologies.

      Type Parameters:
      T - generic chronological type with LocalizedPatternSupport as upper bound
      Parameters:
      style - format style
      locale - format locale
      chronology - chronology with format pattern support
      Returns:
      new ChronoFormatter-instance
      Throws:
      UnsupportedOperationException - if given style is not supported
      Since:
      5.8

    • ofGenericCalendarPattern

      public static ChronoFormatter<CalendarDate> ofGenericCalendarPattern​(String pattern, Locale locale)

      Constructs a CLDR-pattern-based formatter for general calendar chronologies.

      If the locale contains an unicode-ca-extension then Time4J will try to load a suitable calendar chronology if available. Otherwise ISO-8601 will be used with the exception of a few countries which prefer other calendars. Following example will obtain a formatter for the Persian calendar: 

           Locale loc = Locale.forLanguageTag("de-IR-u-ca-persian");
     ChronoFormatter<CalendarDate> formatter =
       ChronoFormatter.ofGenericCalendarPattern("G y MMMM d, EEEE", loc);
     PersianCalendar jalali = PersianCalendar.of(1393, 1, 10);
     PlainDate gregorian = jalali.transform(PlainDate.class);
     assertThat(formatter.format(jalali), is("AP 1393 Farwardin 10, Sonntag"));
     assertThat(formatter.format(gregorian), is("AP 1393 Farwardin 10, Sonntag"));

      This example also demonstrates that the chronology will be inferred from the locale and not from the object to be formatted. However, most applications should set the chronology explicitly for performance and clarity. This method will not work for chronologies which require a pattern type deviating from CLDR, for example the Mayan calendar or the French revolutionary calendar.

      Parameters:
      pattern - format pattern
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if resolving of pattern fails or a requested calendar cannot be found
      Since:
      4.27
      See Also:
      ofPattern(String, PatternType, Locale, Chronology), ofGenericCalendarStyle(FormatStyle, Locale), with(Locale), PatternType.CLDR, Locale.forLanguageTag(String)

    • ofGenericCalendarStyle

      @Deprecated public static ChronoFormatter<CalendarDate> ofGenericCalendarStyle​(DisplayMode style, Locale locale)
      Deprecated.
      Use ofGenericCalendarStyle(FormatStyle, Locale)

      Constructs a style-based formatter for general calendar chronologies which are compatible to CLDR.

      If the locale contains an unicode-ca-extension then Time4J will try to load a suitable calendar chronology if available. Otherwise ISO-8601 will be used with the exception of a few countries which prefer other calendars.

      Parameters:
      style - format style
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      4.27
      See Also:
      ofGenericCalendarPattern(String, Locale), with(Locale), Locale.forLanguageTag(String)

    • ofGenericCalendarStyle

      public static ChronoFormatter<CalendarDate> ofGenericCalendarStyle​(FormatStyle style, Locale locale)

      Constructs a style-based formatter for general calendar chronologies which are compatible to CLDR.

      If the locale contains an unicode-ca-extension then Time4J will try to load a suitable calendar chronology if available. Otherwise ISO-8601 will be used with the exception of a few countries which prefer other calendars.

      Parameters:
      style - format style
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Since:
      5.8
      See Also:
      ofGenericCalendarPattern(String, Locale), with(Locale), Locale.forLanguageTag(String)

    • ofGenericMomentPattern

      public static ChronoFormatter<Moment> ofGenericMomentPattern​(String pattern, Locale locale)

      Constructs a CLDR-pattern-based formatter for universal timestamps with calendar override derived from given locale.

      If the locale contains an unicode-ca-extension then Time4J will try to load a suitable override chronology if available. Otherwise ISO-8601 will be used. For formatting, it is necessary to set the timezone on the built formatter.

      Parameters:
      pattern - format pattern
      locale - format locale
      Returns:
      new ChronoFormatter-instance
      Throws:
      IllegalArgumentException - if resolving of pattern fails or a requested calendar cannot be found
      Since:
      4.27
      See Also:
      ofPattern(String, PatternType, Locale, Chronology), with(Locale), PatternType.CLDR, Locale.forLanguageTag(String)

    • setUp

      public static <T extends ChronoEntity<T>> ChronoFormatter.Builder<T> setUp​(Class<T> type, Locale locale)

      Constructs a builder for creating formatters.

      Type Parameters:
      T - generic chronological type (subtype of ChronoEntity)
      Parameters:
      type - reified chronological type
      locale - format locale
      Returns:
      new Builder-instance
      Throws:
      IllegalArgumentException - if given chronological type is not formattable that is if no chronology can be derived from type
      See Also:
      Chronology.lookup(Class)

    • setUp

      public static <T> ChronoFormatter.Builder<T> setUp​(Chronology<T> chronology, Locale locale)

      Constructs a builder for creating formatters.

      Type Parameters:
      T - generic chronological type (subtype of ChronoEntity)
      Parameters:
      chronology - formattable chronology
      locale - format locale
      Returns:
      new Builder-instance
      Since:
      3.10/4.7

    • setUpWithOverride

      public static <C extends CalendarVariant<C>> ChronoFormatter.Builder<Moment> setUpWithOverride​(Locale locale, CalendarFamily<C> overrideCalendar)

      Constructs a builder for creating global formatters with usage of given calendar type.

      For formatting, it is necessary to set the timezone on the built formatter. For parsing, the calendar variant is necessary.

      Type Parameters:
      C - generic calendrical type with variant
      Parameters:
      locale - format locale
      overrideCalendar - formattable calendar chronology
      Returns:
      new Builder-instance applicable on Moment
      Since:
      3.11/4.8

    • setUpWithOverride

      public static <C extends Calendrical<?,​ C>> ChronoFormatter.Builder<Moment> setUpWithOverride​(Locale locale, Chronology<C> overrideCalendar)

      Constructs a builder for creating global formatters with usage of given calendar type.

      For formatting, it is necessary to set the timezone on the built formatter.

      Type Parameters:
      C - generic calendrical type
      Parameters:
      locale - format locale
      overrideCalendar - formattable calendar chronology
      Returns:
      new Builder-instance applicable on Moment
      Since:
      3.11/4.8

    • equals

      public boolean equals​(Object obj)

      Compares the chronologies, default attributes, default values and the internal format structures.

      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()

      For debugging purposes.

      Overrides:
      toString in class Object