net.time4j.format

Class Attributes

java.lang.Object

net.time4j.format.Attributes

All Implemented Interfaces:

AttributeQuery

public final class Attributes
extends Object
implements AttributeQuery

A collection of format attributes for controlling the formatting and parsing.

Author:

Meno Hochschild

Concurrency:

This class is immutable and can be used by multiple threads in parallel.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Attributes.Builder Builds a collection of format attributes.

Field Summary

Fields

Modifier and Type	Field and Description
static AttributeKey<String>	CALENDAR_TYPE Attribute for the calendar type.
static AttributeKey<String>	CALENDAR_VARIANT Defines an attribute key which can be used in queries for the calendar variant.
static AttributeKey<Character>	DECIMAL_SEPARATOR Determines the unicode char for the decimal separator.
static AttributeKey<String>	FORMAT_PATTERN Defines an attribute key which can show the global format pattern when the formatter was constructed by pattern.
static AttributeKey<Boolean>	FOUR_DIGIT_YEAR This attribute controls if style-driven date patterns should always have four-digit-years or not.
static AttributeKey<Locale>	LANGUAGE Attribute controlling the language output and parsing of chronological texts (for example month names).
static AttributeKey<Leniency>	LENIENCY Attribute which controls the leniency in parsing.
static AttributeKey<Boolean>	NO_GMT_PREFIX This attribute controls if the formatter will stop using the localized GMT prefix for representations of localized timezone offsets.
static AttributeKey<NumberSystem>	NUMBER_SYSTEM Determines the number system.
static AttributeKey<OutputContext>	OUTPUT_CONTEXT Determines the output context to be used in formatting and parsing.
static AttributeKey<Character>	PAD_CHAR Determines the pad char to be used for non-decimal elements if a formatted representation is shorter than specified.
static AttributeKey<Boolean>	PARSE_CASE_INSENSITIVE This attribute controls if the case of text is irrelevant in parsing or not.
static AttributeKey<Boolean>	PARSE_MULTIPLE_CONTEXT This attribute controls if the parser will also try alternative output contexts if parsing with the original one fails.
static AttributeKey<Boolean>	PARSE_PARTIAL_COMPARE This attribute controls if the parser will only check the start of a chronological text.
static AttributeKey<Integer>	PIVOT_YEAR Determines the pivot year for the representation of two-digit-years.
static AttributeKey<Integer>	PROTECTED_CHARACTERS Determines how many remaining chars in a given text are reserved and cannot be consumed by the current format step.
static AttributeKey<StartOfDay>	START_OF_DAY Defines an attribute key which can be used in queries for the start of day during formatting or parsing.
static AttributeKey<TextWidth>	TEXT_WIDTH Determines the text width to be used in formatting and parsing.
static AttributeKey<TimeScale>	TIME_SCALE Attribute for the time scale to be used in parsing or formatting universal timestamps.
static AttributeKey<TZID>	TIMEZONE_ID Attribute denoting the timezone identifier for display purposes.
static AttributeKey<Boolean>	TRAILING_CHARACTERS Controls if any trailing unparsed characters will be tolerated or not.
static AttributeKey<TransitionStrategy>	TRANSITION_STRATEGY Attribute for the conflict strategy to be used in resolving ambivalent or invalid local timestamps.
static AttributeKey<Character>	ZERO_DIGIT Determines the unicode char for the zero digit.

Method Summary

Modifier and Type	Method and Description
boolean	contains(AttributeKey<?> key) Queries if a format attribute exists for given key.
static <A> AttributeKey<A>	createKey(String name, Class<A> type) Creates a new attribute key.
static Attributes	empty() Represents an empty collection of format attributes.
boolean	equals(Object obj) Compares all internal format attributes.
<A> A	get(AttributeKey<A> key) Yields a format attribute for given key.
<A> A	get(AttributeKey<A> key, A defaultValue) Yields a format attribute for given key.
int	hashCode()
String	toString() Supports mainly debugging.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

CALENDAR_TYPE

public static final AttributeKey<String> CALENDAR_TYPE

Attribute for the calendar type.

This attribute is effectively read-only and usually derived from the corresponding annotation value of any given chronology. Default value: CalendarText.ISO_CALENDAR_TYPE

See Also:

CalendarType

LANGUAGE

public static final AttributeKey<Locale> LANGUAGE

Attribute controlling the language output and parsing of chronological texts (for example month names).

Default value: Locale.ROOT.

TIMEZONE_ID

public static final AttributeKey<TZID> TIMEZONE_ID

Attribute denoting the timezone identifier for display purposes.

When printing a global type this attribute controls the zonal representation. If this attribute is missing then Time4J will throw an exception because the internal timezone reference UTC+00:00 of global types is not intended to be used for display purposes.

When parsing a global type this attribute serves as replacement timezone if the parsing has not recognized any timezone or offset information in the text to be parsed. If the attribute is also missing then Time4J will throw an exception.

