T - generic type of chronological entity (subtype of ChronoEntity)public static final class ChronoFormatter.Builder<T extends ChronoEntity<T>> extends Object
Builder for creating a new ChronoFormatter.
This class is not thread-safe so a new instance is
necessary per thread. A new instance can be created by
ChronoFormatter.setUp(Class, Locale).
| Modifier and Type | Method and Description |
|---|---|
<V extends ChronoEntity<V>> |
addCustomized(ChronoElement<V> element,
ChronoFormatter<V> formatter)
Defines a customized format element for given chronological
element.
|
<V> ChronoFormatter.Builder<T> |
addCustomized(ChronoElement<V> element,
ChronoPrinter<V> printer,
ChronoParser<V> parser)
Defines a customized format element for given chronological
element.
|
ChronoFormatter.Builder<T> |
addDayPeriod(Map<PlainTime,String> timeToLabels)
Defines a text format for a custom day period.
|
ChronoFormatter.Builder<T> |
addDayPeriodApproximate()
Defines a text format for a flexible day period (morning/afternoon etc).
|
ChronoFormatter.Builder<T> |
addDayPeriodFixed()
Defines a text format for a fixed day period (am/pm/midnight/noon).
|
ChronoFormatter.Builder<T> |
addEnglishOrdinal(ChronoElement<Integer> element)
Defines an ordinal format for given chronological
element in english language.
|
ChronoFormatter.Builder<T> |
addFixedDecimal(ChronoElement<BigDecimal> element,
int precision,
int scale)
Defines a fixed unsigned decimal format for given chronological
element.
|
ChronoFormatter.Builder<T> |
addFixedInteger(ChronoElement<Integer> element,
int digits)
Defines an integer format without sign and with fixed width
for given chronological element.
|
<V extends Enum<V>> |
addFixedNumerical(ChronoElement<V> element,
int digits)
Defines an integer format without sign and with fixed width
for given chronological enumeration element.
|
ChronoFormatter.Builder<T> |
addFraction(ChronoElement<Integer> element,
int minDigits,
int maxDigits,
boolean decimalSeparator)
Defines a fractional format for given chronological element
including a possible decimal separator char but without any
integer part by mapping the context-dependent value range to
the interval [0.0-1.0).
|
ChronoFormatter.Builder<T> |
addIgnorableWhitespace()
Defines a sequence of optional white space.
|
ChronoFormatter.Builder<T> |
addInteger(ChronoElement<Integer> element,
int minDigits,
int maxDigits)
Defines an integer format without sign for given
chronological element.
|
ChronoFormatter.Builder<T> |
addInteger(ChronoElement<Integer> element,
int minDigits,
int maxDigits,
SignPolicy signPolicy)
Defines an integer format for given chronological
element.
|
ChronoFormatter.Builder<T> |
addLiteral(AttributeKey<Character> attribute)
Defines a literal element with a char which will be searched
in given format attribute.
|
ChronoFormatter.Builder<T> |
addLiteral(char literal)
Defines a literal element with exactly one char.
|
ChronoFormatter.Builder<T> |
addLiteral(char literal,
char alt)
Defines a literal element with exactly one char which can also be an alternative char
during parsing.
|
ChronoFormatter.Builder<T> |
addLiteral(String literal)
Defines a literal element with any chars.
|
ChronoFormatter.Builder<T> |
addLongLocalizedOffset()
Adds a timezone offset in long localized notation.
|
ChronoFormatter.Builder<T> |
addLongNumber(ChronoElement<Long> element,
int minDigits,
int maxDigits,
SignPolicy signPolicy)
Defines an integer format for given chronological
element.
|
ChronoFormatter.Builder<T> |
addLongTimezoneName()
Adds a long localized timezone name.
|
ChronoFormatter.Builder<T> |
addLongTimezoneName(Set<TZID> preferredZones)
Adds a long localized timezone name.
|
<V extends Enum<V>> |
addNumerical(ChronoElement<V> element,
int minDigits,
int maxDigits)
Defines an integer format without sign for given chronological
enumeration element.
|
ChronoFormatter.Builder<T> |
addOrdinal(ChronoElement<Integer> element,
Map<PluralCategory,String> indicators)
Defines an ordinal format for given chronological
element.
|
ChronoFormatter.Builder<T> |
addPattern(String formatPattern,
PatternType patternType)
Processes given format pattern of given pattern type to a
sequence of format elements.
|
ChronoFormatter.Builder<T> |
addShortLocalizedOffset()
Adds a timezone offset in short localized notation.
|
ChronoFormatter.Builder<T> |
addShortTimezoneName()
Adds a short localized timezone name (an abbreviation).
|
ChronoFormatter.Builder<T> |
addShortTimezoneName(Set<TZID> preferredZones)
Adds a short localized timezone name (an abbreviation).
|
<V extends Enum<V>> |
addText(ChronoElement<V> element)
Defines a text format for given chronological element.
|
<V extends Enum<V>> |
addText(ChronoElement<V> element,
Map<V,String> lookup)
Defines a text format for given chronological element with
user-defined string resources.
|
ChronoFormatter.Builder<T> |
addText(TextElement<?> element)
Defines a text format for given chronological element.
|
ChronoFormatter.Builder<T> |
addTimezoneID()
Adds a timezone identifier.
|
ChronoFormatter.Builder<T> |
addTimezoneOffset()
Adds a timezone offset in typical ISO-8601-notation.
|
ChronoFormatter.Builder<T> |
addTimezoneOffset(DisplayMode precision,
boolean extended,
List<String> zeroOffsets)
Adds a timezone offset in canonical notation.
|
ChronoFormatter.Builder<T> |
addTwoDigitYear(ChronoElement<Integer> element)
Defines a special format element for a two-digit-year.
|
ChronoFormatter<T> |
build()
Finishes the build and creates a new
ChronoFormatter. |
ChronoFormatter.Builder<T> |
endSection()
Removes the last sectional attribute.
|
Chronology<?> |
getChronology()
Returns the calendar override if set else the associated chronology.
|
ChronoFormatter.Builder<T> |
or()
Starts a new block inside the current section such that the following parts will only be
taken into account in case of failure according to or-logic.
|
ChronoFormatter.Builder<T> |
padNext(int width)
Defines for the next format element of the same section so
many pad chars until the element width has reached the width
specified.
|
ChronoFormatter.Builder<T> |
padPrevious(int width)
Defines for the previous format element of the same
section so many pad chars until the element width has
reached the width specified.
|
ChronoFormatter.Builder<T> |
skipUnknown(ChronoCondition<Character> unparseableCondition,
int maxIterations)
Skips all characters accepted by given condition as unparseable.
|
ChronoFormatter.Builder<T> |
skipUnknown(int keepRemainingChars)
Skips all characters from input as unparseable until at least given count of characters is left.
|
ChronoFormatter.Builder<T> |
startOptionalSection()
Starts a new optional section where errors in parsing will
not cause an exception but just be ignored.
|
ChronoFormatter.Builder<T> |
startOptionalSection(ChronoCondition<ChronoDisplay> printCondition)
Starts a new optional section where errors in parsing will
not cause an exception but just be ignored.
|
<A extends Enum<A>> |
startSection(AttributeKey<A> key,
A value)
Starts a new section with given sectional attribute.
|
ChronoFormatter.Builder<T> |
startSection(AttributeKey<Boolean> key,
boolean value)
Starts a new section with given sectional attribute.
|
ChronoFormatter.Builder<T> |
startSection(AttributeKey<Character> key,
char value)
Starts a new section with given sectional attribute.
|
ChronoFormatter.Builder<T> |
startSection(AttributeKey<Integer> key,
int value)
Starts a new section with given sectional attribute.
|
public Chronology<?> getChronology()
Returns the calendar override if set else the associated chronology.
public ChronoFormatter.Builder<T> addInteger(ChronoElement<Integer> element, int minDigits, int maxDigits)
Defines an integer format without sign for given chronological element.
Equivalent to addInteger(element, minDigits, maxDigits,
SignPolicy.SHOW_NEVER.
element - chronological elementminDigits - minimum count of digits in range 1-9maxDigits - maximum count of digits in range 1-9IllegalArgumentException - if any of minDigits and
maxDigits are out of range 1-9 or if
maxDigits < minDigits or if given element is
not supported by chronology or its preparserIllegalStateException - if a numerical element is added
multiple times in a rowChronology.isSupported(ChronoElement),
SignPolicy.SHOW_NEVER,
ChronoFormatter.Builder.addInteger(ChronoElement, int, int, SignPolicy)public ChronoFormatter.Builder<T> addInteger(ChronoElement<Integer> element, int minDigits, int maxDigits, SignPolicy signPolicy)
Defines an integer format for given chronological element.
First a sign is expected (positive or negative) where the
last argument signPolicy controls the output and
interpretation. Following rules hold for the sequence of
digits to be formatted:
minDigits then it will be left-padded with
zero digit char until the sequence has minDigits
digits. But if there are more digits than maxDigits
then an IllegalArgumentException will be thrown. maxDigits chars will be
interpreted as digits. If there are less than minDigits
then the text input will be invalid. Note: If there is no
strict or smart mode (lax) then the parser will always assume
minDigits == 0 and maxDigits = 9. Note: The argument maxDigits will only be taken into account
if the arabic number system is used.
Example:
ChronoElement<Integer> element = PlainTime.MILLI_OF_SECOND;
int minDigits = 3;
int maxDigits = 6;
ChronoFormatter<PlainTime> formatter =
ChronoFormatter.setUp(PlainTime.class, Locale.US)
.addInteger(
element,
minDigits,
maxDigits,
SignPolicy.SHOW_ALWAYS)
.build();
System.out.println(
formatter.format(PlainTime.of(12, 0, 0, 12345678)));
// output: +012
element - chronological elementminDigits - minimum count of digits in range 1-9maxDigits - maximum count of digits in range 1-9signPolicy - controls output of numeric signIllegalArgumentException - if any of minDigits and
maxDigits are out of range 1-9 or if
maxDigits < minDigits or if given element is
not supported by chronology or its preparserIllegalStateException - if a numerical element is added
multiple times in a rowChronology.isSupported(ChronoElement),
Attributes.LENIENCYpublic ChronoFormatter.Builder<T> addLongNumber(ChronoElement<Long> element, int minDigits, int maxDigits, SignPolicy signPolicy)
Defines an integer format for given chronological element.
Like ChronoFormatter.Builder.addInteger(ChronoElement, int, int,
SignPolicy) but on long-basis.
element - chronological elementminDigits - minimum count of digits in range 1-18maxDigits - maximum count of digits in range 1-18signPolicy - controls output of numeric signIllegalArgumentException - if any of minDigits and
maxDigits are out of range 1-18 or if
maxDigits < minDigits or if given element is
not supported by chronology or its preparserIllegalStateException - if a numerical element is added
multiple times in a rowChronology.isSupported(ChronoElement)public ChronoFormatter.Builder<T> addFixedInteger(ChronoElement<Integer> element, int digits)
Defines an integer format without sign and with fixed width for given chronological element.
Almost equivalent to
addInteger(element, digits, digits, SignPolicy.SHOW_NEVER)
but with following important difference:
If this method directly follow after other numerical elements then the fixed width defined here will be preserved in preceding elements so parsing of those ancestors will not consume too many digits (adjacent digit parsing).
element - chronological elementdigits - fixed count of digits in range 1-9IllegalArgumentException - if digits is out of
range 1-9 or if given element is not supported
by chronology or its preparserChronology.isSupported(ChronoElement),
SignPolicy.SHOW_NEVER,
ChronoFormatter.Builder.addInteger(ChronoElement, int, int, SignPolicy)public <V extends Enum<V>> ChronoFormatter.Builder<T> addNumerical(ChronoElement<V> element, int minDigits, int maxDigits)
Defines an integer format without sign for given chronological enumeration element.
If the element is compatible to the interface
NumericalElement then its value will first converted to
an integer else the ordinal number of enum will be used. A sign
is never printed or expected. Example:
ChronoFormatter<PlainDate> formatter =
ChronoFormatter.setUp(PlainDate.class, Locale.US)
.addNumerical(Weekmodel.of(Locale.US).localDayOfWeek(), 1, 1)
.build();
System.out.println(
formatter.format(PlainDate.of(2013, 6, 14))); // Freitag
// output: 6 (next to last day of US week)
V - generic type of element valueselement - chronological elementminDigits - minimum count of digits in range 1-9maxDigits - maximum count of digits in range 1-9IllegalArgumentException - if any of minDigits and
maxDigits are out of range 1-9 or if
maxDigits < minDigits or if given element is
not supported by chronology or its preparserIllegalStateException - if a numerical element is added
multiple times in a rowChronology.isSupported(ChronoElement),
NumericalElement.numerical(V),
SignPolicy.SHOW_NEVERpublic <V extends Enum<V>> ChronoFormatter.Builder<T> addFixedNumerical(ChronoElement<V> element, int digits)
Defines an integer format without sign and with fixed width for given chronological enumeration element.
Almost equivalent to addNumerical(element, digits, digits)
but with following important difference:
If this method directly follow after other numerical elements then the fixed width defined here will be preserved in preceding elements so parsing of those ancestors will not consume too many digits (adjacent digit parsing).
V - generic type of element valueselement - chronological elementdigits - fixed count of digits in range 1-9IllegalArgumentException - if digits is out of
range 1-9 or if given element is not supported
by chronology or its preparserChronology.isSupported(ChronoElement),
addNumerical(ChronoElement, int, int)public ChronoFormatter.Builder<T> addFraction(ChronoElement<Integer> element, int minDigits, int maxDigits, boolean decimalSeparator)
Defines a fractional format for given chronological element including a possible decimal separator char but without any integer part by mapping the context-dependent value range to the interval [0.0-1.0).
First a leading decimal separator char will be formatted
if required by last argument (for example in US the dot, in
Germany a comma). Then the fractional digits follow by mean of
the formula (value - min) / (max - min + 1). Possible
gaps like offset-jumps in the value range mapping will be kept.
The fractional representation is most suitable for elements
with a fixed value range, for example MINUTE_OF_HOUR
or MILLI_OF_SECOND.
minDigits
then it will be right-padded with zero digit char until there
are minDigits digits. But if there are more than
maxDigits then the sequence of digits will be
truncated. In the special case of minDigits == 0
and if the sequence to be formatted has no digits then the
diecimal separator char will be left out. maxDigits chars will be
interpreted as digits. If there are less than minDigits
then the text input will be invalid. Note: If there is just a
lax mode then the parser will always assume minDigits == 0
and maxDigits = 9 unless a fixed width was implicitly
specified by setting minDigits == maxDigits and without
decimal separator char (then adjacent digit parsing). Example:
ChronoElement<Integer> element = PlainTime.MICRO_OF_SECOND;
int minDigits = 3;
int maxDigits = 6;
ChronoFormatter<PlainTime> formatter =
ChronoFormatter.setUp(PlainTime.class, Locale.US)
.addFraction(
element,
minDigits,
maxDigits,
true
).build();
System.out.println(
formatter.format(PlainTime.of(12, 0, 0, 12345678)));
// output in US: .012345
Note: A fractional element must not be directly preceded by another numerical element.
element - chronological elementminDigits - minimum count of digits after decimal
separator in range 0-9maxDigits - maximum count of digits after decimal
separator in range 1-9decimalSeparator - shall decimal separator be visible?IllegalArgumentException - if minDigits is out of
range 0-9 or if maxDigits is out of range
1-9 or if maxDigits < minDigits or if
given element is not supported by chronology or its
preparser or if there is already a fractional or decimal
part definedChronology.isSupported(ChronoElement),
Attributes.LENIENCYpublic ChronoFormatter.Builder<T> addFixedDecimal(ChronoElement<BigDecimal> element, int precision, int scale)
Defines a fixed unsigned decimal format for given chronological element.
PRINT => If the resulting sequence of digits before
the decimal separator char has less than precision - scale
digits then it will be left-padded with zero digit chars. Otherwise
if there are more integer digits than allowed then an exception will
be thrown.
If the resulting sequence of digits after the decimal separator
is smaller than scale then the sequence will be right-padded
with zero digit chars. Otherwise the sequence of decimal digits will
be truncated if necessary.
precision chars will be
interpreted as digits in strict mode. Otherwise as many digits are
parsed as available and found. Example:
ChronoElement<BigDecimal> element = PlainTime.DECIMAL_MINUTE;
int precision = 3;
int scale = 1;
ChronoFormatter<PlainTime> formatter =
ChronoFormatter.setUp(PlainTime.class, Locale.US)
.addPattern("HH:", PatternType.CLDR)
.addFixedDecimal(element, precision, scale)
.build();
System.out.println(formatter.format(PlainTime.of(12, 8, 30)));
// output: 12:08.5
Note: A decimal element must not be directly preceded by another numerical element.
element - chronological elementprecision - total count of digits >= 2scale - digits after decimal separator >= 1IllegalArgumentException - if precision is smaller
than 2 or if scale is smaller than
1 or if precision <= scale or if
given element is not supported by chronology or its
preparser or if there is already a fractional or decimal
part definedChronology.isSupported(ChronoElement),
Attributes.LENIENCYpublic ChronoFormatter.Builder<T> addEnglishOrdinal(ChronoElement<Integer> element)
Defines an ordinal format for given chronological element in english language.
An ordinal indicator will be printed or parsed after a given sequence of digits. In English the indicators "st", "nd", "rd" and "th" are used dependent on the value of the element.
element - chronological elementIllegalArgumentException - if given element is not
supported by the underlying chronology or its preparserIllegalStateException - if a numerical element is added
multiple times in a rowChronology.isSupported(ChronoElement),
ChronoFormatter.Builder.addOrdinal(ChronoElement,Map)public ChronoFormatter.Builder<T> addOrdinal(ChronoElement<Integer> element, Map<PluralCategory,String> indicators)
Defines an ordinal format for given chronological element.
An ordinal indicator will be printed or parsed after a given sequence of digits. In English the indicators "st", "nd", "rd" and "th" are used dependent on the value of the element. In many other languages a fixed literal can be sufficient (although often context-dependent). This method is necessary if the indicators of a given language depend on the numerical value of the element.
Example for French generating HTML-text:
ChronoElement<Integer> element = PlainDate.DAY_OF_MONTH;
Map<PluralCategory, String> indicators =
new HashMap<PluralCategory, String>();
indicators.put(PluralCategory.ONE, "<sup>er</sup>");
indicators.put(PluralCategory.OTHER, "<sup>e</sup>");
ChronoFormatter<PlainDate> formatter =
ChronoFormatter.setUp(PlainDate.class, Locale.FRENCH)
.addOrdinal(element, indicators)
.addLiteral(" jour")
.build();
System.out.println(
formatter.format(PlainDate.of(2014, 8, 1)));
// output: 1<sup>er</sup> jour
Note that dependent on the context other strings can be necessary, for example French also uses feminine forms (for the week etc.).
element - chronological elementindicators - ordinal indicators to be used as suffixesIllegalArgumentException - if there is no indicator at least
for the plural category OTHER or if given element is not
supported by the underlying chronology or its preparserIllegalStateException - if a numerical element is added
multiple times in a rowChronology.isSupported(ChronoElement)public ChronoFormatter.Builder<T> addLiteral(char literal)
Defines a literal element with exactly one char.
Usually the literal char is a punctuation mark or a letter symbol. Decimal digits as literal chars are not recommended, especially not after preceding numerical elements.
literal - single literal charIllegalArgumentException - if the char represents
a non-printable ASCII-charpublic ChronoFormatter.Builder<T> addLiteral(char literal, char alt)
Defines a literal element with exactly one char which can also be an alternative char during parsing.
Usually the literal char is a punctuation mark or a letter symbol. Decimal digits as literal chars are not recommended, especially not after preceding numerical elements.
literal - single literal char (preferred in printing)alt - alternative literal char for parsingIllegalArgumentException - if any char represents a non-printable ASCII-charpublic ChronoFormatter.Builder<T> addLiteral(String literal)
Defines a literal element with any chars.
Usually the literal char sequence consists of punctuation marks or letter symbols. Leading decimal digits as literal chars are not recommended, especially not after preceding numerical elements.
literal - literal char sequenceIllegalArgumentException - if given literal is empty
or starts with a non-printable ASCII-charpublic ChronoFormatter.Builder<T> addLiteral(AttributeKey<Character> attribute)
Defines a literal element with a char which will be searched in given format attribute.
A localized decimal separator char as literal will be possible
if the argument is equal to Attributes.DECIMAL_SEPARATOR.
Note: If given format attribute does not exist at runtime then
the formatting will fail.
attribute - attribute defining a literal charpublic ChronoFormatter.Builder<T> addIgnorableWhitespace()
Defines a sequence of optional white space.
If printed a space char will be used. In parsing however, any white space of arbitrary length will be ignored and skipped.
public ChronoFormatter.Builder<T> skipUnknown(int keepRemainingChars)
Skips all characters from input as unparseable until at least given count of characters is left.
Note: This method is only relevant for parsing. During printing, this method does nothing.
keepRemainingChars - minimum count of characters which should be reserved for following stepsIllegalArgumentException - if keepRemainingChars < 0ChronoFormatter.Builder.skipUnknown(ChronoCondition, int),
Attributes.TRAILING_CHARACTERSpublic ChronoFormatter.Builder<T> skipUnknown(ChronoCondition<Character> unparseableCondition, int maxIterations)
Skips all characters accepted by given condition as unparseable.
Starting with v4.14, the first argument will be replaced by a java.util.function.IntPredicate
in order to enable easier lambda expressions. If the condition always returns true then
maxIterations effectively models a fixed width of characters to be skipped.
Note: This method is only relevant for parsing. During printing, this method does nothing.
Specification: The first condition argument must be immutable or stateless (for example a lambda expression).
unparseableCondition - condition which marks accepted characters as unparseablemaxIterations - maximum count of invocations on given conditionIllegalArgumentException - if maxIterations < 1ChronoFormatter.Builder.skipUnknown(int)public ChronoFormatter.Builder<T> addPattern(String formatPattern, PatternType patternType)
Processes given format pattern of given pattern type to a sequence of format elements.
The letters a-z and A-Z are treated as format symbols. The square brackets
"[" and "]" define an optional section
which can be nested, too. The char "|" starts a new or-block. And
the chars "#", "{" and "}" are reserved for the future. All
other chars will be interpreted as literals. If a reserved char shall be treated as literal
then it must be escaped by the apostroph "'". The apostroph itself can be
treated as literal by double apostroph.
For exact interpretation and description of format symbols
see the implementations of interface ChronoPattern.
formatPattern - pattern of symbols to be used in formattingpatternType - type of pattern how to interprete symbolsIllegalArgumentException - if resolving of pattern failsPatternTypepublic ChronoFormatter.Builder<T> addText(TextElement<?> element)
Defines a text format for given chronological element.
element - chronological text elementIllegalArgumentException - if given element is not
supported by chronology or its preparserChronology.isSupported(ChronoElement)public <V extends Enum<V>> ChronoFormatter.Builder<T> addText(ChronoElement<V> element)
Defines a text format for given chronological element.
V - generic type of element valueselement - chronological elementIllegalArgumentException - if given element is not
supported by chronologyChronology.isSupported(ChronoElement)public <V extends Enum<V>> ChronoFormatter.Builder<T> addText(ChronoElement<V> element, Map<V,String> lookup)
Defines a text format for given chronological element with user-defined string resources.
V - generic type of element valueselement - chronological elementlookup - text resources for lookupIllegalArgumentException - if given element is not
supported by chronology or its preparserChronology.isSupported(ChronoElement)public ChronoFormatter.Builder<T> addDayPeriodFixed()
Defines a text format for a fixed day period (am/pm/midnight/noon).
IllegalStateException - if the underlying chronology does not support day periodsDayPeriod.fixed()public ChronoFormatter.Builder<T> addDayPeriodApproximate()
Defines a text format for a flexible day period (morning/afternoon etc).
IllegalStateException - if the underlying chronology does not support day periodsDayPeriod.approximate()public ChronoFormatter.Builder<T> addDayPeriod(Map<PlainTime,String> timeToLabels)
Defines a text format for a custom day period.
timeToLabels - mapping from start times to custom dayperiod labelsIllegalStateException - if already called once or if the underlying chronology
does not support day periodsIllegalArgumentException - if given map is empty or contains empty valuesDayPeriod.of(Map)public <V extends ChronoEntity<V>> ChronoFormatter.Builder<T> addCustomized(ChronoElement<V> element, ChronoFormatter<V> formatter)
Defines a customized format element for given chronological element.
V - generic type of element valueselement - chronological elementformatter - customized formatter object as delegateIllegalArgumentException - if given element is not
supported by chronology or its preparserChronology.isSupported(ChronoElement)public <V> ChronoFormatter.Builder<T> addCustomized(ChronoElement<V> element, ChronoPrinter<V> printer, ChronoParser<V> parser)
Defines a customized format element for given chronological element.
V - generic type of element valueselement - chronological elementprinter - customized printerparser - customized parserIllegalArgumentException - if given element is not
supported by chronology or its preparserChronology.isSupported(ChronoElement)public ChronoFormatter.Builder<T> addTwoDigitYear(ChronoElement<Integer> element)
Defines a special format element for a two-digit-year.
It is possible to specify a pivot year by setting the
attribute Attributes.PIVOT_YEAR to a meaningful year.
If this attribute is missing then Time4J will set the year
twenty years after now as pivot year by default.
If this format element is directly preceded by other numerical elements with variable width then the fixed width of 2 will be preserved such that the preceding elements will not consume too many digits (adjacent digit parsing). Otherwise this format element can also parse more than two digits if there is no strict mode with the consequence that the parsed year will be interpreted as absolute full year.
element - year element (name must start with the
prefix "YEAR")IllegalArgumentException - if given element is not
supported by chronologyAttributes.PIVOT_YEARpublic ChronoFormatter.Builder<T> addTimezoneID()
Adds a timezone identifier.
Parsing of a timezone ID is case-sensitive. All timezone IDs
which will be provided by Timezone.getAvailableIDs()
will be supported - with the exception of old IDs like
"Asia/Riyadh87" or "CST6CDT" which contain
some digits. Offset-IDs like the canonical form of
ZonalOffset or "GMT" are supported, too.
An exceptional case are again deprecated IDs like
"Etc/GMT+12".
IllegalStateException - if the underlying chronology does not correspond
to the type UnixTimepublic ChronoFormatter.Builder<T> addShortTimezoneName()
Adds a short localized timezone name (an abbreviation).
Dependent on the current locale, the preferred timezone IDs in a country will be determined first. The parsing of timezone names is case-sensitive.
Note that Time4J will try to find a unique mapping from names to IDs for US in smart parsing mode. However, this is only an imperfect approximation to current practice. A counter example is Phoenix which does not observe daylight savings although it has the same name "MST" as Denver.
ChronoFormatter.Builder.addShortTimezoneName(Set)public ChronoFormatter.Builder<T> addLongTimezoneName()
Adds a long localized timezone name.
Dependent on the current locale, the preferred timezone IDs in a country will be determined first. The parsing of timezone names is case-sensitive.
Note that Time4J will try to find a unique mapping from names to IDs for US in smart parsing mode. However, this is only an imperfect approximation to current practice. A counter example is Phoenix which does not observe daylight savings although it has the same name "Mountain Standard Time" as Denver.
ChronoFormatter.Builder.addLongTimezoneName(Set)public ChronoFormatter.Builder<T> addShortTimezoneName(Set<TZID> preferredZones)
Adds a short localized timezone name (an abbreviation).
Parsing of timezone names is case-sensitive.
preferredZones - preferred timezone ids for resolving
duplicatesChronoFormatter.Builder.addLongTimezoneName(Set)public ChronoFormatter.Builder<T> addLongTimezoneName(Set<TZID> preferredZones)
Adds a long localized timezone name.
Parsing of timezone names is case-sensitive.
preferredZones - preferred timezone ids for resolving
duplicatesChronoFormatter.Builder.addShortTimezoneName(Set)public ChronoFormatter.Builder<T> addTimezoneOffset()
Adds a timezone offset in typical ISO-8601-notation.
The offset format is "±HH:mm" or in case of
zero offset simply "Z". Equivalent to the expression
addTimezoneOffset(DisplayMode.MEDIUM, true,
Collections.singletonList("Z")).
public ChronoFormatter.Builder<T> addTimezoneOffset(DisplayMode precision, boolean extended, List<String> zeroOffsets)
Adds a timezone offset in canonical notation.
This format element is also applicable on chronological
entities without timezone reference like PlainTime
provided that a timezone offset is set as format attribute.
Dependent on given arguments following formats are
defined:
| SHORT | MEDIUM | LONG | FULL | |
|---|---|---|---|---|
| basic | ±HH[mm] | ±HHmm | ±HHmm[ss[.{fraction}]] | ±HHmmss[.{fraction}] |
| extended | ±HH[:mm] | ±HH:mm | ±HH:mm[:ss[.{fraction}]] | ±HH:mm:ss[.{fraction}] |
Notes: All components given in square brackets are optional.
During printing, they will only appear if they are different from 0.
During parsing, they can be left out of the text to be parsed. A fractional
second part with 9 digits is always optional (unless a dot exists)
and is only possible in case of a longitudinal offset. The modes
SHORT and MEDIUM correspond to ISO-8601 where an offset should
only have hours and minutes. The hour part might consist of one digit
only if the parsing mode is not strict.
The third argument determines what kind of text should be interpreted as zero offset. The formatted output always uses the first list entry while parsing expects any list entries.
precision - display mode of offset formatextended - extended or basic ISO-8601-modezeroOffsets - list of replacement texts if offset is zeroIllegalArgumentException - if any replacement text consists
of white-space only or if given replacement list is emptyChronoEntity.getTimezone()public ChronoFormatter.Builder<T> addShortLocalizedOffset()
Adds a timezone offset in short localized notation.
This format element is also applicable on chronological
entities without timezone reference like PlainTime
provided that a timezone offset is set as format attribute.
The format "GMT±H[:mm[:ss]]" will be used.
Notes: The minute component given in square brackets is
optional in short format and appears only if it is different
from 0. The GMT-prefix can also be like "UTC"
or "UT" when parsing. A localized GMT-notation is
possible provided that the resource files
"iso8601.properties" have an entry with the key
"prefixGMTOffset". If the format attribute
Attributes.NO_GMT_PREFIX is set to true
then the GMT-prefix will be suppressed. The format attribute
Attributes.ZERO_DIGIT (usually set indirect via the
locale) controls which localized set of digits will be used.
The sign is possibly localized, too.
ChronoEntity.getTimezone(),
ChronoFormatter.Builder.addLongLocalizedOffset(),
Attributes.NO_GMT_PREFIXpublic ChronoFormatter.Builder<T> addLongLocalizedOffset()
Adds a timezone offset in long localized notation.
This format element is also applicable on chronological
entities without timezone reference like PlainTime
provided that a timezone offset is set as format attribute.
The format "GMT±HH:mm[:ss]" will be used.
Notes: The GMT-prefix can also be like "UTC"
or "UT" when parsing. A localized GMT-notation is
possible provided that the resource files
"iso8601.properties" have an entry with the key
"prefixGMTOffset". If the format attribute
Attributes.NO_GMT_PREFIX is set to true
then the GMT-prefix will be suppressed. The format attribute
Attributes.ZERO_DIGIT (usually set indirect via the
locale) controls which localized set of digits will be used.
The sign is possibly localized, too.
ChronoEntity.getTimezone(),
ChronoFormatter.Builder.addShortLocalizedOffset(),
Attributes.NO_GMT_PREFIXpublic ChronoFormatter.Builder<T> padNext(int width)
Defines for the next format element of the same section so many pad chars until the element width has reached the width specified.
Note: This method will be ignored if it is directly followed by a new section or if the current section is closed or if there are no more format elements.
width - fixed width of following format stepIllegalArgumentException - if given width is negativeAttributes.PAD_CHAR,
ChronoFormatter.Builder.padPrevious(int)public ChronoFormatter.Builder<T> padPrevious(int width)
Defines for the previous format element of the same section so many pad chars until the element width has reached the width specified.
width - fixed width of previous format stepIllegalArgumentException - if given width is negativeAttributes.PAD_CHAR,
ChronoFormatter.Builder.padNext(int)public ChronoFormatter.Builder<T> startOptionalSection()
Starts a new optional section where errors in parsing will not cause an exception but just be ignored.
public ChronoFormatter.Builder<T> startOptionalSection(ChronoCondition<ChronoDisplay> printCondition)
Starts a new optional section where errors in parsing will not cause an exception but just be ignored.
printCondition - optional condition for printingpublic ChronoFormatter.Builder<T> startSection(AttributeKey<Boolean> key, boolean value)
Starts a new section with given sectional attribute.
The new section takes over all attributes of current section
if available. Sectional attributes cannot be overridden by the
default attributes of ChronoFormatter.
key - attribute keyvalue - attribute valuepublic ChronoFormatter.Builder<T> startSection(AttributeKey<Integer> key, int value)
Starts a new section with given sectional attribute.
The new section takes over all attributes of current section
if available. Sectional attributes cannot be overridden by the
default attributes of ChronoFormatter.
key - attribute keyvalue - attribute valuepublic ChronoFormatter.Builder<T> startSection(AttributeKey<Character> key, char value)
Starts a new section with given sectional attribute.
The new section takes over all attributes of current section
if available. Sectional attributes cannot be overridden by the
default attributes of ChronoFormatter.
key - attribute keyvalue - attribute valuepublic <A extends Enum<A>> ChronoFormatter.Builder<T> startSection(AttributeKey<A> key, A value)
Starts a new section with given sectional attribute.
The new section takes over all attributes of current section
if available. Sectional attributes cannot be overridden by the
default attributes of ChronoFormatter.
A - generic type of attribute (enum-based)key - attribute keyvalue - attribute valuepublic ChronoFormatter.Builder<T> endSection()
Removes the last sectional attribute.
NoSuchElementException - if there is no section
which was started with startSection()ChronoFormatter.Builder.startSection(AttributeKey, boolean),
ChronoFormatter.Builder.startSection(AttributeKey, Enum),
ChronoFormatter.Builder.startSection(AttributeKey, int),
ChronoFormatter.Builder.startSection(AttributeKey, char)public ChronoFormatter.Builder<T> or()
Starts a new block inside the current section such that the following parts will only be taken into account in case of failure according to or-logic.
Example of usage (here with format pattern char "|"):
ChronoFormatter<PlainDate> f =
ChronoFormatter.ofDatePattern("E, [dd.MM.|MM/dd/]uuuu", PatternType.CLDR, Locale.ENGLISH);
PlainDate expected = PlainDate.of(2015, 12, 31);
assertThat(f.parse("Thu, 31.12.2015"), is(expected));
assertThat(f.parse("Thu, 12/31/2015"), is(expected));
Note: Or-blocks can also be used outside of an optional section.
IllegalStateException - if called twice
or called after the end of an optional section
or if there is not yet any defined format step in current sectionpublic ChronoFormatter<T> build()
Finishes the build and creates a new ChronoFormatter.
ChronoFormatter-instanceIllegalStateException - if there is no format element at all or none after or-operator in same sectionCopyright © 2014–2016. All rights reserved.