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 java.lang.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");
 

About thread-safety: This class is immutable and can be used by multiple threads in parallel.

Since:

3.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ChronoFormatter.Builder<T> Builder for creating a new ChronoFormatter.

Field Summary

Fields

Modifier and Type	Field and Description
static ChronoFormatter<Moment>	RFC_1123 Special formatter for printing or parsing moments according to the RFC-1123-specification.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object obj) Compares the chronologies, default attributes, default values and the internal format structures.
java.lang.String	format(GeneralTimestamp<?> tsp) Prints given general timestamp.
java.lang.String	format(T formattable) Prints given chronological entity as formatted text.
void	formatToBuffer(T formattable, java.lang.Appendable buffer) Prints given chronological entity as formatted text and writes it to given buffer.
AttributeQuery	getAttributes() Returns the global format attributes which are active if they are not overridden by sectional attributes.
Chronology<T>	getChronology() Returns the associated chronology.
java.util.Locale	getLocale() Returns the locale setting.
int	hashCode()
static ChronoFormatter<PlainDate>	ofDatePattern(java.lang.String pattern, PatternType type, java.util.Locale locale) Constructs a pattern-based formatter for plain date objects.
static ChronoFormatter<PlainDate>	ofDateStyle(DisplayMode style, java.util.Locale locale) Constructs a style-based formatter for plain date objects.
static ChronoParser<Moment>	ofMomentPattern(java.lang.String pattern, PatternType type, java.util.Locale locale) Constructs a pattern-based parser for global timestamp objects.
static ChronoFormatter<Moment>	ofMomentPattern(java.lang.String pattern, PatternType type, java.util.Locale locale, TZID tzid) Constructs a pattern-based formatter for global timestamp objects.
static ChronoFormatter<Moment>	ofMomentStyle(DisplayMode dateStyle, DisplayMode timeStyle, java.util.Locale locale, TZID tzid) Constructs a style-based formatter for moments.
static <T> ChronoFormatter<T>	ofPattern(java.lang.String pattern, PatternType type, java.util.Locale locale, Chronology<T> chronology) Constructs a pattern-based formatter for general chronologies.
static <T extends LocalizedPatternSupport> ChronoFormatter<T>	ofStyle(DisplayStyle style, java.util.Locale locale, Chronology<T> chronology) Constructs a style-based formatter for general chronologies.
static ChronoFormatter<PlainTime>	ofTimePattern(java.lang.String pattern, PatternType type, java.util.Locale locale) Constructs a pattern-based formatter for clock time objects.
static ChronoFormatter<PlainTimestamp>	ofTimestampPattern(java.lang.String pattern, PatternType type, java.util.Locale locale) Constructs a pattern-based formatter for plain timestamps.
static ChronoFormatter<PlainTimestamp>	ofTimestampStyle(DisplayMode dateStyle, DisplayMode timeStyle, java.util.Locale locale) Constructs a style-based formatter for plain timestamps.
static ChronoFormatter<PlainTime>	ofTimeStyle(DisplayMode style, java.util.Locale locale) Constructs a style-based formatter for plain date objects.
T	parse(java.lang.CharSequence text) Interpretes given text as chronological entity starting at the begin of text.
T	parse(java.lang.CharSequence text, ParseLog status) Interpretes given text as chronological entity starting at the specified position in parse log.
T	parse(java.lang.CharSequence text, ParseLog status, AttributeQuery attributes) Interpretes given text as chronological entity starting at the specified position in parse log.
T	parse(java.lang.CharSequence text, java.text.ParsePosition position) For maximum information use parse(CharSequence, ParseLog) instead.
T	parse(java.lang.CharSequence text, java.text.ParsePosition position, RawValues rawValues) Interpretes given text as chronological entity starting at the specified position.
ChronoEntity<?>	parseRaw(java.lang.CharSequence text, int offset) Translates given text as raw chronological entity without converting to the target type of the underlying chronology.
ChronoEntity<?>	parseRaw(java.lang.String text) Translates given text as raw chronological entity without converting to the target type of the underlying chronology.
java.util.Set<ElementPosition>	print(T formattable, java.lang.Appendable buffer, AttributeQuery attributes) Prints given chronological entity as formatted text and writes the text into given buffer.
<R> R	print(T formattable, java.lang.Appendable buffer, AttributeQuery attributes, ChronoFunction<ChronoDisplay,R> query) Creates a text output and writes it into given buffer.
java.util.Set<ElementPosition>	print(T formattable, java.lang.StringBuilder buffer) Prints given chronological entity as formatted text and writes the text into given buffer.
static <T> ChronoFormatter.Builder<T>	setUp(Chronology<T> chronology, java.util.Locale locale) Constructs a builder for creating formatters.
static <T extends ChronoEntity<T>> ChronoFormatter.Builder<T>	setUp(java.lang.Class<T> type, java.util.Locale locale) Constructs a builder for creating formatters.
static <C extends CalendarVariant<C>> ChronoFormatter.Builder<Moment>	setUpWithOverride(java.util.Locale locale, CalendarFamily<C> overrideCalendar) Constructs a builder for creating global formatters with usage of given calendar type.
static <C extends Calendrical<?,C>> ChronoFormatter.Builder<Moment>	setUpWithOverride(java.util.Locale locale, Chronology<C> overrideCalendar) Constructs a builder for creating global formatters with usage of given calendar type.
java.text.Format	toFormat() Converts this formatter into a traditional java.text.Format-object.
java.lang.String	toString() For debugging purposes.
<A extends java.lang.Enum<A>> ChronoFormatter<T>	with(AttributeKey<A> key, A value) Creates a copy of this formatter with given enum-attribute.
ChronoFormatter<T>	with(AttributeKey<java.lang.Boolean> key, boolean value) Creates a copy of this formatter with given boolean-attribute.
ChronoFormatter<T>	with(AttributeKey<java.lang.Character> key, char value) Creates a copy of this formatter with given char-attribute.
ChronoFormatter<T>	with(AttributeKey<java.lang.Integer> key, int value) Creates a copy of this formatter with given int-attribute.
ChronoFormatter<T>	with(Attributes attributes) Creates a copy of this formatter with given standard attributes.
ChronoFormatter<T>	with(ChronoHistory history) Creates a copy of this formatter with the given chronological history of gregorian calendar reforms.
ChronoFormatter<T>	with(Leniency leniency) Sets the leniency mode.
ChronoFormatter<T>	with(java.util.Locale locale) Creates a copy of this formatter with given locale.
ChronoFormatter<T>	with(StartOfDay startOfDay) Sets the start of calendar day.
ChronoFormatter<T>	with(Timezone tz) Creates a copy of this formatter with given timezone which shall be used in formatting or parsing.
ChronoFormatter<T>	withAlternativeEraNames() Creates a copy of this formatter with alternative era names.
ChronoFormatter<T>	withCalendarVariant(java.lang.String variant) Sets the calendar variant.
ChronoFormatter<T>	withCalendarVariant(VariantSource variantSource) Sets the calendar variant.
<V> ChronoFormatter<T>	withDefault(ChronoElement<V> element, V value) Determines a default replacement value for given element.
ChronoFormatter<T>	withGregorianCutOver(PlainDate date) Short-cut for with(ChronoHistory.ofGregorianReform(date)).
ChronoFormatter<T>	withLatinEraNames() Creates a copy of this formatter with latin era names.
ChronoFormatter<T>	withStdTimezone() Equivalent to with(Timezone.ofSystem()).
ChronoFormatter<T>	withTimezone(java.lang.String tzid) Equivalent to with(Timezone.of(tzid)).
ChronoFormatter<T>	withTimezone(TZID tzid) Equivalent to with(Timezone.of(tzid)).

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

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 Detail