Note that before version v2.0 the behaviour of Time4J was different. When printing, the default ZonalOffset.UTC was used. When parsing, the system default timezone was used as default in case of missing attribute and lax mode.

TRANSITION_STRATEGY

public static final AttributeKey<TransitionStrategy> TRANSITION_STRATEGY

Attribute for the conflict strategy to be used in resolving ambivalent or invalid local timestamps.

If this attribute is missing then Time4J will assume the default conflict strategy.

See Also:

Timezone.DEFAULT_CONFLICT_STRATEGY

LENIENCY

public static final AttributeKey<Leniency> LENIENCY

Attribute which controls the leniency in parsing.

Setting of this attribute also changes other attributes:

Legend

LENIENCY	PARSE_CASE_INSENSITIVE	PARSE_PARTIAL_COMPARE	TRAILING_CHARACTERS	PARSE_MULTIPLE_CONTEXT
STRICT	false	false	false	false
SMART	true	false	false	true
LAX	true	true	true	true

Default value: Leniency.SMART

TEXT_WIDTH

public static final AttributeKey<TextWidth> TEXT_WIDTH

Determines the text width to be used in formatting and parsing.

Default value: TextWidth.WIDE

OUTPUT_CONTEXT

public static final AttributeKey<OutputContext> OUTPUT_CONTEXT

Determines the output context to be used in formatting and parsing.

Default value: OutputContext.FORMAT

PARSE_CASE_INSENSITIVE

public static final AttributeKey<Boolean> PARSE_CASE_INSENSITIVE

This attribute controls if the case of text is irrelevant in parsing or not.

Default value: true

PARSE_PARTIAL_COMPARE

public static final AttributeKey<Boolean> PARSE_PARTIAL_COMPARE

This attribute controls if the parser will only check the start of a chronological text.

Abbreviations can be parsed by help of this attribute, too. Default value: false

PARSE_MULTIPLE_CONTEXT

public static final AttributeKey<Boolean> PARSE_MULTIPLE_CONTEXT

This attribute controls if the parser will also try alternative output contexts if parsing with the original one fails.

Relates to month names, weekday names and quarter names. Default value: true

Since:

3.14/4.11

See Also:

OutputContext, OUTPUT_CONTEXT

NUMBER_SYSTEM

public static final AttributeKey<NumberSystem> NUMBER_SYSTEM

Determines the number system.

In case of changing the language setting this attribute will automatically be adjusted. The attribute for zero digit will be adjusted, too (if the number system is decimal) but can be set to another value however.

If a non-decimal number system like roman numbers is chosen then Time4J will ignore it for any other format component than ordinary integers. For example, zone offsets in format ±hh:mm, fractional seconds, ordinals like "1st" or two-digit-years cannot be printed in roman numbers.

Since:

3.11/4.8

ZERO_DIGIT

public static final AttributeKey<Character> ZERO_DIGIT

Determines the unicode char for the zero digit.

In case of changing the language setting or the (decimal) number system this attribute will automatically be adjusted to the default number system. For ISO-8601, the default value is the arab digit 0 (corresponding to the ASCII-value 48).

See Also:

NUMBER_SYSTEM

NO_GMT_PREFIX

public static final AttributeKey<Boolean> NO_GMT_PREFIX

This attribute controls if the formatter will stop using the localized GMT prefix for representations of localized timezone offsets.

Only relevant if the CLDR format pattern symbol O (or OOOO) is used.

Since:

3.13/4.10

DECIMAL_SEPARATOR

public static final AttributeKey<Character> DECIMAL_SEPARATOR

Determines the unicode char for the decimal separator.

In case of changing the language setting this attribute will automatically be adjusted. In ISO-8601 (for the root locale), the comma is the default value is the comma corresponding to the ASCII-value 44. With help of the boolean system property "net.time4j.format.iso.decimal.dot", the dot can be defined as alternative default value.

PAD_CHAR

public static final AttributeKey<Character> PAD_CHAR

Determines the pad char to be used for non-decimal elements if a formatted representation is shorter than specified.

This attribute is mainly interesting for text elements.

Default value is the space. Numerical elements using decimal numbering systems are not affected by this attribute because they always use the zero digit as pad char. However, other numbering systems like Roman numbers can be combined with this attribute if a padding instruction is also defined in the formatter. Example for numerical but non-decimal elements:

     ChronoFormatter<PlainDate> f =
       ChronoFormatter.setUp(PlainDate.axis(), Locale.ROOT)
         .addFixedInteger(PlainDate.YEAR, 4)
         .addLiteral('-')
         .padNext(2)
         .addInteger(PlainDate.MONTH_AS_NUMBER, 1, 2)
         .addLiteral('-')
         .padNext(2)
         .addInteger(PlainDate.DAY_OF_MONTH, 1, 2)
         .build()
         .with(Attributes.NUMBER_SYSTEM, NumberSystem.DOZENAL) // non-decimal!
         .with(Attributes.PAD_CHAR, '0');

     assertThat(
       f.format(PlainDate.of(2017, 10, 11)),
       is("1201-0↊-0↋"));
 

