net.time4j.format

Interface TemporalFormatter<T>

Type Parameters:

T - generic type of applicable chronological types

public interface TemporalFormatter<T>

Generic facade for any temporal/chronological format object which can print temporal objects to text or parse texts to temporal objects.

Specification: Implementations must be immutable.

Since:

3.0

Author:

Meno Hochschild

Method Summary

Methods

Modifier and Type	Method and Description
String	format(T formattable) Prints given chronological entity as formatted text.
void	formatToBuffer(T formattable, Appendable buffer) Prints given chronological entity as formatted text and writes it to given buffer.
AttributeQuery	getAttributes() Determines all global format attributes if available.
T	parse(CharSequence text) Interpretes given text as chronological entity starting at the begin of text.
T	parse(CharSequence text, ParsePosition position) Interpretes given text as chronological entity starting at the specified position.
T	parse(CharSequence text, ParsePosition position, RawValues rawValues) Interpretes given text as chronological entity starting at the specified position.
TemporalFormatter<T>	with(Leniency leniency) Sets the leniency mode.
TemporalFormatter<T>	with(Locale locale) Creates a copy of this formatter with given locale.
TemporalFormatter<T>	withTimezone(String tzid) Equivalent to withTimezone(Timezone.of(tzid).getID()).
TemporalFormatter<T>	withTimezone(TZID tzid) Creates a copy of this formatter with given timezone id which shall be used in formatting or parsing.

Method Detail

format

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

Since:

3.0

formatToBuffer

void formatToBuffer(T formattable,
                  Appendable buffer)
                    throws IOException

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

Parameters:

formattable - object to be formatted

buffer - format buffer

Throws:

IllegalArgumentException - if given object is not formattable

IOException - if writing to the buffer fails

Since:

3.0

parse

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

Since:

3.0

parse

T parse(CharSequence text,
      ParsePosition position)

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

Parameters:

text - text to be parsed

position - parse position (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

Since:

3.0

parse

T parse(CharSequence text,
      ParsePosition position,
      RawValues rawValues)

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

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

Throws:

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

Since:

3.0

withTimezone

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

Since:

3.0

See Also:

Attributes.TIMEZONE_ID

withTimezone

TemporalFormatter<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:

3.0

See Also:

TemporalFormatter.withTimezone(TZID), Attributes.TIMEZONE_ID

with

TemporalFormatter<T> with(Locale locale)

Creates a copy of this formatter with given locale.

Note that changing the locale cannot change the inner structure of this formatter even if the structure is no longer appropriate for given locale. An example is the English AM/PM-pattern which will be preserved even if the language changes from English to German.

Parameters:

locale - new language and country configuration

Returns:

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

Since:

3.0

with

TemporalFormatter<T> with(Leniency leniency)

Sets the leniency mode.

By default any temporal formatter is smart.

Parameters:

leniency - determines how strict the parser should be

Returns:

changed copy with the new or changed attribute while this instance remains unaffected

Since:

3.0

See Also:

Attributes.LENIENCY

getAttributes

AttributeQuery getAttributes()

Determines all global format attributes if available.

Global attributes are valid for the whole formatter. Sectional attributes which might exist and control the behaviour of only a part of the formatter cannot be overridden.

Returns:

attribute query

Since:

3.0