net.time4j.format

Class ChronoFormatter<T extends ChronoEntity<T>>

java.lang.Object

net.time4j.format.ChronoFormatter<T>

Type Parameters:

T - generic type of chronological entity

All Implemented Interfaces:

ChronoParser<T>, ChronoPrinter<T>

public final class ChronoFormatter<T extends ChronoEntity<T>>
extends Object
implements ChronoPrinter<T>, ChronoParser<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.

Author:

Meno Hochschild

Nested Class Summary

Nested Classes

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object obj) Compares the chronologies, default attributes, default values and the internal format structures.
String	format(T formattable) Prints given chronological entity as formatted text.
Chronology<T>	getChronology() Returns the associated chronology.
Attributes	getDefaultAttributes() Returns the default attributes which are active if they are not overridden by sectional attributes.
Locale	getLocale() Returns the locale setting.
int	hashCode()
T	parse(CharSequence text) Interpretes given text as chronological entity starting at the begin of text.
T	parse(CharSequence text, ParseLog status) Interpretes given text as chronological entity starting at the specified position in parse log.
T	parse(CharSequence text, ParseLog status, AttributeQuery attributes) Interpretes given text as chronological entity starting at the specified position in parse log.
ChronoEntity<?>	parseRaw(CharSequence text, int offset) Translates given text as raw chronological entity without converting to the target type of the underlying chronology.
ChronoEntity<?>	parseRaw(String text) Translates given text as raw chronological entity without converting to the target type of the underlying chronology.
Set<ElementPosition>	print(T formattable, Appendable buffer, AttributeQuery attributes) Prints given chronological entity as formatted text and writes the text into given buffer.
<R> R	print(T formattable, Appendable buffer, AttributeQuery attributes, ChronoFunction<ChronoDisplay,R> query) Creates a text output and writes it into given buffer.
Set<ElementPosition>	print(T formattable, StringBuilder buffer) Prints given chronological entity as formatted text and writes the text into given buffer.
static <T extends ChronoEntity<T>> ChronoFormatter.Builder<T>	setUp(Class<T> type, Locale locale) Constructs a builder for creating formatters.
Format	toFormat() Converts this formatter into a traditional java.text.Format-object.
String	toString() For debugging purposes.
<A extends Enum<A>> ChronoFormatter<T>	with(AttributeKey<A> key, A value) Creates a copy of this formatter with given enum-attribute.
ChronoFormatter<T>	with(AttributeKey<Boolean> key, boolean value) Creates a copy of this formatter with given boolean-attribute.
ChronoFormatter<T>	with(AttributeKey<Character> key, char value) Creates a copy of this formatter with given char-attribute.
ChronoFormatter<T>	with(AttributeKey<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(Locale locale) Creates a copy of this formatter with given locale.
<V> ChronoFormatter<T>	withDefault(ChronoElement<V> element, V value) Determines a default replacement value for given element.
ChronoFormatter<T>	withStdTimezone() Equivalent to withTimezone(Timezone.ofSystem().getID()).
ChronoFormatter<T>	withTimezone(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.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

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)

getDefaultAttributes

public Attributes getDefaultAttributes()

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

The default 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)

Returns:

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

See Also:

getChronology(), getLocale()

format

public String format(T formattable)

Prints given chronological entity as formatted text.

Parameters:

formattable - object to be formatted

Returns:

formatted text

Throws:

IllegalArgumentException - if given object is not formattable

print

public Set<ElementPosition> print(T formattable,
                         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:

IllegalArgumentException - if given object is not formattable

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.

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:

IllegalArgumentException - if given object is not formattable

IOException - if writing to buffer fails

print

public <R> R print(T formattable,
          Appendable buffer,
          AttributeQuery attributes,
          ChronoFunction<ChronoDisplay,R> query)
        throws 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 extends ChronoEntity<T>>

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:

IOException - if writing into buffer fails

parse

public T parse(CharSequence text)
                                throws ParseException

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

Parameters:

text - text to be parsed

Returns:

parse result

Throws:

IndexOutOfBoundsException - if the text is empty

ParseException - if the text is not parseable

parse

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

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

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 extends ChronoEntity<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:

• Attributes.LANGUAGE
• Attributes.ZERO_DIGIT
• Attributes.DECIMAL_SEPARATOR

If necessary all inner format elements which are locale-dependent will also be adjusted (for example Weekmodel.weekOfYear(). But fixed literals will remain unchanged hence this method might not be suitable for all languages.

Parameters:

locale - new language and country configuration

Returns:

changed copy with given language and localized symbols while this instance remains unaffected

withTimezone

public 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.

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

Equivalent to withTimezone(Timezone.of(tzid).getID()).

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:

withTimezone(TZID), Attributes.TIMEZONE_ID

withStdTimezone

public ChronoFormatter<T> withStdTimezone()

Equivalent to withTimezone(Timezone.ofSystem().getID()).

Returns:

changed copy with the system timezone while this instance remains unaffected

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:

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

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.

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:

• 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
• 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

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

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)

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