PIVOT_YEAR

public static final AttributeKey<Integer> PIVOT_YEAR

Determines the pivot year for the representation of two-digit-years.

Default value is the year which is 20 years after the current year. Example: If the pivot year has the value 2034 then a two-digit-year will be mapped to the range 1934-2033 such that the last two digits are equal. This attribute must have at least three digits an be positive else an exception will be thrown.

TRAILING_CHARACTERS

public static final AttributeKey<Boolean> TRAILING_CHARACTERS

Controls if any trailing unparsed characters will be tolerated or not.

Example:

  ChronoFormatter formatter =
      ChronoFormatter.setUp(PlainTime.class, Locale.US)
      .addInteger(PlainTime.CLOCK_HOUR_OF_AMPM, 1, 2)
      .addLiteral(' ')
      .addText(PlainTime.AM_PM_OF_DAY)
      .padPrevious(3)
      .addFixedInteger(PlainTime.MINUTE_OF_HOUR, 2)
      .build()
      .with(Attributes.TRAILING_CHARACTERS, true);
  System.out.println(formatter.parse("5 PM 45xyz"));
  // Output: T17:45
 

Starting with version v3.25/4.21, this attribute will only matter if users don't explicitly specify a ParseLog or a ParsePosition. Otherwise - with explicit parse log or position - the parser will always tolerate trailing characters.

Default value: false in strict or smart mode

PROTECTED_CHARACTERS

public static final AttributeKey<Integer> PROTECTED_CHARACTERS

Determines how many remaining chars in a given text are reserved and cannot be consumed by the current format step.

Default value is 0. This attribute can be used as sectional attribute if an integer element is numerically processed. Such a protected element will not consume any following chars and possibly use the default value setting of the current formatter instead.

Note: This attribute overrides any reserved area due to adjacent digit parsing.

Since:

2.0

CALENDAR_VARIANT

public static final AttributeKey<String> CALENDAR_VARIANT

Defines an attribute key which can be used in queries for the calendar variant.

Since:

3.5/4.3

START_OF_DAY

public static final AttributeKey<StartOfDay> START_OF_DAY

Defines an attribute key which can be used in queries for the start of day during formatting or parsing.

The default value is StartOfDay.MIDNIGHT.

Since:

3.5/4.3

FOUR_DIGIT_YEAR

public static final AttributeKey<Boolean> FOUR_DIGIT_YEAR

This attribute controls if style-driven date patterns should always have four-digit-years or not.

Default value: false

Since:

3.26/4.22

TIME_SCALE

public static final AttributeKey<TimeScale> TIME_SCALE

Attribute for the time scale to be used in parsing or formatting universal timestamps.

If this attribute is missing then Time4J will assume the default UTC scale. Example for TAI:

     assertThat(
       ChronoFormatter.ofMomentPattern(
         "uuuu-MM-dd'T'HH:mm:ss.SSSSSSSSSX",
         PatternType.CLDR,
         Locale.ROOT,
         ZonalOffset.UTC)
       .with(Attributes.TIME_SCALE, TimeScale.TAI)
       .parse("2012-07-01T00:00:34.123456789Z")
       .toString(),
       is("2012-06-30T23:59:60,123456789Z")); // 35 seconds delta between UTC and TAI
 

Since:

3.28/4.24

FORMAT_PATTERN

public static final AttributeKey<String> FORMAT_PATTERN

Defines an attribute key which can show the global format pattern when the formatter was constructed by pattern.

Since:

3.33/4.28

Method Detail

empty

public static Attributes empty()

Represents an empty collection of format attributes.

Returns:

empty attribute query

createKey

public static <A> AttributeKey<A> createKey(String name,
                                            Class<A> type)

Creates a new attribute key.

Type Parameters:

A - generic immutable type of attribute value

Parameters:

name - name of attribute

type - type of attribute

Returns:

new attribute key

Since:

3.13/4.10

contains

public boolean contains(AttributeKey<?> key)

Description copied from interface: AttributeQuery

Queries if a format attribute exists for given key.

Specified by:

contains in interface AttributeQuery

Parameters:

key - attribute key

Returns:

true if attribute exists else false

get

public <A> A get(AttributeKey<A> key)

Description copied from interface: AttributeQuery

Yields a format attribute for given key.

Specified by:

get in interface AttributeQuery

Type Parameters:

A - generic type of attribute value

Parameters:

key - attribute key

Returns:

attribute value

get

public <A> A get(AttributeKey<A> key,
                 A defaultValue)

Description copied from interface: AttributeQuery

Yields a format attribute for given key.

Specified by:

get in interface AttributeQuery

Type Parameters:

A - generic type of attribute value

Parameters:

key - attribute key

defaultValue - replacement value to be used if attribute does not exist

Returns:

attribute value

equals

public boolean equals(Object obj)

Compares all internal format attributes.

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Supports mainly debugging.

Overrides:

toString in class Object