net.time4j.format

Interface TemporalFormatter<T>

Type Parameters:

T - generic type of applicable chronological types

All Known Implementing Classes:

ChronoFormatter, SimpleFormatter

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.

Since:

3.0

Author:

Meno Hochschild

Specification:

All implementations must be immutable.

Method Summary

Modifier and Type	Method and Description
default String	format(T formattable) Synonym for print(T).
AttributeQuery	getAttributes() Determines all global format attributes if available.
T	parse(CharSequence text) Interpretes given text as chronological entity.
T	parse(CharSequence text, RawValues rawValues) Interpretes given text as chronological entity and updates given raw values.
String	print(T formattable) Prints given chronological entity as formatted text.
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

default String format(T formattable)

Synonym for print(T).

This method adapts the standard naming style of most Java formatters while Time4J prefers the name "print".

Parameters:

formattable - object to be formatted

Returns:

formatted text

Throws:

IllegalArgumentException - if given object is not formattable

Since:

3.0

print

String print(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:

5.0

parse

T parse(CharSequence text)
 throws ParseException

Interpretes given text as chronological entity.

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,
        RawValues rawValues)
 throws ParseException

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

Parameters:

text - text to be parsed

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

Returns:

parsed result

Throws:

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

ParseException - if parsing does not work

Since:

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

Throws:

IllegalArgumentException - if timezone data cannot be loaded

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:

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