public final class DateTimeFormatterBuilder
extends java.lang.Object
This allows a DateTimeFormatter
to be created.
All date-time formatters are created ultimately using this builder.
The basic elements of date-time can all be added:
In addition, any of the elements may be decorated by padding, either with spaces or any other character.
Finally, a shorthand pattern, mostly compatible with java.text.SimpleDateFormat SimpleDateFormat
can be used, see appendPattern(String)
.
In practice, this simply parses the pattern and calls other methods on the builder.
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 |
appendChronoId()
Appends the chronology ID to the formatter.
|
DateTimeFormatterBuilder |
appendChronoText(TextStyle textStyle)
Appends the chronology name to the formatter.
|
DateTimeFormatterBuilder |
appendFraction(TemporalField field,
int minWidth,
int maxWidth,
boolean decimalPoint)
Appends the fractional value of a date-time field to the formatter.
|
DateTimeFormatterBuilder |
appendInstant()
Appends an instant using ISO-8601 to the formatter.
|
DateTimeFormatterBuilder |
appendLiteral(char literal)
Appends a character literal to the formatter.
|
DateTimeFormatterBuilder |
appendLiteral(java.lang.String literal)
Appends a string literal to the formatter.
|
DateTimeFormatterBuilder |
appendLocalized(FormatStyle dateStyle,
FormatStyle timeStyle)
Appends a localized date-time pattern to the formatter.
|
DateTimeFormatterBuilder |
appendLocalized(FormatStyle dateStyle,
FormatStyle timeStyle,
Chrono<?> chrono)
Appends a localized date-time pattern to the formatter.
|
DateTimeFormatterBuilder |
appendOffset(java.lang.String pattern,
java.lang.String noOffsetText)
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(java.lang.String pattern)
Appends the elements defined by the specified pattern to the builder.
|
DateTimeFormatterBuilder |
appendText(TemporalField field)
Appends the text of a date-time field to the formatter using the full
text style.
|
DateTimeFormatterBuilder |
appendText(TemporalField field,
java.util.Map<java.lang.Long,java.lang.String> textLookup)
Appends the text of a date-time field to the formatter using the specified
map to supply the text.
|
DateTimeFormatterBuilder |
appendText(TemporalField field,
TextStyle textStyle)
Appends the text of a date-time field to the formatter.
|
DateTimeFormatterBuilder |
appendValue(TemporalField field)
Appends the value of a date-time field to the formatter using a normal
output style.
|
DateTimeFormatterBuilder |
appendValue(TemporalField field,
int width)
Appends the value of a date-time field to the formatter using a fixed
width, zero-padded approach.
|
DateTimeFormatterBuilder |
appendValue(TemporalField field,
int minWidth,
int maxWidth,
SignStyle signStyle)
Appends the value of a date-time field to the formatter providing full
control over printing.
|
DateTimeFormatterBuilder |
appendValueReduced(TemporalField field,
int width,
int baseValue)
Appends the reduced value of a date-time field to the formatter.
|
DateTimeFormatterBuilder |
appendZoneId()
Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter.
|
DateTimeFormatterBuilder |
appendZoneOrOffsetId()
Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to
the formatter, using the best available zone ID.
|
DateTimeFormatterBuilder |
appendZoneRegionId()
Appends the time-zone region ID, such as 'Europe/Paris', to the formatter,
rejecting the zone ID if it is a
ZoneOffset . |
DateTimeFormatterBuilder |
appendZoneText(TextStyle textStyle)
Appends the time-zone 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(java.util.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 method allows the case sensitivity setting of parsing to be changed.
Calling this method changes the state of the builder such that all
subsequent builder method calls will parse text in case sensitive mode.
See parseCaseInsensitive()
for the opposite setting.
The parse case sensitive/insensitive methods may be called at any point
in the builder, thus the parser can swap between case parsing modes
multiple times during the parse.
Since the default is case sensitive, this method should only be used after
a previous call to #parseCaseInsensitive
.
public DateTimeFormatterBuilder parseCaseInsensitive()
Parsing can be case sensitive or insensitive - by default it is case sensitive. This method allows the case sensitivity setting of parsing to be changed.
Calling this method changes the state of the builder such that all
subsequent builder method calls will parse text in case insensitive mode.
See parseCaseSensitive()
for the opposite setting.
The parse case sensitive/insensitive methods may be called at any point
in the builder, thus the parser can swap between case parsing modes
multiple times during the parse.
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.
Applications calling this method should typically also call parseCaseInsensitive()
.
When used, this method changes the parsing to be lenient 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(TemporalField field)
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,
requiring one digit, but accepting as many digits as possible.
This behavior can be affected by 'adjacent value parsing'.
See appendValue(java.time.temporal.TemporalField, int)
for full details.
field
- the field to append, not nullpublic DateTimeFormatterBuilder appendValue(TemporalField field, 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(YEAR).appendValue(MONTH_OF_YEAR, 2);
The year is a variable width parse of between 1 and 19 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 '201106' will correctly parse to a year of 2011 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 adjacent parsing is active, then parsing must match exactly the specified number of digits in both strict and lenient modes. In addition, no positive or negative sign is permitted.
field
- the field to append, not nullwidth
- the width of the printed field, from 1 to 19java.lang.IllegalArgumentException
- if the width is invalidpublic DateTimeFormatterBuilder appendValue(TemporalField field, int minWidth, int maxWidth, 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 such as this normally behaves greedily,
accepting as many digits as possible.
This behavior can be affected by 'adjacent value parsing'.
See appendValue(java.time.temporal.TemporalField, int)
for full details.
In strict parsing mode, the minimum number of parsed digits is minWidth
.
In lenient parsing mode, the minimum number of parsed digits is one.
If this method is invoked with equal minimum and maximum widths and a sign style of
NOT_NEGATIVE
then it delegates to appendValue(TemporalField,int)
.
In this scenario, the printing and parsing behavior described there occur.
field
- the field to append, not nullminWidth
- the minimum field width of the printed field, from 1 to 19maxWidth
- the maximum field width of the printed field, from 1 to 19signStyle
- the positive/negative output style, not nulljava.lang.IllegalArgumentException
- if the widths are invalidpublic DateTimeFormatterBuilder appendValueReduced(TemporalField field, 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(java.time.temporal.TemporalField, int)
for full details.
field
- the field to append, not nullwidth
- the width of the printed and parsed field, from 1 to 18baseValue
- the base value of the range of valid valuesjava.lang.IllegalArgumentException
- if the width or base value is invalidpublic DateTimeFormatterBuilder appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint)
The fractional value of the field will be output including the
preceding decimal point. The preceding value is not output.
For example, the second-of-minute value of 15 would be output as .25
.
The width of the printed fraction can be controlled. Setting the minimum width to zero will cause no output to be generated. The printed 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.
When parsing in strict mode, the number of parsed digits must be between the minimum and maximum width. When parsing in lenient mode, the minimum width is considered to be zero and the maximum is nine.
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 date-time to be printed is invalid it cannot be printed and an exception will be thrown.
field
- 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 9decimalPoint
- whether to output the localized decimal point symboljava.lang.IllegalArgumentException
- if the field has a variable set of valid values or
either width is invalidpublic DateTimeFormatterBuilder appendText(TemporalField field)
The text of the field will be output during a print. The value must be within the valid range of the field. 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.
field
- the field to append, not nullpublic DateTimeFormatterBuilder appendText(TemporalField field, TextStyle textStyle)
The text of the field will be output during a print. The value must be within the valid range of the field. 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.
field
- the field to append, not nulltextStyle
- the text style to use, not nullpublic DateTimeFormatterBuilder appendText(TemporalField field, java.util.Map<java.lang.Long,java.lang.String> textLookup)
The standard text outputting methods use the localized text in the JDK. This method allows that text to be specified directly. The supplied map is not validated by the builder to ensure that printing or parsing is possible, thus an invalid map may throw an error during later use.
Supplying the map of text provides considerable flexibility in printing and parsing. For example, a legacy application might require or supply the months of the year as "JNY", "FBY", "MCH" etc. These do not match the standard set of text for localized month names. Using this method, a map can be created which defines the connection between each value and the text:
Map<Long, String> map = new HashMap<>(); map.put(1, "JNY"); map.put(2, "FBY"); map.put(3, "MCH"); ... builder.appendText(MONTH_OF_YEAR, map);
Other uses might be to output the value with a suffix, such as "1st", "2nd", "3rd", or as Roman numerals "I", "II", "III", "IV".
During printing, the value is obtained and checked that it is in the valid range. If text is not available for the value then it is output as a number. During parsing, the parser will match against the map of text and numeric values.
field
- the field to append, not nulltextLookup
- the map from the value to the textpublic DateTimeFormatterBuilder appendInstant()
Instants have a fixed output format. They are converted to a date-time with a zone-offset of UTC and printed using the standard ISO-8601 format.
An alternative to this method is to print/parse the instant as a single
epoch-seconds value. That is achieved using appendValue(INSTANT_SECONDS)
.
public DateTimeFormatterBuilder appendOffsetId()
This appends an instruction to print/parse the offset ID to the builder.
This is equivalent to calling appendOffset("HH:MM:ss", "Z")
.
public DateTimeFormatterBuilder appendOffset(java.lang.String pattern, java.lang.String noOffsetText)
This appends an instruction to print/parse the offset ID to the builder.
During printing, the offset is obtained using a mechanism equivalent
to querying the temporal with Queries.offset()
.
It will be printed using the format defined below.
If the offset cannot be obtained then an exception is thrown unless the
section of the formatter is optional.
During parsing, the offset is parsed using the format defined below. If the offset cannot be parsed then an exception is thrown unless the section of the formatter is optional.
The format of the offset is controlled by a pattern which must be one of the following:
+HH
- hour only, ignoring any minute
+HHMM
- hour and minute, no colon
+HH:MM
- hour and minute, with colon
+HHMMss
- hour and minute, with second if non-zero and no colon
+HH:MM:ss
- hour and minute, with second if non-zero and colon
+HHMMSS
- hour, minute and second, no colon
+HH:MM:SS
- hour, minute and second, with colon
The "no offset" text controls what text is printed when the offset is zero. Example values would be 'Z', '+00:00', 'UTC' or 'GMT'. Three formats are accepted for parsing UTC - the "no offset" text, and the plus and minus versions of zero defined by the pattern.
pattern
- the pattern to use, not nullnoOffsetText
- the text to use when the offset is zero, not nullpublic DateTimeFormatterBuilder appendZoneId()
This appends an instruction to print/parse the zone ID to the builder.
The zone ID is obtained in a strict manner suitable for ZonedDateTime
.
By contrast, OffsetDateTime
does not have a zone ID suitable
for use with this method, see appendZoneOrOffsetId()
.
During printing, the zone is obtained using a mechanism equivalent
to querying the temporal with Queries.zoneId()
.
It will be printed using the result of ZoneId.getId()
.
If the zone cannot be obtained then an exception is thrown unless the
section of the formatter is optional.
During parsing, the zone is parsed and must match a known zone or offset. If the zone cannot be parsed then an exception is thrown unless the section of the formatter is optional.
appendZoneRegionId()
public DateTimeFormatterBuilder appendZoneRegionId()
ZoneOffset
.
This appends an instruction to print/parse the zone ID to the builder only if it is a region-based ID.
During printing, the zone is obtained using a mechanism equivalent
to querying the temporal with Queries.zoneId()
.
If the zone is a ZoneOffset
or it cannot be obtained then
an exception is thrown unless the section of the formatter is optional.
If the zone is not an offset, then the zone will be printed using
the zone ID from ZoneId.getId()
.
During parsing, the zone is parsed and must match a known zone or offset.
If the zone cannot be parsed then an exception is thrown unless the
section of the formatter is optional.
Note that parsing accepts offsets, whereas printing will never produce
one, thus parsing is equivalent to appendZoneId
.
appendZoneId()
public DateTimeFormatterBuilder appendZoneOrOffsetId()
This appends an instruction to print/parse the best available
zone or offset ID to the builder.
The zone ID is obtained in a lenient manner that first attempts to
find a true zone ID, such as that on ZonedDateTime
, and
then attempts to find an offset, such as that on OffsetDateTime
.
During printing, the zone is obtained using a mechanism equivalent
to querying the temporal with Queries.zone()
.
It will be printed using the result of ZoneId.getId()
.
If the zone cannot be obtained then an exception is thrown unless the
section of the formatter is optional.
During parsing, the zone is parsed and must match a known zone or offset. If the zone cannot be parsed then an exception is thrown unless the section of the formatter is optional.
This method is is identical to appendZoneId()
except in the
mechanism used to obtain the zone.
appendZoneId()
public DateTimeFormatterBuilder appendZoneText(TextStyle textStyle)
This appends an instruction to print the textual name of the zone to the builder.
During printing, the zone is obtained using a mechanism equivalent
to querying the temporal with Queries.zoneId()
.
If the zone is a ZoneOffset
it will be printed using the
result of ZoneOffset.getId()
.
If the zone is not an offset, the textual name will be looked up
for the locale set in the DateTimeFormatter
.
If the temporal object being printed represents an instant, then the text
will be the summer or winter time text as appropriate.
If the lookup for text does not find any suitable reuslt, then the
ID
will be printed instead.
If the zone cannot be obtained then an exception is thrown unless the
section of the formatter is optional.
Parsing is not currently supported.
textStyle
- the text style to use, not nullpublic DateTimeFormatterBuilder appendChronoId()
The chronology ID will be output during a print. If the chronology cannot be obtained then an exception will be thrown.
public DateTimeFormatterBuilder appendChronoText(TextStyle textStyle)
The calendar system name will be output during a print. If the chronology cannot be obtained then an exception will be thrown. The calendar system name is obtained from the formatting symbols.
textStyle
- the text style to use, not nullpublic DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, 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 requiredpublic DateTimeFormatterBuilder appendLocalized(FormatStyle dateStyle, FormatStyle timeStyle, Chrono<?> chrono)
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 requiredchrono
- the chronology to use, not nullpublic DateTimeFormatterBuilder appendLiteral(char literal)
This character will be output during a print.
literal
- the literal to append, not nullpublic DateTimeFormatterBuilder appendLiteral(java.lang.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 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 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 nullpublic DateTimeFormatterBuilder appendPattern(java.lang.String pattern)
All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The characters '{' and '}' are reserved for future use. The characters '[' and ']' indicate optional patterns. The following pattern letters are defined:
Symbol Meaning Presentation Examples ------ ------- ------------ ------- G era number/text 1; 01; AD; Anno Domini y year year 2004; 04 D day-of-year number 189 M month-of-year number/text 7; 07; Jul; July; J d day-of-month number 10 Q quarter-of-year number/text 3; 03; Q3 Y week-based-year year 1996; 96 w week-of-year number 27 W week-of-month number 27 e localized day-of-week number 2; Tue; Tuesday; T E day-of-week number/text 2; Tue; Tuesday; T 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 0 k clock-hour-of-am-pm (1-24) number 0 H hour-of-day (0-23) number 0 m minute-of-hour number 30 s second-of-minute number 55 S fraction-of-second fraction 978 A milli-of-day number 1234 n nano-of-second number 987654321 N nano-of-day number 1234000000 I time-zone ID zoneId America/Los_Angeles z time-zone name text Pacific Standard Time; PST Z zone-offset offset-Z +0000; -0800; -08:00; X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15; p pad next pad modifier 1 ' escape for text delimiter '' single quote literal ' [ optional section start ] optional section end {} reserved for future use
The count of pattern letters determine the format.
Text: The text style is determined based on the number of pattern letters used.
Less than 4 pattern letters will use the short form
.
Exactly 4 pattern letters will use the full form
.
Exactly 5 pattern letters will use the narrow form
.
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(java.time.temporal.TemporalField)
. Otherwise, the
count of digits is used as the width of the output field as per appendValue(java.time.temporal.TemporalField, int)
.
Number/Text: If the count of pattern letters is 3 or greater, use the Text rules above. Otherwise use the Number rules above.
Fraction: Outputs the nano-of-second field as a fraction-of-second. The nano-of-second value has nine digits, thus the count of pattern letters is from 1 to 9. If it is less than 9, then the nano-of-second value is truncated, with only the most significant digits being output. When parsing in strict mode, the number of parsed digits must match the count of pattern letters. When parsing in lenient mode, the number of parsed digits must be at least the count of pattern letters, up to 9 digits.
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 SignStyle.NORMAL
.
Otherwise, the sign is output if the pad width is exceeded, as per SignStyle.EXCEEDS_PAD
ZoneId: 'I' outputs the zone ID, such as 'Europe/Paris'.
Offset X: This formats the offset using 'Z' when the offset is zero. One letter outputs just the hour', such as '+01' Two letters outputs the hour and minute, without a colon, such as '+0130'. Three letters outputs the hour and minute, with a colon, such as '+01:30'. Four letters outputs the hour and minute and optional second, without a colon, such as '+013015'. Five letters outputs the hour and minute and optional second, with a colon, such as '+01:30:15'.
Offset Z: This formats the offset using '+0000' or '+00:00' when the offset is zero. One or two letters outputs the hour and minute, without a colon, such as '+0130'. Three letters outputs the hour and minute, with a colon, such as '+01:30'.
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 is an error. 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
.
Pattern letters 'E' and 'u' are merged, which changes the meaning of "E" and "EE" to be numeric.
Pattern letters 'Z' and 'X' are extended.
Pattern letter 'y' and 'Y' parse years of two digits and more than 4 digits differently.
Pattern letters 'n', 'A', 'N', 'I' and 'p' are added.
Number types will reject large numbers.
The pattern string is also similar, but not identical, to that defined by the
Unicode Common Locale Data Repository (CLDR).
pattern
- the pattern to add, not nulljava.lang.IllegalArgumentException
- 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 greaterjava.lang.IllegalArgumentException
- 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 characterjava.lang.IllegalArgumentException
- 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
TemporalAccessor
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(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,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 date-time.
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
TemporalAccessor
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(HOUR_OF_DAY,2).optionalStart().appendValue(MINUTE_OF_HOUR,2).optionalEnd()
.
During printing, the minute will only be output if its value can be obtained from the date-time.
During parsing, the input will be successfully parsed whether the minute is present or not.
java.lang.IllegalStateException
- if there was no previous call to optionalStart
public DateTimeFormatter toFormatter()
This will create a formatter with the default FORMAT locale
.
Numbers will be printed and parsed using the standard non-localized set of symbols.
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(java.util.Locale locale)
This will create a formatter with the specified locale. Numbers will be printed and parsed using the standard non-localized set of symbols.
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 null