getChronology

public Chronology<T> getChronology()

Returns the associated chronology.

Returns:

chronology to be used for formatting associated objects

getLocale

public java.util.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)

getAttributes

public AttributeQuery getAttributes()

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

These 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 TemporalFormatter<T>

Returns:

global control attributes valid for the whole formatter (can be overridden by sectional attributes however)

See Also:

getChronology(), getLocale()

format

public java.lang.String format(T formattable)

Description copied from interface: TemporalFormatter

Prints given chronological entity as formatted text.

Specified by:

format in interface TemporalFormatter<T>

Parameters:

formattable - object to be formatted

Returns:

formatted text

format

public java.lang.String format(GeneralTimestamp<?> tsp)

Prints given general timestamp.

Parameters:

tsp - general timestamp as combination of a date and a time

Returns:

formatted string

Throws:

java.lang.IllegalArgumentException - if the timestamp is not formattable with this formatter

Since:

3.11/4.8

formatToBuffer

public void formatToBuffer(T formattable,
                           java.lang.Appendable buffer)
                    throws java.io.IOException

Description copied from interface: TemporalFormatter

Prints given chronological entity as formatted text and writes it to given buffer.

Specified by:

formatToBuffer in interface TemporalFormatter<T>

Parameters:

formattable - object to be formatted

buffer - format buffer

Throws:

java.io.IOException - if writing to the buffer fails

print

public java.util.Set<ElementPosition> print(T formattable,
                                            java.lang.StringBuilder buffer)

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

Equiovalent to print(formattable, buffer, getDefaultAttributes(), true).

Parameters:

formattable - object to be formatted

buffer - text output buffer

Returns:

unmodifiable set of element positions in formatted text

Throws:

