public final class DateTimeFormatterBuilder extends Object
All date-time formatters are created ultimately using this builder.
Each consists of two halves a printer
and a parser
.
Most of the methods will create both a printer and a parser automatically, however
it is possible to create a formatter that only prints or only parses.
The basic elements of calendricals can all be added:
zone offset
time-zone
id
Finally, a shorthand pattern, mostly compatible with SimpleDateFormat
can be used, see appendPattern(String)
.
In practice, this simply parses the pattern and calls other methods on the builder.
Modifier and Type | Class and Description |
---|---|
static class |
DateTimeFormatterBuilder.FormatStyle
Enumeration of the style of a localized date, time or date-time formatter.
|
static class |
DateTimeFormatterBuilder.SignStyle
Enumeration of ways to handle the positive/negative sign.
|
static class |
DateTimeFormatterBuilder.TextStyle
Enumeration of the style of text output to use.
|
Constructor and Description |
---|
DateTimeFormatterBuilder()
Constructs a new instance of the builder.
|
Modifier and Type | Method and Description |
---|---|
DateTimeFormatterBuilder |
append(DateTimeFormatter formatter)
Appends all the elements of a formatter to the builder.
|
DateTimeFormatterBuilder |
append(DateTimePrinter printer,
DateTimeParser parser)
Appends a printer and/or parser to the formatter.
|
DateTimeFormatterBuilder |
appendFraction(DateTimeFieldRule<?> rule,
int minWidth,
int maxWidth)
Appends the fractional value of a date-time field to the formatter.
|
DateTimeFormatterBuilder |
appendLiteral(char literal)
Appends a character literal to the formatter.
|
DateTimeFormatterBuilder |
appendLiteral(String literal)
Appends a string literal to the formatter.
|
DateTimeFormatterBuilder |
appendLocalized(DateTimeFormatterBuilder.FormatStyle dateStyle,
DateTimeFormatterBuilder.FormatStyle timeStyle)
Appends a localized date-time pattern to the formatter.
|
DateTimeFormatterBuilder |
appendLocalized(DateTimeFormatterBuilder.FormatStyle dateStyle,
DateTimeFormatterBuilder.FormatStyle timeStyle,
Chronology chronology)
Appends a localized date-time pattern to the formatter.
|
DateTimeFormatterBuilder |
appendOffset(String utcText,
boolean includeColon,
boolean allowSeconds)
Appends the zone offset, such as '+01:00', to the formatter.
|
DateTimeFormatterBuilder |
appendOffsetId()
Appends the zone offset, such as '+01:00', to the formatter.
|
DateTimeFormatterBuilder |
appendOptional(DateTimeFormatter formatter)
Appends a formatter to the builder which will optionally print/parse.
|
DateTimeFormatterBuilder |
appendPattern(String pattern)
Appends the elements defined by the specified pattern to the builder.
|
DateTimeFormatterBuilder |
appendText(DateTimeFieldRule<?> rule)
Appends the text of a date-time field to the formatter using the full
text style.
|
DateTimeFormatterBuilder |
appendText(DateTimeFieldRule<?> rule,
DateTimeFormatterBuilder.TextStyle textStyle)
Appends the text of a date-time field to the formatter.
|
DateTimeFormatterBuilder |
appendValue(DateTimeFieldRule<?> rule)
Appends the value of a date-time field to the formatter using a normal
output style.
|
DateTimeFormatterBuilder |
appendValue(DateTimeFieldRule<?> rule,
int width)
Appends the value of a date-time field to the formatter using a fixed
width, zero-padded approach.
|
DateTimeFormatterBuilder |
appendValue(DateTimeFieldRule<?> rule,
int minWidth,
int maxWidth,
DateTimeFormatterBuilder.SignStyle signStyle)
Appends the value of a date-time field to the formatter providing full
control over printing.
|
DateTimeFormatterBuilder |
appendValueReduced(DateTimeFieldRule<?> rule,
int width,
int baseValue)
Appends the reduced value of a date-time field to the formatter.
|
DateTimeFormatterBuilder |
appendZoneId()
Appends the time-zone rule id, such as 'Europe/Paris', to the formatter.
|
DateTimeFormatterBuilder |
appendZoneText(DateTimeFormatterBuilder.TextStyle textStyle)
Appends the time-zone rule name, such as 'British Summer Time', to the formatter.
|
DateTimeFormatterBuilder |
optionalEnd()
Ends an optional section.
|
DateTimeFormatterBuilder |
optionalStart()
Mark the start of an optional section.
|
DateTimeFormatterBuilder |
padNext(int padWidth)
Causes the next added printer/parser to pad to a fixed width using a space.
|
DateTimeFormatterBuilder |
padNext(int padWidth,
char padChar)
Causes the next added printer/parser to pad to a fixed width.
|
DateTimeFormatterBuilder |
parseCaseInsensitive()
Changes the parse style to be case insensitive for the remainder of the formatter.
|
DateTimeFormatterBuilder |
parseCaseSensitive()
Changes the parse style to be case sensitive for the remainder of the formatter.
|
DateTimeFormatterBuilder |
parseLenient()
Changes the parse style to be lenient for the remainder of the formatter.
|
DateTimeFormatterBuilder |
parseStrict()
Changes the parse style to be strict for the remainder of the formatter.
|
DateTimeFormatter |
toFormatter()
Completes this builder by creating the DateTimeFormatter using the default locale.
|
DateTimeFormatter |
toFormatter(Locale locale)
Completes this builder by creating the DateTimeFormatter using the specified locale.
|
public DateTimeFormatterBuilder()
public DateTimeFormatterBuilder parseCaseSensitive()
Parsing can be case sensitive or insensitive - by default it is case sensitive. This controls how text is compared.
When used, this method changes the parsing to be case sensitive from this point onwards.
As case sensitive is the default, this is normally only needed after calling parseCaseInsensitive()
.
The change will remain in force until the end of the formatter that is eventually
constructed or until parseCaseInsensitive
is called.
public DateTimeFormatterBuilder parseCaseInsensitive()
Parsing can be case sensitive or insensitive - by default it is case sensitive. This controls how text is compared.
When used, this method changes the parsing to be case insensitive from this point onwards.
The change will remain in force until the end of the formatter that is eventually
constructed or until parseCaseSensitive
is called.
public DateTimeFormatterBuilder parseStrict()
Parsing can be strict or lenient - by default its strict. This controls the degree of flexibility in matching the text and sign styles.
When used, this method changes the parsing to be strict from this point onwards.
As strict is the default, this is normally only needed after calling parseLenient()
.
The change will remain in force until the end of the formatter that is eventually
constructed or until parseLenient
is called.
public DateTimeFormatterBuilder parseLenient()
Parsing can be strict or lenient - by default its strict. This controls the degree of flexibility in matching the text and sign styles.
When used, this method changes the parsing to be strict from this point onwards.
The change will remain in force until the end of the formatter that is eventually
constructed or until parseStrict
is called.
public DateTimeFormatterBuilder appendValue(DateTimeFieldRule<?> rule)
The value of the field will be output during a print. If the value cannot be obtained then an exception will be thrown.
The value will be printed as per the normal print of an integer value. Only negative numbers will be signed. No padding will be added.
The parser for a variable width value such as this normally behaves greedily, accepting as many
digits as possible. This behavior can be affected by 'adjacent value parsing'.
See appendValue(DateTimeFieldRule, int)
for full details.
rule
- the rule of the field to append, not nullNullPointerException
- if the field rule is nullpublic DateTimeFormatterBuilder appendValue(DateTimeFieldRule<?> rule, int width)
The value of the field will be output during a print. If the value cannot be obtained then an exception will be thrown.
The value will be zero-padded on the left. If the size of the value means that it cannot be printed within the width then an exception is thrown. If the value of the field is negative then an exception is thrown during printing.
This method supports a special technique of parsing known as 'adjacent value parsing'. This technique solves the problem where a variable length value is followed by one or more fixed length values. The standard parser is greedy, and thus it would normally steal the digits that are needed by the fixed width value parsers that follow the variable width one.
No action is required to initiate 'adjacent value parsing'.
When a call to appendValue
with a variable width is made, the builder
enters adjacent value parsing setup mode. If the immediately subsequent method
call or calls on the same builder are to this method, then the parser will reserve
space so that the fixed width values can be parsed.
For example, consider builder.appendValue(yearRule).appendValue(monthRule, 2);
The year is a variable width parse of between 1 and 10 digits.
The month is a fixed width parse of 2 digits.
Because these were appended to the same builder immediately after one another,
the year parser will reserve two digits for the month to parse.
Thus, the text '200906' will correctly parse to a year of 2009 and a month of 6.
Without adjacent value parsing, the year would greedily parse all six digits and leave
nothing for the month.
Adjacent value parsing applies to each set of fixed width not-negative values in the parser
that immediately follow any kind of variable width value.
Calling any other append method will end the setup of adjacent value parsing.
Thus, in the unlikely event that you need to avoid adjacent value parsing behavior,
simply add the appendValue
to another DateTimeFormatterBuilder
and add that to this builder.
If the four-parameter version of appendValue
is called with equal minimum
and maximum widths and a sign style of not-negative then it delegates to this method.
rule
- the rule of the field to append, not nullwidth
- the width of the printed field, from 1 to 10NullPointerException
- if the field rule is nullIllegalArgumentException
- if the width is invalidpublic DateTimeFormatterBuilder appendValue(DateTimeFieldRule<?> rule, int minWidth, int maxWidth, DateTimeFormatterBuilder.SignStyle signStyle)
The value of the field will be output during a print. If the value cannot be obtained then an exception will be thrown.
This method provides full control of the numeric formatting, including zero-padding and the positive/negative sign.
The parser for a variable width value normally behaves greedily, accepting as many
digits as possible. This behavior can be affected by 'adjacent value parsing'.
See appendValue(DateTimeFieldRule, int)
for full details.
rule
- the rule of the field to append, not nullminWidth
- the minimum field width of the printed field, from 1 to 10maxWidth
- the maximum field width of the printed field, from 1 to 10signStyle
- the positive/negative output style, not nullNullPointerException
- if the field rule or sign style is nullIllegalArgumentException
- if the widths are invalidpublic DateTimeFormatterBuilder appendValueReduced(DateTimeFieldRule<?> rule, int width, int baseValue)
This is typically used for printing and parsing a two digit year.
The width
is the printed and parsed width.
The baseValue
is used during parsing to determine the valid range.
For printing, the width is used to determine the number of characters to print. The rightmost characters are output to match the width, left padding with zero.
For parsing, exactly the number of characters specified by the width are parsed. This is incomplete information however, so the base value is used to complete the parse. The base value is the first valid value in a range of ten to the power of width.
For example, a base value of 1980
and a width of 2
will have
valid values from 1980
to 2079
.
During parsing, the text "12"
will result in the value 2012
as that
is the value within the range where the last two digits are "12".
This is a fixed width parser operating using 'adjacent value parsing'.
See appendValue(DateTimeFieldRule, int)
for full details.
rule
- the rule of the field to append, not nullwidth
- the width of the printed and parsed field, from 1 to 8baseValue
- the base value of the range of valid valuesNullPointerException
- if the field rule is nullIllegalArgumentException
- if the width or base value is invalidpublic DateTimeFormatterBuilder appendFraction(DateTimeFieldRule<?> rule, int minWidth, int maxWidth)
The fractional value of the field will be output including the
preceeding decimal point. The preceeding value is not output.
The fraction is obtained using DateTimeFieldRule.convertIntToFraction(int)
.
The width of the output fraction can be controlled. Setting the minimum width to zero will cause no output to be generated. The output fraction will have the minimum width necessary between the minimum and maximum widths - trailing zeroes are omitted. No rounding occurs due to the maximum width - digits are simply dropped.
If the value cannot be obtained then an exception will be thrown. If the value is negative an exception will be thrown. If the field does not have a fixed set of valid values then an exception will be thrown. If the field value in the calendrical to be printed is invalid it cannot be printed and an exception will be thrown.
rule
- the rule of the field to append, not nullminWidth
- the minimum width of the field excluding the decimal point, from 0 to 9maxWidth
- the maximum width of the field excluding the decimal point, from 1 to 9NullPointerException
- if the field rule or sign style is nullIllegalArgumentException
- if the field has a variable set of valid valuesIllegalArgumentException
- if the field has a non-zero minimumIllegalArgumentException
- if the widths are invalidpublic DateTimeFormatterBuilder appendText(DateTimeFieldRule<?> rule)
The text of the field will be output during a print. If the value cannot be obtained then an exception will be thrown. If the field has no textual representation, then the numeric value will be used.
The value will be printed as per the normal print of an integer value. Only negative numbers will be signed. No padding will be added.
rule
- the rule of the field to append, not nullNullPointerException
- if the field rule is nullpublic DateTimeFormatterBuilder appendText(DateTimeFieldRule<?> rule, DateTimeFormatterBuilder.TextStyle textStyle)
The text of the field will be output during a print. If the value cannot be obtained then an exception will be thrown. If the field has no textual representation, then the numeric value will be used.
The value will be printed as per the normal print of an integer value. Only negative numbers will be signed. No padding will be added.
rule
- the rule of the field to append, not nulltextStyle
- the text style to use, not nullNullPointerException
- if the field rule or text style is nullpublic DateTimeFormatterBuilder appendOffsetId()
The zone offset id will be output during a print. If the offset cannot be obtained then an exception will be thrown.
The output id is minor variation to the standard ISO-8601 format. There are three formats:
public DateTimeFormatterBuilder appendOffset(String utcText, boolean includeColon, boolean allowSeconds)
The zone offset will be output during a print. If the offset cannot be obtained then an exception will be thrown. The output format is controlled by the specified parameters.
The UTC text controls what text is printed when the offset is zero. Example values would be 'Z', '+00:00', 'UTC' or 'GMT'.
The include colon parameter controls whether a colon should separate the numeric fields or not.
The allow seconds parameter controls whether seconds may be output. If false then seconds are never output. If true then seconds are only output if non-zero.
utcText
- the text to use for UTC, not nullincludeColon
- whether to include a colonallowSeconds
- whether to allow secondsNullPointerException
- if the UTC text is nullpublic DateTimeFormatterBuilder appendZoneId()
The time-zone id will be output during a print. If the zone cannot be obtained then an exception will be thrown.
public DateTimeFormatterBuilder appendZoneText(DateTimeFormatterBuilder.TextStyle textStyle)
The time-zone name will be output during a print. If the zone cannot be obtained then an exception will be thrown.
The zone name is obtained from the formatting symbols. Different names may be output depending on whether daylight savings time applies.
If the date, time or offset cannot be obtained it may not be possible to determine which text to output. In this case, the text representing time without daylight savings (winter time) will be used.
textStyle
- the text style to use, not nullNullPointerException
- if the text style is nullpublic DateTimeFormatterBuilder appendLocalized(DateTimeFormatterBuilder.FormatStyle dateStyle, DateTimeFormatterBuilder.FormatStyle timeStyle)
The pattern is resolved lazily using the locale being used during the print/parse
(stored in DateTimeFormatter
.
The pattern can vary by chronology, although typically it doesn't. This method uses the standard ISO chronology patterns.
dateStyle
- the date style to use, null means no date requiredtimeStyle
- the time style to use, null means no time requiredNullPointerException
- if the text style is nullpublic DateTimeFormatterBuilder appendLocalized(DateTimeFormatterBuilder.FormatStyle dateStyle, DateTimeFormatterBuilder.FormatStyle timeStyle, Chronology chronology)
The pattern is resolved lazily using the locale being used during the print/parse
(stored in DateTimeFormatter
.
The pattern can vary by chronology, although typically it doesn't. This method allows the chronology to be specified.
dateStyle
- the date style to use, null means no date requiredtimeStyle
- the time style to use, null means no time requiredchronology
- the chronology to use, not nullNullPointerException
- if the text style is nullpublic DateTimeFormatterBuilder appendLiteral(char literal)
This character will be output during a print.
literal
- the literal to append, not nullpublic DateTimeFormatterBuilder appendLiteral(String literal)
This string will be output during a print.
If the literal is empty, nothing is added to the formatter.
literal
- the literal to append, not nullNullPointerException
- if the literal is nullpublic DateTimeFormatterBuilder append(DateTimePrinter printer, DateTimeParser parser)
If one of the two parameters is null then the formatter will only be able to print or parse. If both are null, an exception is thrown.
printer
- the printer to add, null prevents the formatter from printingparser
- the parser to add, null prevents the formatter from parsingNullPointerException
- if both printer and parser are nullpublic DateTimeFormatterBuilder append(DateTimeFormatter formatter)
This method has the same effect as appending each of the constituent parts of the formatter directly to this builder.
formatter
- the formatter to add, not nullNullPointerException
- if the formatter is nullpublic DateTimeFormatterBuilder appendOptional(DateTimeFormatter formatter)
This method has the same effect as appending each of the constituent
parts directly to this builder surrounded by an optionalStart()
and
optionalEnd()
.
The formatter will print if data is available for all the fields contained within it. The formatter will parse if the string matches, otherwise no error is returned.
formatter
- the formatter to add, not nullNullPointerException
- if the formatter is nullpublic DateTimeFormatterBuilder appendPattern(String pattern)
All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The following pattern letters are defined:
Symbol Meaning Presentation Examples ------ ------- ------------ ------- y year year 2004; 04 D day-of-year number 189 M month-of-year month July; Jul; 07 d day-of-month number 10 Q quarter-of-year number 3 q month-of-quarter number 2 x week-based-year year 1996 w week-of-week-based-year number 27 e day-of-week number 2 E day-of-week text Tuesday; Tue F week-of-month number 3 a am-pm-of-day text PM h clock-hour-of-am-pm (1-12) number 12 K hour-of-am-pm (0-11) number/fraction 0 k clock-hour-of-am-pm (1-24) number 0 H hour-of-day (0-23) number/fraction 0 m minute-of-hour number/fraction 30 s second-of-minute number/fraction 55 S milli-of-second number/fraction 978 n nano-of-second number/fraction 987654321 I time-zone ID zoneID America/Los_Angeles z time-zone name text Pacific Standard Time; PST Z zone-offset offset -0800; -08:00; f make next a fraction fraction modifier .123 p pad next pad modifier 1 ' escape for text delimiter '' single quote literal ' [ optional section start ] optional section end
The count of pattern letters determine the format.
Text: If the number of pattern letters is 4 or more, the full textual form is used
as per DateTimeFormatterBuilder.TextStyle.FULL
. Otherwise a short form is used, as per DateTimeFormatterBuilder.TextStyle.SHORT
.
Number: If the count of letters is one, then the value is printed using the minimum number
of digits and without padding as per appendValue(DateTimeFieldRule)
. Otherwise, the
count of digits is used as the width of the output field as per appendValue(DateTimeFieldRule, int)
.
Fraction modifier: Modifies the pattern that immediately follows to be a fraction. All fractional values must use the 'f' prefix to ensure correct parsing. The fraction also outputs the decimal point. If the count of 'f' is one, then the fractional value has the exact number of digits defined by the count of the value being output. If the count of 'f' is two or more, then the fractional value has the a minimum number of digits defined by the count of the value being output and a maximum output of nine digits.
For example, 'ssffnnn' outputs the second followed by 3-9 digits of the nanosecond, while 'mmfss' outputs the minute followed by exactly 2 digits representing the second.
Year: The count of letters determines the minimum field width below which padding is used.
If the count of letters is two, then a reduced
two digit form is used.
For printing, this outputs the rightmost two digits. For parsing, this will parse using the
base value of 2000, resulting in a year within the range 2000 to 2099 inclusive.
If the count of letters is less than four (but not two), then the sign is only output for negative
years as per DateTimeFormatterBuilder.SignStyle.NORMAL
.
Otherwise, the sign is output if the pad width is exceeded, as per DateTimeFormatterBuilder.SignStyle.EXCEEDS_PAD
Month: If the count of letters is 3 or greater, use the Text rules above. Otherwise use the Number rules above.
ZoneID: 'I' outputs the zone id, such as 'Europe/Paris'.
Offset: 'Z' outputs offset without a colon, without seconds and '+0000' as the text for UTC. 'ZZ' outputs the offset with a colon, without seconds and '+00:00' as the text for UTC. 'ZZZ' outputs offset without a colon, with seconds and 'Z' as the text for UTC (ISO-8601 style). 'ZZZZ' outputs the offset with a colon, with seconds and 'Z' as the text for UTC (ISO-8601 style).
Zone names: Time zone names ('z') cannot be parsed.
Optional section: The optional section markers work exactly like calling optionalStart()
and optionalEnd()
.
Pad modifier: Modifies the pattern that immediately follows to be padded with spaces.
The pad width is determined by the number of pattern letters.
This is the same as calling padNext(int)
.
For example, 'ppH' outputs the hour-of-day padded on the left with spaces to a width of 2.
Any unrecognized letter will be output directly. However, since these are reserved, that may change in future versions. Any non-letter character, other than '[', ']' and the single quote will be output directly. Despite this, it is recommended to use single quotes around all characters that you want to output directly to ensure that future changes do not break your application.
The pattern string is similar, but not identical, to SimpleDateFormat
.
SimpleDateFormat pattern letters 'G' and 'W' are not available.
Pattern letters 'x', 'Q', 'q', 'e', 'n', 'I', 'f' and 'p' are added.
Letters 'y', 'z' and 'Z' have some differences.
pattern
- the pattern to add, not nullNullPointerException
- if the pattern is nullIllegalArgumentException
- if the pattern is invalidpublic DateTimeFormatterBuilder padNext(int padWidth)
This padding will pad to a fixed width using spaces.
An exception will be thrown during printing if the pad width is exceeded.
padWidth
- the pad width, 1 or greaterIllegalArgumentException
- if pad width is too smallpublic DateTimeFormatterBuilder padNext(int padWidth, char padChar)
This padding is intended for padding other than zero-padding. Zero-padding should be achieved using the appendValue methods.
An exception will be thrown during printing if the pad width is exceeded.
padWidth
- the pad width, 1 or greaterpadChar
- the pad characterIllegalArgumentException
- if pad width is too smallpublic DateTimeFormatterBuilder optionalStart()
The output of printing can include optional sections, which may be nested.
An optional section is started by calling this method and ended by calling
optionalEnd()
or by ending the build process.
All elements in the optional section are treated as optional.
During printing, the section is only output if data is available in the
Calendrical
for all the elements in the section.
During parsing, the whole section may be missing from the parsed string.
For example, consider a builder setup as
builder.appendValue(hourRule,2).optionalStart().appendValue(minuteRule,2)
.
The optional section ends automatically at the end of the builder.
During printing, the minute will only be output if its value can be obtained from the calendrical.
During parsing, the input will be successfully parsed whether the minute is present or not.
public DateTimeFormatterBuilder optionalEnd()
The output of printing can include optional sections, which may be nested.
An optional section is started by calling optionalStart()
and ended
using this method (or at the end of the builder).
Calling this method without having previously called optionalStart
will throw an exception.
Calling this method immediately after calling optionalStart
has no effect
on the formatter other than ending the (empty) optional section.
All elements in the optional section are treated as optional.
During printing, the section is only output if data is available in the
Calendrical
for all the elements in the section.
During parsing, the whole section may be missing from the parsed string.
For example, consider a builder setup as
builder.appendValue(hourRule,2).optionalStart().appendValue(minuteRule,2).optionalEnd()
.
During printing, the minute will only be output if its value can be obtained from the calendrical.
During parsing, the input will be successfully parsed whether the minute is present or not.
IllegalStateException
- if there was no previous call to optionalStart
public DateTimeFormatter toFormatter()
Calling this method will end any open optional sections by repeatedly
calling optionalEnd()
before creating the formatter.
This builder can still be used after creating the formatter if desired,
although the state may have been changed by calls to optionalEnd
.
public DateTimeFormatter toFormatter(Locale locale)
Calling this method will end any open optional sections by repeatedly
calling optionalEnd()
before creating the formatter.
This builder can still be used after creating the formatter if desired,
although the state may have been changed by calls to optionalEnd
.
locale
- the locale to use for formatting, not nullCopyright © 2014. All rights reserved.