T - generic type of chronological entitypublic final class ChronoFormatter<T extends ChronoEntity<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 predefined format constants
in Iso8601Format which can be adjusted by some
with()-methods. Another way to create an instance are the
methods formatter(...) and localFormatter(...) in
the classes PlainDate, PlainTime, PlainTimestamp
and Moment.
| Modifier and Type | Class and Description |
|---|---|
static class |
ChronoFormatter.Builder<T extends ChronoEntity<T>>
Builder for creating a new
ChronoFormatter. |
| 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(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<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<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.
|
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 extends ChronoEntity<T>> |
setUp(java.lang.Class<T> type,
java.util.Locale locale)
Constructs a builder for creating formatters.
|
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>> |
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> |
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> |
withStartOfDay(StartOfDay startOfDay)
Sets the start of calendar day.
|
ChronoFormatter<T> |
withStdTimezone()
Equivalent to
withTimezone(Timezone.ofSystem().getID()). |
ChronoFormatter<T> |
withTimezone(java.lang.String tzid)
Equivalent to
withTimezone(Timezone.of(tzid).getID()). |
ChronoFormatter<T> |
withTimezone(TZID tzid)
Creates a copy of this formatter with given timezone id which
shall be used in formatting or parsing.
|
public Chronology<T> getChronology()
Returns the associated chronology.
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.
null)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:
Attributes.CALENDAR_TYPE |
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) |
getAttributes in interface TemporalFormatter<T extends ChronoEntity<T>>getChronology(),
getLocale()public java.lang.String format(T formattable)
TemporalFormatterPrints given chronological entity as formatted text.
format in interface TemporalFormatter<T extends ChronoEntity<T>>formattable - object to be formattedpublic void formatToBuffer(T formattable, java.lang.Appendable buffer) throws java.io.IOException
TemporalFormatterPrints given chronological entity as formatted text and writes it to given buffer.
formatToBuffer in interface TemporalFormatter<T extends ChronoEntity<T>>formattable - object to be formattedbuffer - format bufferjava.io.IOException - if writing to the buffer failspublic 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).
formattable - object to be formattedbuffer - text output bufferjava.lang.IllegalArgumentException - if given object is not formattablepublic 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).
formattable - object to be formattedbuffer - text output bufferattributes - attributes for limited formatting controljava.lang.IllegalArgumentException - if given object is not formattablejava.io.IOException - if writing to buffer failspublic <R> R print(T formattable, java.lang.Appendable buffer, AttributeQuery attributes, ChronoFunction<ChronoDisplay,R> query) throws java.io.IOException
ChronoPrinterCreates 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.
print in interface ChronoPrinter<T extends ChronoEntity<T>>R - generic result typeformattable - chronological entity to be formattedbuffer - format buffer any text output will be sent toattributes - control attributesquery - custom query returning any kind of resultjava.io.IOException - if writing into buffer failspublic T parse(java.lang.CharSequence text) throws java.text.ParseException
TemporalFormatterInterpretes given text as chronological entity starting at the begin of text.
parse in interface TemporalFormatter<T extends ChronoEntity<T>>text - text to be parsedjava.text.ParseException - if the text is not parseablepublic T parse(java.lang.CharSequence text, java.text.ParsePosition position)
For maximum information use parse(CharSequence, ParseLog) instead.
parse in interface TemporalFormatter<T extends ChronoEntity<T>>text - text to be parsedposition - parse position (always as new instance)null if parsing does not workjava.lang.IndexOutOfBoundsException - if the start position is at end of text or even behindpublic T parse(java.lang.CharSequence text, java.text.ParsePosition position, RawValues rawValues)
TemporalFormatterInterpretes given text as chronological entity starting at the specified position.
parse in interface TemporalFormatter<T extends ChronoEntity<T>>text - text to be parsedposition - parse position (always as new instance)rawValues - holder for raw values (always as new instance)null if parsing does not workpublic 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()).
text - text to be parsedstatus - parser information (always as new instance)null if parsing does not workjava.lang.IndexOutOfBoundsException - if the start position is at end of
text or even behindpublic 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.
parse in interface ChronoParser<T extends ChronoEntity<T>>text - text to be parsedstatus - parser information (always as new instance)attributes - attributes for limited parsing controlnull if parsing does not workjava.lang.IndexOutOfBoundsException - if the start position is at end of
text or even behindpublic ChronoEntity<?> parseRaw(java.lang.String text)
Translates given text as raw chronological entity without converting to the target type of the underlying chronology.
text - text to be parsedpublic 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.
text - text to be parsedoffset - start positionpublic 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:
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.
with in interface TemporalFormatter<T extends ChronoEntity<T>>locale - new language and country configurationpublic ChronoFormatter<T> with(Leniency leniency)
TemporalFormatterSets the leniency mode.
By default any temporal formatter is smart.
with in interface TemporalFormatter<T extends ChronoEntity<T>>leniency - determines how strict the parser should beAttributes.LENIENCYpublic ChronoFormatter<T> withAlternativeEraNames()
Creates a copy of this formatter with alternative era names.
Note: Sectional attributes cannot be overridden.
ChronoHistory.ATTRIBUTE_COMMON_ERA,
HistoricEra.getAlternativeName(Locale, TextWidth)public ChronoFormatter<T> withLatinEraNames()
Creates a copy of this formatter with latin era names.
Note: Sectional attributes cannot be overridden.
ChronoHistory.ATTRIBUTE_LATIN_ERApublic ChronoFormatter<T> withGregorianCutOver(PlainDate date)
Short-cut for with(ChronoHistory.ofGregorianReform(date)).
date - first gregorian date after gregorian calendar reform takes effectjava.lang.IllegalArgumentException - if given date is before first introduction of gregorian calendar
on 1582-10-15 and not the minimum on the date axisChronoHistory.ofGregorianReform(PlainDate),
with(ChronoHistory)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.
history - chronological history describing historical calendar reformspublic ChronoFormatter<T> withTimezone(TZID tzid)
Creates a copy of this formatter with given timezone id 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 as replacement value if the formatted
text does not contain any timezone.
withTimezone in interface TemporalFormatter<T extends ChronoEntity<T>>tzid - timezone idAttributes.TIMEZONE_IDpublic ChronoFormatter<T> withTimezone(java.lang.String tzid)
Equivalent to withTimezone(Timezone.of(tzid).getID()).
withTimezone in interface TemporalFormatter<T extends ChronoEntity<T>>tzid - timezone idjava.lang.IllegalArgumentException - if given timezone cannot be loadedwithTimezone(TZID),
Attributes.TIMEZONE_IDpublic ChronoFormatter<T> withStdTimezone()
Equivalent to withTimezone(Timezone.ofSystem().getID()).
public ChronoFormatter<T> withCalendarVariant(java.lang.String variant)
Sets the calendar variant.
variant - name of new calendar variantAttributes.CALENDAR_VARIANTpublic ChronoFormatter<T> withCalendarVariant(VariantSource variantSource)
Sets the calendar variant.
variantSource - source of new calendar variantAttributes.CALENDAR_VARIANTpublic ChronoFormatter<T> withStartOfDay(StartOfDay startOfDay)
Sets the start of calendar day.
startOfDay - new start of dayAttributes.START_OF_DAYpublic <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.
V - generic element value typeelement - chronological element to be updatedvalue - replacement value or null
if the default value shall be deregisteredjava.lang.IllegalArgumentException - if given element is not supported
by the underlying chronologyAttributes.PROTECTED_CHARACTERSpublic 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.
key - attribute keyvalue - attribute valuepublic 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.
key - attribute keyvalue - attribute valuepublic 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.
key - attribute keyvalue - attribute valuepublic <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.
A - generic attribute value typekey - attribute keyvalue - attribute valuepublic ChronoFormatter<T> with(Attributes attributes)
Creates a copy of this formatter with given standard attributes.
Note: Sectional attributes cannot be overridden.
attributes - new default attributespublic 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_PMPlainTime.CLOCK_HOUR_OF_AMPM =>
DateFormat.Field.HOUR1PlainTime.CLOCK_HOUR_OF_DAY =>
DateFormat.Field.HOUR_OF_DAY1PlainDate.DAY_OF_MONTH =>
DateFormat.Field.DAY_OF_MONTHPlainDate.DAY_OF_WEEK =>
DateFormat.Field.DAY_OF_WEEKPlainDate.DAY_OF_YEAR =>
DateFormat.Field.DAY_OF_YEARPlainTime.DIGITAL_HOUR_OF_AMPM =>
DateFormat.Field.HOUR1PlainTime.DIGITAL_HOUR_OF_DAY =>
DateFormat.Field.HOUR0PlainTime.MILLI_OF_SECOND =>
DateFormat.Field.MILLISECONDPlainTime.MINUTE_OF_HOUR =>
DateFormat.Field.MINUTEPlainDate.MONTH_AS_NUMBER =>
DateFormat.Field.MONTHPlainDate.MONTH_OF_YEAR =>
DateFormat.Field.MONTHPlainTime.SECOND_OF_MINUTE =>
DateFormat.Field.SECONDPlainDate.WEEKDAY_IN_MONTH =>
DateFormat.Field.DAY_OF_WEEK_IN_MONTHPlainDate.YEAR =>
DateFormat.Field.YEARPlainDate.YEAR_OF_WEEKDATE =>
DateFormat.Field.YEARWeekmodel.boundedWeekOfMonth() =>
DateFormat.Field.WEEK_OF_MONTHWeekmodel.boundedWeekOfYear() =>
DateFormat.Field.WEEK_OF_YEARWeekmodel.weekOfMonth() =>
DateFormat.Field.WEEK_OF_MONTHWeekmodel.weekOfYear() =>
DateFormat.Field.WEEK_OF_YEARWeekmodel.localDayOfWeek() =>
DateFormat.Field.DAY_OF_WEEKChronoEntity.getTimezone() =>
DateFormat.Field.TIME_ZONEChronoHistory.era() =>
DateFormat.Field.ERAChronoHistory.yearOfEra() =>
DateFormat.Field.YEARChronoHistory.month() =>
DateFormat.Field.MONTHChronoHistory.dayOfMonth() =>
DateFormat.Field.DAY_OF_MONTHNote: The returned Format-object is not serializable.
java.text.Format-object which
delegates all formatting and parsing work to this instancepublic static ChronoFormatter<PlainDate> ofDatePattern(java.lang.String pattern, PatternType type, java.util.Locale locale)
Constructs a pattern-based formatter for plain date objects.
pattern - format patterntype - the type of the pattern to be usedlocale - format localeChronoFormatter-instancejava.lang.IllegalArgumentException - if resolving of pattern failspublic static ChronoFormatter<PlainTime> ofTimePattern(java.lang.String pattern, PatternType type, java.util.Locale locale)
Constructs a pattern-based formatter for clock time objects.
pattern - format patterntype - the type of the pattern to be usedlocale - format localeChronoFormatter-instancejava.lang.IllegalArgumentException - if resolving of pattern failspublic static ChronoFormatter<PlainTimestamp> ofTimestampPattern(java.lang.String pattern, PatternType type, java.util.Locale locale)
Constructs a pattern-based formatter for plain timestamps.
pattern - format patterntype - the type of the pattern to be usedlocale - format localeChronoFormatter-instancejava.lang.IllegalArgumentException - if resolving of pattern failspublic 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.
pattern - format patterntype - the type of the pattern to be usedlocale - format localetzid - timezone idMoment-objects using given locale and timezonejava.lang.IllegalArgumentException - if resolving of pattern failspublic static <T extends ChronoEntity<T>> ChronoFormatter.Builder<T> setUp(java.lang.Class<T> type, java.util.Locale locale)
Constructs a builder for creating formatters.
T - generic chronological type (subtype of ChronoEntity)type - reified chronological typelocale - format localeBuilder-instancejava.lang.IllegalArgumentException - if given chronological type is not
formattable that is if no chronology can be derived from typeChronology.lookup(Class)public boolean equals(java.lang.Object obj)
Compares the chronologies, default attributes, default values and the internal format structures.
equals in class java.lang.Objectpublic int hashCode()
hashCode in class java.lang.Objectpublic java.lang.String toString()
For debugging purposes.
toString in class java.lang.Object