java.lang.IllegalArgumentException - if given object is not formattable

print

public java.util.Set<ElementPosition> print(T formattable,
                                            java.lang.Appendable buffer,
                                            AttributeQuery attributes)
                                     throws java.io.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.

Equivalent to print(formattable, buffer, attributes, true).

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:

java.lang.IllegalArgumentException - if given object is not formattable

java.io.IOException - if writing to buffer fails

print

public <R> R print(T formattable,
                   java.lang.Appendable buffer,
                   AttributeQuery attributes,
                   ChronoFunction<ChronoDisplay,R> query)
            throws java.io.IOException

Description copied from interface: ChronoPrinter

Creates a text output and writes it into given buffer.

Note: Implementations have to call query.apply(...) at the end to return a possibly meaningful result. An example would be a query which produces just the identical input so the result of printing a Moment will be the formatted form of the original Moment.

Specified by:

print in interface ChronoPrinter<T>

Type Parameters:

R - generic result type

Parameters:

formattable - chronological entity to be formatted

buffer - format buffer any text output will be sent to

attributes - control attributes

query - custom query returning any kind of result

Returns:

result of query

Throws:

java.io.IOException - if writing into buffer fails

parse

public T parse(java.lang.CharSequence text)
        throws java.text.ParseException

Description copied from interface: TemporalFormatter

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

Specified by:

parse in interface TemporalFormatter<T>

Parameters:

text - text to be parsed

Returns:

parse result

Throws:

java.text.ParseException - if the text is not parseable

parse

public T parse(java.lang.CharSequence text,
               java.text.ParsePosition position)

For maximum information use parse(CharSequence, ParseLog) instead.

Specified by:

parse in interface TemporalFormatter<T>

Parameters:

text - text to be parsed

position - parse position (always as new instance)

Returns:

result or null if parsing does not work

Throws:

java.lang.IndexOutOfBoundsException - if the start position is at end of text or even behind

parse

public T parse(java.lang.CharSequence text,
               java.text.ParsePosition position,
               RawValues rawValues)

Description copied from interface: TemporalFormatter

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

Specified by:

parse in interface TemporalFormatter<T>

Parameters:

text - text to be parsed

position - parse position (always as new instance)

rawValues - holder for raw values (always as new instance)

Returns:

result or null if parsing does not work

parse

public T parse(java.lang.CharSequence text,
               ParseLog status)

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

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

Parameters:

text - text to be parsed

status - parser information (always as new instance)

Returns:

result or null if parsing does not work

Throws:

java.lang.IndexOutOfBoundsException - if the start position is at end of text or even behind

parse

public T parse(java.lang.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:

java.lang.IndexOutOfBoundsException - if the start position is at end of text or even behind

parseRaw

public ChronoEntity<?> parseRaw(java.lang.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(java.lang.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(java.util.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:

• Attributes.LANGUAGE
• Attributes.ZERO_DIGIT
• Attributes.DECIMAL_SEPARATOR
• Attributes.NUMBER_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

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.

Note: Sectional attributes cannot be overridden.

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:

java.lang.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

See Also:

Attributes.TIMEZONE_ID

withTimezone

public ChronoFormatter<T> withTimezone(java.lang.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:

java.lang.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(java.lang.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 =
      PlainDate.localFormatter("MM-dd", PatternType.CLDR)
               .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:

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

See Also:

Attributes.PROTECTED_CHARACTERS

with

public ChronoFormatter<T> with(AttributeKey<java.lang.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<java.lang.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<java.lang.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 java.lang.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 java.text.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:

• PlainTime.AM_PM_OF_DAY => DateFormat.Field.AM_PM
• PlainTime.CLOCK_HOUR_OF_AMPM => DateFormat.Field.HOUR1
• PlainTime.CLOCK_HOUR_OF_DAY => DateFormat.Field.HOUR_OF_DAY1
• PlainDate.DAY_OF_MONTH => DateFormat.Field.DAY_OF_MONTH
• PlainDate.DAY_OF_WEEK => DateFormat.Field.DAY_OF_WEEK
• PlainDate.DAY_OF_YEAR => DateFormat.Field.DAY_OF_YEAR
• PlainTime.DIGITAL_HOUR_OF_AMPM => DateFormat.Field.HOUR1
• PlainTime.DIGITAL_HOUR_OF_DAY => DateFormat.Field.HOUR0
• PlainTime.MILLI_OF_SECOND => DateFormat.Field.MILLISECOND
• PlainTime.MINUTE_OF_HOUR => DateFormat.Field.MINUTE
• PlainDate.MONTH_AS_NUMBER => DateFormat.Field.MONTH
• PlainDate.MONTH_OF_YEAR => DateFormat.Field.MONTH
• PlainTime.SECOND_OF_MINUTE => DateFormat.Field.SECOND
• PlainDate.WEEKDAY_IN_MONTH => DateFormat.Field.DAY_OF_WEEK_IN_MONTH
• PlainDate.YEAR => DateFormat.Field.YEAR
• PlainDate.YEAR_OF_WEEKDATE => DateFormat.Field.YEAR
• Weekmodel.boundedWeekOfMonth() => DateFormat.Field.WEEK_OF_MONTH
• Weekmodel.boundedWeekOfYear() => DateFormat.Field.WEEK_OF_YEAR
• Weekmodel.weekOfMonth() => DateFormat.Field.WEEK_OF_MONTH
• Weekmodel.weekOfYear() => DateFormat.Field.WEEK_OF_YEAR
• Weekmodel.localDayOfWeek() => DateFormat.Field.DAY_OF_WEEK
• ChronoEntity.getTimezone() => DateFormat.Field.TIME_ZONE
• ChronoHistory.era() => DateFormat.Field.ERA
• ChronoHistory.yearOfEra() => DateFormat.Field.YEAR
• ChronoHistory.month() => DateFormat.Field.MONTH
• ChronoHistory.dayOfMonth() => DateFormat.Field.DAY_OF_MONTH

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(java.lang.String pattern,
                                                       PatternType type,
                                                       java.util.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:

java.lang.IllegalArgumentException - if resolving of pattern fails

Since:

3.1

See Also:

ofPattern(String, PatternType, Locale, Chronology)

ofTimePattern

public static ChronoFormatter<PlainTime> ofTimePattern(java.lang.String pattern,
                                                       PatternType type,
                                                       java.util.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:

java.lang.IllegalArgumentException - if resolving of pattern fails

Since:

3.1

See Also:

ofPattern(String, PatternType, Locale, Chronology)

ofTimestampPattern

public static ChronoFormatter<PlainTimestamp> ofTimestampPattern(java.lang.String pattern,
                                                                 PatternType type,
                                                                 java.util.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:

java.lang.IllegalArgumentException - if resolving of pattern fails

Since:

3.1

See Also:

ofPattern(String, PatternType, Locale, Chronology)

ofMomentPattern

public static ChronoParser<Moment> ofMomentPattern(java.lang.String pattern,
                                                   PatternType type,
                                                   java.util.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:

java.lang.IllegalArgumentException - if resolving of pattern fails

Since:

3.28/4.24

See Also:

ofMomentPattern(String, PatternType, Locale, TZID)

ofMomentPattern

public static ChronoFormatter<Moment> ofMomentPattern(java.lang.String pattern,
                                                      PatternType type,
                                                      java.util.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:

java.lang.IllegalArgumentException - if resolving of pattern fails

Since:

3.1

See Also:

ofPattern(String, PatternType, Locale, Chronology)

ofPattern

public static <T> ChronoFormatter<T> ofPattern(java.lang.String pattern,
                                               PatternType type,
                                               java.util.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 v3.24). 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:

java.lang.IllegalArgumentException - if resolving of pattern fails

Since:

3.14/4.11

See Also:

ChronoFormatter.Builder.addPattern(String, PatternType)

ofDateStyle

public static ChronoFormatter<PlainDate> ofDateStyle(DisplayMode style,
                                                     java.util.Locale 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)

ofTimeStyle

public static ChronoFormatter<PlainTime> ofTimeStyle(DisplayMode style,
                                                     java.util.Locale 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.patternForTime(DisplayMode, Locale)

ofTimestampStyle

public static ChronoFormatter<PlainTimestamp> ofTimestampStyle(DisplayMode dateStyle,
                                                               DisplayMode timeStyle,
                                                               java.util.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:

3.10/4.7

See Also:

CalendarText.patternForTimestamp(DisplayMode, DisplayMode, Locale)

ofMomentStyle

public static ChronoFormatter<Moment> ofMomentStyle(DisplayMode dateStyle,
                                                    DisplayMode timeStyle,
                                                    java.util.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

Since:

3.10/4.7

See Also:

CalendarText.patternForMoment(DisplayMode, DisplayMode, Locale)

ofStyle

public static <T extends LocalizedPatternSupport> ChronoFormatter<T> ofStyle(DisplayStyle style,
                                                                             java.util.Locale locale,
                                                                             Chronology<T> 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:

java.lang.UnsupportedOperationException - if given style is not supported

Since:

3.10/4.7

See Also:

DisplayMode

setUp

public static <T extends ChronoEntity<T>> ChronoFormatter.Builder<T> setUp(java.lang.Class<T> type,
                                                                           java.util.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:

java.lang.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,
                                                   java.util.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(java.util.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(java.util.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(java.lang.Object obj)

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

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

For debugging purposes.

Overrides:

toString in class java.lang.Object