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:
- Value - a numeric value
- Fraction - a fractional value including the decimal place. Always use this when outputting fractions to ensure that the fraction is parsed correctly
- Text - the textual equivalent for the value
- OffsetId/Offset - the zone offset
- ZoneId - the time-zone id
- ZoneText - the name of the time-zone
- ChronologyId - the chronology id
- ChronologyText - the name of the chronology
- Literal - a text literal
- Nested and Optional - formats can be nested or made optional
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.
- Implementation Requirements:
- This class is a mutable builder intended for use from a single thread.
- Since:
- 1.8
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionappend
(DateTimeFormatter formatter) Appends all the elements of a formatter to the builder.Appends the chronology ID, such as 'ISO' or 'ThaiBuddhist', to the formatter.appendChronologyText
(TextStyle textStyle) Appends the chronology name to the formatter.appendDayPeriodText
(TextStyle style) Appends the day period text to the formatter.appendFraction
(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint) Appends the fractional value of a date-time field to the formatter.appendGenericZoneText
(TextStyle textStyle) Appends the generic time-zone name, such as 'Pacific Time', to the formatter.appendGenericZoneText
(TextStyle textStyle, Set<ZoneId> preferredZones) Appends the generic time-zone name, such as 'Pacific Time', to the formatter.Appends an instant using ISO-8601 to the formatter, formatting fractional digits in groups of three.appendInstant
(int fractionalDigits) Appends an instant using ISO-8601 to the formatter with control over the number of fractional digits.appendLiteral
(char literal) Appends a character literal to the formatter.appendLiteral
(String literal) Appends a string literal to the formatter.appendLocalized
(String requestedTemplate) Appends a localized pattern to the formatter using the requested template.appendLocalized
(FormatStyle dateStyle, FormatStyle timeStyle) Appends a localized date-time pattern to the formatter.appendLocalizedOffset
(TextStyle style) Appends the localized zone offset, such as 'GMT+01:00', to the formatter.appendOffset
(String pattern, String noOffsetText) Appends the zone offset, such as '+01:00', to the formatter.Appends the zone offset, such as '+01:00', to the formatter.appendOptional
(DateTimeFormatter formatter) Appends a formatter to the builder which will optionally format/parse.appendPattern
(String pattern) Appends the elements defined by the specified pattern to the builder.appendText
(TemporalField field) Appends the text of a date-time field to the formatter using the full text style.appendText
(TemporalField field, TextStyle textStyle) Appends the text of a date-time field to the formatter.appendText
(TemporalField field, Map<Long, String> textLookup) Appends the text of a date-time field to the formatter using the specified map to supply the text.appendValue
(TemporalField field) Appends the value of a date-time field to the formatter using a normal output style.appendValue
(TemporalField field, int width) Appends the value of a date-time field to the formatter using a fixed width, zero-padded approach.appendValue
(TemporalField field, int minWidth, int maxWidth, SignStyle signStyle) Appends the value of a date-time field to the formatter providing full control over formatting.appendValueReduced
(TemporalField field, int width, int maxWidth, int baseValue) Appends the reduced value of a date-time field to the formatter.appendValueReduced
(TemporalField field, int width, int maxWidth, ChronoLocalDate baseDate) Appends the reduced value of a date-time field to the formatter.Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter.Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter, using the best available zone ID.Appends the time-zone region ID, such as 'Europe/Paris', to the formatter, rejecting the zone ID if it is aZoneOffset
.appendZoneText
(TextStyle textStyle) Appends the time-zone name, such as 'British Summer Time', to the formatter.appendZoneText
(TextStyle textStyle, Set<ZoneId> preferredZones) Appends the time-zone name, such as 'British Summer Time', to the formatter.static String
getLocalizedDateTimePattern
(String requestedTemplate, Chronology chrono, Locale locale) Returns the formatting pattern for the requested template for a locale and chronology.static String
getLocalizedDateTimePattern
(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale) Gets the formatting pattern for date and time styles for a locale and chronology.Ends an optional section.Mark the start of an optional section.padNext
(int padWidth) Causes the next added printer/parser to pad to a fixed width using a space.padNext
(int padWidth, char padChar) Causes the next added printer/parser to pad to a fixed width.Changes the parse style to be case insensitive for the remainder of the formatter.Changes the parse style to be case sensitive for the remainder of the formatter.parseDefaulting
(TemporalField field, long value) Appends a default value for a field to the formatter for use in parsing.Changes the parse style to be lenient for the remainder of the formatter.Changes the parse style to be strict for the remainder of the formatter.Completes this builder by creating theDateTimeFormatter
using the default locale.toFormatter
(Locale locale) Completes this builder by creating theDateTimeFormatter
using the specified locale.
-
Constructor Details
-
DateTimeFormatterBuilder
public DateTimeFormatterBuilder()Constructs a new instance of the builder.
-
-
Method Details
-
getLocalizedDateTimePattern
public static String getLocalizedDateTimePattern(FormatStyle dateStyle, FormatStyle timeStyle, Chronology chrono, Locale locale) Gets the formatting pattern for date and time styles for a locale and chronology. The locale and chronology are used to lookup the locale specific format for the requested dateStyle and/or timeStyle.If the locale contains the "rg" (region override) Unicode extensions, the formatting pattern is overridden with the one appropriate for the region.
- Parameters:
dateStyle
- the FormatStyle for the date, null for time-only patterntimeStyle
- the FormatStyle for the time, null for date-only patternchrono
- the Chronology, non-nulllocale
- the locale, non-null- Returns:
- the locale and Chronology specific formatting pattern
- Throws:
IllegalArgumentException
- if both dateStyle and timeStyle are null
-
getLocalizedDateTimePattern
public static String getLocalizedDateTimePattern(String requestedTemplate, Chronology chrono, Locale locale) Returns the formatting pattern for the requested template for a locale and chronology. The locale and chronology are used to lookup the locale specific format for the requested template.If the locale contains the "rg" (region override) Unicode extensions, the formatting pattern is overridden with the one appropriate for the region.
Refer to
appendLocalized(String)
for the detail ofrequestedTemplate
argument.- Parameters:
requestedTemplate
- the requested template, not nullchrono
- the Chronology, non-nulllocale
- the locale, non-null- Returns:
- the locale and Chronology specific formatting pattern
- Throws:
IllegalArgumentException
- ifrequestedTemplate
does not match the regular expression syntax described inappendLocalized(String)
.DateTimeException
- if a match for the localized pattern forrequestedTemplate
is not available- Since:
- 19
- See Also:
-
parseCaseSensitive
Changes the parse style to be case sensitive for the remainder of the formatter.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
.- Returns:
- this, for chaining, not null
-
parseCaseInsensitive
Changes the parse style to be case insensitive for the remainder of the formatter.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.- Returns:
- this, for chaining, not null
-
parseStrict
Changes the parse style to be strict for the remainder of the formatter.Parsing can be strict or lenient - by default it is 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 untilparseLenient
is called.- Returns:
- this, for chaining, not null
-
parseLenient
Changes the parse style to be lenient for the remainder of the formatter. Note that case sensitivity is set separately to this method.Parsing can be strict or lenient - by default it is 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.- Returns:
- this, for chaining, not null
-
parseDefaulting
Appends a default value for a field to the formatter for use in parsing.This appends an instruction to the builder to inject a default value into the parsed result. This is especially useful in conjunction with optional parts of the formatter.
For example, consider a formatter that parses the year, followed by an optional month, with a further optional day-of-month. Using such a formatter would require the calling code to check whether a full date, year-month or just a year had been parsed. This method can be used to default the month and day-of-month to a sensible value, such as the first of the month, allowing the calling code to always get a date.
During formatting, this method has no effect.
During parsing, the current state of the parse is inspected. If the specified field has no associated value, because it has not been parsed successfully at that point, then the specified value is injected into the parse result. Injection is immediate, thus the field-value pair will be visible to any subsequent elements in the formatter. As such, this method is normally called at the end of the builder.
- Parameters:
field
- the field to default the value of, not nullvalue
- the value to default the field to- Returns:
- this, for chaining, not null
-
appendValue
Appends the value of a date-time field to the formatter using a normal output style.The value of the field will be output during a format. If the value cannot be obtained then an exception will be thrown.
The value will be printed as per the normal format 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.- Parameters:
field
- the field to append, not null- Returns:
- this, for chaining, not null
-
appendValue
Appends the value of a date-time field to the formatter using a fixed width, zero-padded approach.The value of the field will be output during a format. 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 formatting.
This method supports a special technique of parsing known as 'adjacent value parsing'. This technique solves the problem where a value, variable or fixed width, 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
is made, the builder enters adjacent value parsing setup mode. If the immediately subsequent method call or calls on the same builder are for a fixed width value, 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 value, variable or fixed width. 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 anotherDateTimeFormatterBuilder
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.
- Parameters:
field
- the field to append, not nullwidth
- the width of the printed field, from 1 to 19- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the width is invalid
-
appendValue
public 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 formatting.The value of the field will be output during a format. 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
and the maximum ismaxWidth
. In lenient parsing mode, the minimum number of parsed digits is one and the maximum is 19 (except as limited by adjacent value parsing).If this method is invoked with equal minimum and maximum widths and a sign style of
NOT_NEGATIVE
then it delegates toappendValue(TemporalField,int)
. In this scenario, the formatting and parsing behavior described there occur.- Parameters:
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 null- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the widths are invalid
-
appendValueReduced
public DateTimeFormatterBuilder appendValueReduced(TemporalField field, int width, int maxWidth, int baseValue) Appends the reduced value of a date-time field to the formatter.Since fields such as year vary by chronology, it is recommended to use the
appendValueReduced(TemporalField, int, int, ChronoLocalDate)
date} variant of this method in most cases. This variant is suitable for simple fields or working with only the ISO chronology.For formatting, the
width
andmaxWidth
are used to determine the number of characters to format. If they are equal then the format is fixed width. If the value of the field is within the range of thebaseValue
usingwidth
characters then the reduced value is formatted otherwise the value is truncated to fitmaxWidth
. The rightmost characters are output to match the width, left padding with zero.For strict parsing, the number of characters allowed by
width
tomaxWidth
are parsed. For lenient parsing, the number of characters must be at least 1 and less than 10. If the number of digits parsed is equal towidth
and the value is positive, the value of the field is computed to be the first number greater than or equal to thebaseValue
with the same least significant characters, otherwise the value parsed is the field value. This allows a reduced value to be entered for values in range of the baseValue and width and absolute values can be entered for values outside the range.For example, a base value of
1980
and a width of2
will have valid values from1980
to2079
. During parsing, the text"12"
will result in the value2012
as that is the value within the range where the last two characters are "12". By contrast, parsing the text"1915"
will result in the value1915
.- Parameters:
field
- the field to append, not nullwidth
- the field width of the printed and parsed field, from 1 to 10maxWidth
- the maximum field width of the printed field, from 1 to 10baseValue
- the base value of the range of valid values- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the width or base value is invalid
-
appendValueReduced
public DateTimeFormatterBuilder appendValueReduced(TemporalField field, int width, int maxWidth, ChronoLocalDate baseDate) Appends the reduced value of a date-time field to the formatter.This is typically used for formatting and parsing a two digit year.
The base date is used to calculate the full value during parsing. For example, if the base date is 1950-01-01 then parsed values for a two digit year parse will be in the range 1950-01-01 to 2049-12-31. Only the year would be extracted from the date, thus a base date of 1950-08-25 would also parse to the range 1950-01-01 to 2049-12-31. This behavior is necessary to support fields such as week-based-year or other calendar systems where the parsed value does not align with standard ISO years.
The exact behavior is as follows. Parse the full set of fields and determine the effective chronology using the last chronology if it appears more than once. Then convert the base date to the effective chronology. Then extract the specified field from the chronology-specific base date and use it to determine the
baseValue
used below.For formatting, the
width
andmaxWidth
are used to determine the number of characters to format. If they are equal then the format is fixed width. If the value of the field is within the range of thebaseValue
usingwidth
characters then the reduced value is formatted otherwise the value is truncated to fitmaxWidth
. The rightmost characters are output to match the width, left padding with zero.For strict parsing, the number of characters allowed by
width
tomaxWidth
are parsed. For lenient parsing, the number of characters must be at least 1 and less than 10. If the number of digits parsed is equal towidth
and the value is positive, the value of the field is computed to be the first number greater than or equal to thebaseValue
with the same least significant characters, otherwise the value parsed is the field value. This allows a reduced value to be entered for values in range of the baseValue and width and absolute values can be entered for values outside the range.For example, a base value of
1980
and a width of2
will have valid values from1980
to2079
. During parsing, the text"12"
will result in the value2012
as that is the value within the range where the last two characters are "12". By contrast, parsing the text"1915"
will result in the value1915
.- Parameters:
field
- the field to append, not nullwidth
- the field width of the printed and parsed field, from 1 to 10maxWidth
- the maximum field width of the printed field, from 1 to 10baseDate
- the base date used to calculate the base value for the range of valid values in the parsed chronology, not null- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the width or base value is invalid
-
appendFraction
public DateTimeFormatterBuilder appendFraction(TemporalField field, int minWidth, int maxWidth, boolean decimalPoint) Appends the fractional value of a date-time field to the formatter.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. In strict mode, if the minimum and maximum widths are equal and there is no decimal point then the parser will participate in adjacent value parsing, see
appendValue(java.time.temporal.TemporalField, int)
. 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 outside the range of valid values then an exception will be thrown.
- Parameters:
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 symbol- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the field has a variable set of valid values or either width is invalid
-
appendText
Appends the text of a date-time field to the formatter using the full text style.The text of the field will be output during a format. 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 format of an integer value. Only negative numbers will be signed. No padding will be added.
- Parameters:
field
- the field to append, not null- Returns:
- this, for chaining, not null
-
appendText
Appends the text of a date-time field to the formatter.The text of the field will be output during a format. 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 format of an integer value. Only negative numbers will be signed. No padding will be added.
- Parameters:
field
- the field to append, not nulltextStyle
- the text style to use, not null- Returns:
- this, for chaining, not null
-
appendText
Appends the text of a date-time field to the formatter using the specified map to supply the text.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 formatting or parsing is possible, thus an invalid map may throw an error during later use.
Supplying the map of text provides considerable flexibility in formatting 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(1L, "JNY"); map.put(2L, "FBY"); map.put(3L, "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 formatting, 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.
- Parameters:
field
- the field to append, not nulltextLookup
- the map from the value to the text- Returns:
- this, for chaining, not null
-
appendInstant
Appends an instant using ISO-8601 to the formatter, formatting fractional digits in groups of three.Instants have a fixed output format. They are converted to a date-time with a zone-offset of UTC and formatted using the standard ISO-8601 format. With this method, formatting nano-of-second outputs zero, three, six or nine digits as necessary. The localized decimal style is not used.
The instant is obtained using
INSTANT_SECONDS
and optionallyNANO_OF_SECOND
. The value ofINSTANT_SECONDS
may be outside the maximum range ofLocalDateTime
.The resolver style has no effect on instant parsing. The end-of-day time of '24:00' is handled as midnight at the start of the following day. The leap-second time of '23:59:59' is handled to some degree, see
DateTimeFormatter.parsedLeapSecond()
for full details.When formatting, the instant will always be suffixed by 'Z' to indicate UTC. When parsing, the behaviour of
appendOffsetId()
will be used to parse the offset, converting the instant to UTC as necessary.An alternative to this method is to format/parse the instant as a single epoch-seconds value. That is achieved using
appendValue(INSTANT_SECONDS)
.- Returns:
- this, for chaining, not null
-
appendInstant
Appends an instant using ISO-8601 to the formatter with control over the number of fractional digits.Instants have a fixed output format, although this method provides some control over the fractional digits. They are converted to a date-time with a zone-offset of UTC and printed using the standard ISO-8601 format. The localized decimal style is not used.
The
fractionalDigits
parameter allows the output of the fractional second to be controlled. Specifying zero will cause no fractional digits to be output. From 1 to 9 will output an increasing number of digits, using zero right-padding if necessary. The special value -1 is used to output as many digits as necessary to avoid any trailing zeroes.When parsing in strict mode, the number of parsed digits must match the fractional digits. When parsing in lenient mode, any number of fractional digits from zero to nine are accepted.
The instant is obtained using
INSTANT_SECONDS
and optionallyNANO_OF_SECOND
. The value ofINSTANT_SECONDS
may be outside the maximum range ofLocalDateTime
.The resolver style has no effect on instant parsing. The end-of-day time of '24:00' is handled as midnight at the start of the following day. The leap-second time of '23:59:60' is handled to some degree, see
DateTimeFormatter.parsedLeapSecond()
for full details.An alternative to this method is to format/parse the instant as a single epoch-seconds value. That is achieved using
appendValue(INSTANT_SECONDS)
.- Parameters:
fractionalDigits
- the number of fractional second digits to format with, from 0 to 9, or -1 to use as many digits as necessary- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the number of fractional digits is invalid
-
appendOffsetId
Appends the zone offset, such as '+01:00', to the formatter.This appends an instruction to format/parse the offset ID to the builder. This is equivalent to calling
appendOffset("+HH:mm:ss", "Z")
. SeeappendOffset(String, String)
for details on formatting and parsing.- Returns:
- this, for chaining, not null
-
appendOffset
Appends the zone offset, such as '+01:00', to the formatter.This appends an instruction to format/parse the offset ID to the builder.
During formatting, the offset is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.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.When parsing in strict mode, the input must contain the mandatory and optional elements are defined by the specified pattern. If the offset cannot be parsed then an exception is thrown unless the section of the formatter is optional.
When parsing in lenient mode, only the hours are mandatory - minutes and seconds are optional. The colons are required if the specified pattern contains a colon. If the specified pattern is "+HH", the presence of colons is determined by whether the character after the hour digits is a colon or not. 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 minute and second+HHmm
- hour, with minute if non-zero, ignoring second, no colon+HH:mm
- hour, with minute if non-zero, ignoring second, with colon+HHMM
- hour and minute, ignoring second, no colon+HH:MM
- hour and minute, ignoring second, with colon+HHMMss
- hour and minute, with second if non-zero, no colon+HH:MM:ss
- hour and minute, with second if non-zero, with colon+HHMMSS
- hour, minute and second, no colon+HH:MM:SS
- hour, minute and second, with colon+HHmmss
- hour, with minute if non-zero or with minute and second if non-zero, no colon+HH:mm:ss
- hour, with minute if non-zero or with minute and second if non-zero, with colon+H
- hour only, ignoring minute and second+Hmm
- hour, with minute if non-zero, ignoring second, no colon+H:mm
- hour, with minute if non-zero, ignoring second, with colon+HMM
- hour and minute, ignoring second, no colon+H:MM
- hour and minute, ignoring second, with colon+HMMss
- hour and minute, with second if non-zero, no colon+H:MM:ss
- hour and minute, with second if non-zero, with colon+HMMSS
- hour, minute and second, no colon+H:MM:SS
- hour, minute and second, with colon+Hmmss
- hour, with minute if non-zero or with minute and second if non-zero, no colon+H:mm:ss
- hour, with minute if non-zero or with minute and second if non-zero, with colon
- Parameters:
pattern
- the pattern to use, not nullnoOffsetText
- the text to use when the offset is zero, not null- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the pattern is invalid
-
appendLocalizedOffset
Appends the localized zone offset, such as 'GMT+01:00', to the formatter.This appends a localized zone offset to the builder, the format of the localized offset is controlled by the specified
style
to this method:full
- formats with localized offset text, such as 'GMT, 2-digit hour and minute field, optional second field if non-zero, and colon.short
- formats with localized offset text, such as 'GMT, hour without leading zero, optional 2-digit minute and second if non-zero, and colon.
During formatting, the offset is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.offset()
. 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 above. If the offset cannot be parsed then an exception is thrown unless the section of the formatter is optional.
- Parameters:
style
- the format style to use, not null- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if style is neitherfull
norshort
-
appendZoneId
Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter.This appends an instruction to format/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, seeappendZoneOrOffsetId()
.During formatting, the zone is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.zoneId()
. It will be printed using the result ofZoneId.getId()
. If the zone cannot be obtained then an exception is thrown unless the section of the formatter is optional.During parsing, the text must match a known zone or offset. There are two types of zone ID, offset-based, such as '+01:30' and region-based, such as 'Europe/London'. These are parsed differently. If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser expects an offset-based zone and will not match region-based zones. The offset ID, such as '+02:30', may be at the start of the parse, or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is equivalent to using
appendOffset(String, String)
using the arguments 'HH:MM:ss' and the no offset string '0'. If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot match a following offset ID, thenZoneOffset.UTC
is selected. In all other cases, the list of known region-based zones is used to find the longest available match. If no match is found, and the parse starts with 'Z', thenZoneOffset.UTC
is selected. The parser uses the case sensitive setting.For example, the following will parse:
"Europe/London" -- ZoneId.of("Europe/London") "Z" -- ZoneOffset.UTC "UT" -- ZoneId.of("UT") "UTC" -- ZoneId.of("UTC") "GMT" -- ZoneId.of("GMT") "+01:30" -- ZoneOffset.of("+01:30") "UT+01:30" -- ZoneOffset.of("+01:30") "UTC+01:30" -- ZoneOffset.of("+01:30") "GMT+01:30" -- ZoneOffset.of("+01:30")
- Returns:
- this, for chaining, not null
- See Also:
-
appendZoneRegionId
Appends the time-zone region ID, such as 'Europe/Paris', to the formatter, rejecting the zone ID if it is aZoneOffset
.This appends an instruction to format/parse the zone ID to the builder only if it is a region-based ID.
During formatting, the zone is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.zoneId()
. If the zone is aZoneOffset
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 fromZoneId.getId()
.During parsing, the text must match a known zone or offset. There are two types of zone ID, offset-based, such as '+01:30' and region-based, such as 'Europe/London'. These are parsed differently. If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser expects an offset-based zone and will not match region-based zones. The offset ID, such as '+02:30', may be at the start of the parse, or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is equivalent to using
appendOffset(String, String)
using the arguments 'HH:MM:ss' and the no offset string '0'. If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot match a following offset ID, thenZoneOffset.UTC
is selected. In all other cases, the list of known region-based zones is used to find the longest available match. If no match is found, and the parse starts with 'Z', thenZoneOffset.UTC
is selected. The parser uses the case sensitive setting.For example, the following will parse:
"Europe/London" -- ZoneId.of("Europe/London") "Z" -- ZoneOffset.UTC "UT" -- ZoneId.of("UT") "UTC" -- ZoneId.of("UTC") "GMT" -- ZoneId.of("GMT") "+01:30" -- ZoneOffset.of("+01:30") "UT+01:30" -- ZoneOffset.of("+01:30") "UTC+01:30" -- ZoneOffset.of("+01:30") "GMT+01:30" -- ZoneOffset.of("+01:30")
Note that this method is identical to
appendZoneId()
except in the mechanism used to obtain the zone. Note also that parsing accepts offsets, whereas formatting will never produce one.- Returns:
- this, for chaining, not null
- See Also:
-
appendZoneOrOffsetId
Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter, using the best available zone ID.This appends an instruction to format/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 onOffsetDateTime
.During formatting, the zone is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.zone()
. It will be printed using the result ofZoneId.getId()
. If the zone cannot be obtained then an exception is thrown unless the section of the formatter is optional.During parsing, the text must match a known zone or offset. There are two types of zone ID, offset-based, such as '+01:30' and region-based, such as 'Europe/London'. These are parsed differently. If the parse starts with '+', '-', 'UT', 'UTC' or 'GMT', then the parser expects an offset-based zone and will not match region-based zones. The offset ID, such as '+02:30', may be at the start of the parse, or prefixed by 'UT', 'UTC' or 'GMT'. The offset ID parsing is equivalent to using
appendOffset(String, String)
using the arguments 'HH:MM:ss' and the no offset string '0'. If the parse starts with 'UT', 'UTC' or 'GMT', and the parser cannot match a following offset ID, thenZoneOffset.UTC
is selected. In all other cases, the list of known region-based zones is used to find the longest available match. If no match is found, and the parse starts with 'Z', thenZoneOffset.UTC
is selected. The parser uses the case sensitive setting.For example, the following will parse:
"Europe/London" -- ZoneId.of("Europe/London") "Z" -- ZoneOffset.UTC "UT" -- ZoneId.of("UT") "UTC" -- ZoneId.of("UTC") "GMT" -- ZoneId.of("GMT") "+01:30" -- ZoneOffset.of("+01:30") "UT+01:30" -- ZoneOffset.of("UT+01:30") "UTC+01:30" -- ZoneOffset.of("UTC+01:30") "GMT+01:30" -- ZoneOffset.of("GMT+01:30")
Note that this method is identical to
appendZoneId()
except in the mechanism used to obtain the zone.- Returns:
- this, for chaining, not null
- See Also:
-
appendZoneText
Appends the time-zone name, such as 'British Summer Time', to the formatter.This appends an instruction to format/parse the textual name of the zone to the builder.
During formatting, the zone is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.zoneId()
. If the zone is aZoneOffset
it will be printed using the result ofZoneOffset.getId()
. If the zone is not an offset, the textual name will be looked up for the locale set in theDateTimeFormatter
. If the temporal object being printed represents an instant, or if it is a local date-time that is not in a daylight saving gap or overlap then the text will be the summer or winter time text as appropriate. If the lookup for text does not find any suitable result, then theID
will be printed. If the zone cannot be obtained then an exception is thrown unless the section of the formatter is optional.During parsing, either the textual zone name, the zone ID or the offset is accepted. Many textual zone names are not unique, such as CST can be for both "Central Standard Time" and "China Standard Time". In this situation, the zone id will be determined by the region information from formatter's
locale
and the standard zone id for that area, for example, America/New_York for the America Eastern zone. TheappendZoneText(TextStyle, Set)
may be used to specify a set of preferredZoneId
in this situation.- Parameters:
textStyle
- the text style to use, not null- Returns:
- this, for chaining, not null
-
appendZoneText
Appends the time-zone name, such as 'British Summer Time', to the formatter.This appends an instruction to format/parse the textual name of the zone to the builder.
During formatting, the zone is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.zoneId()
. If the zone is aZoneOffset
it will be printed using the result ofZoneOffset.getId()
. If the zone is not an offset, the textual name will be looked up for the locale set in theDateTimeFormatter
. If the temporal object being printed represents an instant, or if it is a local date-time that is not in a daylight saving gap or overlap, then the text will be the summer or winter time text as appropriate. If the lookup for text does not find any suitable result, then theID
will be printed. If the zone cannot be obtained then an exception is thrown unless the section of the formatter is optional.During parsing, either the textual zone name, the zone ID or the offset is accepted. Many textual zone names are not unique, such as CST can be for both "Central Standard Time" and "China Standard Time". In this situation, the zone id will be determined by the region information from formatter's
locale
and the standard zone id for that area, for example, America/New_York for the America Eastern zone. This method also allows a set of preferredZoneId
to be specified for parsing. The matched preferred zone id will be used if the textural zone name being parsed is not unique.If the zone cannot be parsed then an exception is thrown unless the section of the formatter is optional.
- Parameters:
textStyle
- the text style to use, not nullpreferredZones
- the set of preferred zone ids, not null- Returns:
- this, for chaining, not null
-
appendGenericZoneText
Appends the generic time-zone name, such as 'Pacific Time', to the formatter.This appends an instruction to format/parse the generic textual name of the zone to the builder. The generic name is the same throughout the whole year, ignoring any daylight saving changes. For example, 'Pacific Time' is the generic name, whereas 'Pacific Standard Time' and 'Pacific Daylight Time' are the specific names, see
appendZoneText(TextStyle)
.During formatting, the zone is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.zoneId()
. If the zone is aZoneOffset
it will be printed using the result ofZoneOffset.getId()
. If the zone is not an offset, the textual name will be looked up for the locale set in theDateTimeFormatter
. If the lookup for text does not find any suitable result, then theID
will be printed. If the zone cannot be obtained then an exception is thrown unless the section of the formatter is optional.During parsing, either the textual zone name, the zone ID or the offset is accepted. Many textual zone names are not unique, such as CST can be for both "Central Standard Time" and "China Standard Time". In this situation, the zone id will be determined by the region information from formatter's
locale
and the standard zone id for that area, for example, America/New_York for the America Eastern zone. TheappendGenericZoneText(TextStyle, Set)
may be used to specify a set of preferredZoneId
in this situation.- Parameters:
textStyle
- the text style to use, not null- Returns:
- this, for chaining, not null
- Since:
- 9
-
appendGenericZoneText
public DateTimeFormatterBuilder appendGenericZoneText(TextStyle textStyle, Set<ZoneId> preferredZones) Appends the generic time-zone name, such as 'Pacific Time', to the formatter.This appends an instruction to format/parse the generic textual name of the zone to the builder. The generic name is the same throughout the whole year, ignoring any daylight saving changes. For example, 'Pacific Time' is the generic name, whereas 'Pacific Standard Time' and 'Pacific Daylight Time' are the specific names, see
appendZoneText(TextStyle)
.This method also allows a set of preferred
ZoneId
to be specified for parsing. The matched preferred zone id will be used if the textural zone name being parsed is not unique.See
appendGenericZoneText(TextStyle)
for details about formatting and parsing.- Parameters:
textStyle
- the text style to use, not nullpreferredZones
- the set of preferred zone ids, not null- Returns:
- this, for chaining, not null
- Since:
- 9
-
appendChronologyId
Appends the chronology ID, such as 'ISO' or 'ThaiBuddhist', to the formatter.This appends an instruction to format/parse the chronology ID to the builder.
During formatting, the chronology is obtained using a mechanism equivalent to querying the temporal with
TemporalQueries.chronology()
. It will be printed using the result ofChronology.getId()
. If the chronology cannot be obtained then an exception is thrown unless the section of the formatter is optional.During parsing, the chronology is parsed and must match one of the chronologies in
Chronology.getAvailableChronologies()
. If the chronology cannot be parsed then an exception is thrown unless the section of the formatter is optional. The parser uses the case sensitive setting.- Returns:
- this, for chaining, not null
-
appendChronologyText
Appends the chronology name to the formatter.The calendar system name will be output during a format. If the chronology cannot be obtained then an exception will be thrown.
- Parameters:
textStyle
- the text style to use, not null- Returns:
- this, for chaining, not null
-
appendLocalized
Appends a localized date-time pattern to the formatter.This appends a localized section to the builder, suitable for outputting a date, time or date-time combination. The format of the localized section is lazily looked up based on four items:
- the
dateStyle
specified to this method - the
timeStyle
specified to this method - the
Locale
of theDateTimeFormatter
- the
Chronology
, selecting the best available
DateTimeFormatter.withChronology(Chronology)
. TheFULL
andLONG
styles typically require a time-zone. When formatting using these styles, aZoneId
must be available, either by usingZonedDateTime
orDateTimeFormatter.withZone(java.time.ZoneId)
.During parsing, if a chronology has already been parsed, then it is used. Otherwise the default from
DateTimeFormatter.withChronology(Chronology)
is used, withIsoChronology
as the fallback.Note that this method provides similar functionality to methods on
DateFormat
such asDateFormat.getDateTimeInstance(int, int)
.- Parameters:
dateStyle
- the date style to use, null means no date requiredtimeStyle
- the time style to use, null means no time required- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if both the date and time styles are null
- the
-
appendLocalized
Appends a localized pattern to the formatter using the requested template.This appends a localized section to the builder, suitable for outputting a date, time or date-time combination. The format of the localized section is lazily looked up based on three items:
- the
requestedTemplate
specified to this method - the
Locale
of theDateTimeFormatter
- the
Chronology
of theDateTimeFormatter
unless overridden
DateTimeFormatter.withChronology(Chronology)
.During parsing, if a chronology has already been parsed, then it is used. Otherwise the default from
DateTimeFormatter.withChronology(Chronology)
is used, withIsoChronology
as the fallback.The requested template is a series of typical pattern symbols in canonical order from the largest date or time unit to the smallest, which can be expressed with the following regular expression:
"G{0,5}" + // Era "y*" + // Year "Q{0,5}" + // Quarter "M{0,5}" + // Month "w*" + // Week of Week Based Year "E{0,5}" + // Day of Week "d{0,2}" + // Day of Month "B{0,5}" + // Period/AmPm of Day "[hHjC]{0,2}" + // Hour of Day/AmPm (refer to LDML for 'j' and 'C') "m{0,2}" + // Minute of Hour "s{0,2}" + // Second of Minute "[vz]{0,4}" // Zone
The mapping of the requested template to the closest of the available localized formats is defined by the Unicode LDML specification. For example, the formatter created from the requested template
yMMM
will format the date '2020-06-16' to 'Jun 2020' in theUS locale
.- Parameters:
requestedTemplate
- the requested template to use, not null- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- ifrequestedTemplate
is invalid- Since:
- 19
- External Specifications
- See Also:
- the
-
appendLiteral
Appends a character literal to the formatter.This character will be output during a format.
- Parameters:
literal
- the literal to append, not null- Returns:
- this, for chaining, not null
-
appendLiteral
Appends a string literal to the formatter.This string will be output during a format.
If the literal is empty, nothing is added to the formatter.
- Parameters:
literal
- the literal to append, not null- Returns:
- this, for chaining, not null
-
appendDayPeriodText
Appends the day period text to the formatter.This appends an instruction to format/parse the textual name of the day period to the builder. Day periods are defined in LDML's "day periods" element.
During formatting, the day period is obtained from
HOUR_OF_DAY
, and optionallyMINUTE_OF_HOUR
if exist. It will be mapped to a day period type defined in LDML, such as "morning1" and then it will be translated into text. Mapping to a day period type and its translation both depend on the locale in the formatter.During parsing, the text will be parsed into a day period type first. Then the parsed day period is combined with other fields to make a
LocalTime
in the resolving phase. If theHOUR_OF_AMPM
field is present, it is combined with the day period to makeHOUR_OF_DAY
taking into account anyMINUTE_OF_HOUR
value. IfHOUR_OF_DAY
is present, it is validated against the day period taking into account anyMINUTE_OF_HOUR
value. If a day period is present withoutHOUR_OF_DAY
,MINUTE_OF_HOUR
,SECOND_OF_MINUTE
andNANO_OF_SECOND
then the midpoint of the day period is set as the time inSMART
andLENIENT
mode. For example, if the parsed day period type is "night1" and the period defined for it in the formatter locale is from 21:00 to 06:00, then it results in theLocalTime
of 01:30. If the resolved time conflicts with the day period,DateTimeException
is thrown inSTRICT
andSMART
mode. InLENIENT
mode, no exception is thrown and the parsed day period is ignored.The "midnight" type allows both "00:00" as the start-of-day and "24:00" as the end-of-day, as long as they are valid with the resolved hour field.
- Parameters:
style
- the text style to use, not null- Returns:
- this, for chaining, not null
- Since:
- 16
- External Specifications
-
append
Appends all the elements of a formatter to the builder.This method has the same effect as appending each of the constituent parts of the formatter directly to this builder.
- Parameters:
formatter
- the formatter to add, not null- Returns:
- this, for chaining, not null
-
appendOptional
Appends a formatter to the builder which will optionally format/parse.This method has the same effect as appending each of the constituent parts directly to this builder surrounded by an
optionalStart()
andoptionalEnd()
.The formatter will format if data is available for all the fields contained within it. The formatter will parse if the string matches, otherwise no error is returned.
- Parameters:
formatter
- the formatter to add, not null- Returns:
- this, for chaining, not null
-
appendPattern
Appends the elements defined by the specified pattern to the builder.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 text AD; Anno Domini; A u year year 2004; 04 y year-of-era year 2004; 04 D day-of-year number 189 M/L month-of-year number/text 7; 07; Jul; July; J d day-of-month number 10 g modified-julian-day number 2451334 Q/q quarter-of-year number/text 3; 03; Q3; 3rd quarter Y week-based-year year 1996; 96 w week-of-week-based-year number 27 W week-of-month number 4 E day-of-week text Tue; Tuesday; T e/c localized day-of-week number/text 2; 02; Tue; Tuesday; T F day-of-week-in-month number 3 a am-pm-of-day text PM B period-of-day text in the morning h clock-hour-of-am-pm (1-12) number 12 K hour-of-am-pm (0-11) number 0 k clock-hour-of-day (1-24) number 24 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 V time-zone ID zone-id America/Los_Angeles; Z; -08:30 v generic time-zone name zone-name PT, Pacific Time z time-zone name zone-name Pacific Standard Time; PST O localized zone-offset offset-O GMT+8; GMT+08:00; UTC-08:00; X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15 x zone-offset offset-x +0000; -08; -0830; -08:30; -083015; -08:30:15 Z zone-offset offset-Z +0000; -0800; -08:00 p pad next pad modifier 1 ' escape for text delimiter '' single quote literal ' [ optional section start ] optional section end # reserved for future use { reserved for future use } reserved for future use
The count of pattern letters determine the format. See DateTimeFormatter for a user-focused description of the patterns. The following tables define how the pattern letters map to the builder.
Date fields: Pattern letters to output a date.
Pattern Count Equivalent builder methods ------- ----- -------------------------- G 1 appendText(ChronoField.ERA, TextStyle.SHORT) GG 2 appendText(ChronoField.ERA, TextStyle.SHORT) GGG 3 appendText(ChronoField.ERA, TextStyle.SHORT) GGGG 4 appendText(ChronoField.ERA, TextStyle.FULL) GGGGG 5 appendText(ChronoField.ERA, TextStyle.NARROW) u 1 appendValue(ChronoField.YEAR, 1, 19, SignStyle.NORMAL) uu 2 appendValueReduced(ChronoField.YEAR, 2, 2, 2000) uuu 3 appendValue(ChronoField.YEAR, 3, 19, SignStyle.NORMAL) u..u 4..n appendValue(ChronoField.YEAR, n, 19, SignStyle.EXCEEDS_PAD) y 1 appendValue(ChronoField.YEAR_OF_ERA, 1, 19, SignStyle.NORMAL) yy 2 appendValueReduced(ChronoField.YEAR_OF_ERA, 2, 2, 2000) yyy 3 appendValue(ChronoField.YEAR_OF_ERA, 3, 19, SignStyle.NORMAL) y..y 4..n appendValue(ChronoField.YEAR_OF_ERA, n, 19, SignStyle.EXCEEDS_PAD) Y 1 append special localized WeekFields element for numeric week-based-year YY 2 append special localized WeekFields element for reduced numeric week-based-year 2 digits YYY 3 append special localized WeekFields element for numeric week-based-year (3, 19, SignStyle.NORMAL) Y..Y 4..n append special localized WeekFields element for numeric week-based-year (n, 19, SignStyle.EXCEEDS_PAD) Q 1 appendValue(IsoFields.QUARTER_OF_YEAR) QQ 2 appendValue(IsoFields.QUARTER_OF_YEAR, 2) QQQ 3 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT) QQQQ 4 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL) QQQQQ 5 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW) q 1 appendValue(IsoFields.QUARTER_OF_YEAR) qq 2 appendValue(IsoFields.QUARTER_OF_YEAR, 2) qqq 3 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.SHORT_STANDALONE) qqqq 4 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.FULL_STANDALONE) qqqqq 5 appendText(IsoFields.QUARTER_OF_YEAR, TextStyle.NARROW_STANDALONE) M 1 appendValue(ChronoField.MONTH_OF_YEAR) MM 2 appendValue(ChronoField.MONTH_OF_YEAR, 2) MMM 3 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT) MMMM 4 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL) MMMMM 5 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW) L 1 appendValue(ChronoField.MONTH_OF_YEAR) LL 2 appendValue(ChronoField.MONTH_OF_YEAR, 2) LLL 3 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.SHORT_STANDALONE) LLLL 4 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.FULL_STANDALONE) LLLLL 5 appendText(ChronoField.MONTH_OF_YEAR, TextStyle.NARROW_STANDALONE) w 1 append special localized WeekFields element for numeric week-of-year ww 2 append special localized WeekFields element for numeric week-of-year, zero-padded W 1 append special localized WeekFields element for numeric week-of-month d 1 appendValue(ChronoField.DAY_OF_MONTH) dd 2 appendValue(ChronoField.DAY_OF_MONTH, 2) D 1 appendValue(ChronoField.DAY_OF_YEAR) DD 2 appendValue(ChronoField.DAY_OF_YEAR, 2, 3, SignStyle.NOT_NEGATIVE) DDD 3 appendValue(ChronoField.DAY_OF_YEAR, 3) F 1 appendValue(ChronoField.ALIGNED_WEEK_OF_MONTH) g..g 1..n appendValue(JulianFields.MODIFIED_JULIAN_DAY, n, 19, SignStyle.NORMAL) E 1 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT) EE 2 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT) EEE 3 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT) EEEE 4 appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL) EEEEE 5 appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW) e 1 append special localized WeekFields element for numeric day-of-week ee 2 append special localized WeekFields element for numeric day-of-week, zero-padded eee 3 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT) eeee 4 appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL) eeeee 5 appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW) c 1 append special localized WeekFields element for numeric day-of-week ccc 3 appendText(ChronoField.DAY_OF_WEEK, TextStyle.SHORT_STANDALONE) cccc 4 appendText(ChronoField.DAY_OF_WEEK, TextStyle.FULL_STANDALONE) ccccc 5 appendText(ChronoField.DAY_OF_WEEK, TextStyle.NARROW_STANDALONE)
Time fields: Pattern letters to output a time.
Pattern Count Equivalent builder methods ------- ----- -------------------------- a 1 appendText(ChronoField.AMPM_OF_DAY, TextStyle.SHORT) h 1 appendValue(ChronoField.CLOCK_HOUR_OF_AMPM) hh 2 appendValue(ChronoField.CLOCK_HOUR_OF_AMPM, 2) H 1 appendValue(ChronoField.HOUR_OF_DAY) HH 2 appendValue(ChronoField.HOUR_OF_DAY, 2) k 1 appendValue(ChronoField.CLOCK_HOUR_OF_DAY) kk 2 appendValue(ChronoField.CLOCK_HOUR_OF_DAY, 2) K 1 appendValue(ChronoField.HOUR_OF_AMPM) KK 2 appendValue(ChronoField.HOUR_OF_AMPM, 2) m 1 appendValue(ChronoField.MINUTE_OF_HOUR) mm 2 appendValue(ChronoField.MINUTE_OF_HOUR, 2) s 1 appendValue(ChronoField.SECOND_OF_MINUTE) ss 2 appendValue(ChronoField.SECOND_OF_MINUTE, 2) S..S 1..n appendFraction(ChronoField.NANO_OF_SECOND, n, n, false) A..A 1..n appendValue(ChronoField.MILLI_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE) n..n 1..n appendValue(ChronoField.NANO_OF_SECOND, n, 19, SignStyle.NOT_NEGATIVE) N..N 1..n appendValue(ChronoField.NANO_OF_DAY, n, 19, SignStyle.NOT_NEGATIVE)
Day periods: Pattern letters to output a day period.
Pattern Count Equivalent builder methods ------- ----- -------------------------- B 1 appendDayPeriodText(TextStyle.SHORT) BBBB 4 appendDayPeriodText(TextStyle.FULL) BBBBB 5 appendDayPeriodText(TextStyle.NARROW)
Zone ID: Pattern letters to output
ZoneId
.Pattern Count Equivalent builder methods ------- ----- -------------------------- VV 2 appendZoneId() v 1 appendGenericZoneText(TextStyle.SHORT) vvvv 4 appendGenericZoneText(TextStyle.FULL) z 1 appendZoneText(TextStyle.SHORT) zz 2 appendZoneText(TextStyle.SHORT) zzz 3 appendZoneText(TextStyle.SHORT) zzzz 4 appendZoneText(TextStyle.FULL)
Zone offset: Pattern letters to output
ZoneOffset
.Pattern Count Equivalent builder methods ------- ----- -------------------------- O 1 appendLocalizedOffset(TextStyle.SHORT) OOOO 4 appendLocalizedOffset(TextStyle.FULL) X 1 appendOffset("+HHmm","Z") XX 2 appendOffset("+HHMM","Z") XXX 3 appendOffset("+HH:MM","Z") XXXX 4 appendOffset("+HHMMss","Z") XXXXX 5 appendOffset("+HH:MM:ss","Z") x 1 appendOffset("+HHmm","+00") xx 2 appendOffset("+HHMM","+0000") xxx 3 appendOffset("+HH:MM","+00:00") xxxx 4 appendOffset("+HHMMss","+0000") xxxxx 5 appendOffset("+HH:MM:ss","+00:00") Z 1 appendOffset("+HHMM","+0000") ZZ 2 appendOffset("+HHMM","+0000") ZZZ 3 appendOffset("+HHMM","+0000") ZZZZ 4 appendLocalizedOffset(TextStyle.FULL) ZZZZZ 5 appendOffset("+HH:MM:ss","Z")
Modifiers: Pattern letters that modify the rest of the pattern:
Pattern Count Equivalent builder methods ------- ----- -------------------------- [ 1 optionalStart() ] 1 optionalEnd() p..p 1..n padNext(n)
Any sequence of letters not specified above, unrecognized letter or reserved character will throw an exception. Future versions may add to the set of patterns. 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.
Note that the pattern string is similar, but not identical, to
SimpleDateFormat
. The pattern string is also similar, but not identical, to that defined by the Unicode Common Locale Data Repository (CLDR/LDML). Pattern letters 'X' and 'u' are aligned with Unicode CLDR/LDML. By contrast,SimpleDateFormat
uses 'u' for the numeric day of week. Pattern letters 'y' and 'Y' parse years of two digits and more than 4 digits differently. Pattern letters 'n', 'A', 'N', and 'p' are added. Number types will reject large numbers.- Parameters:
pattern
- the pattern to add, not null- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if the pattern is invalid
-
padNext
Causes the next added printer/parser to pad to a fixed width using a space.This padding will pad to a fixed width using spaces.
During formatting, the decorated element will be output and then padded to the specified width. An exception will be thrown during formatting if the pad width is exceeded.
During parsing, the padding and decorated element are parsed. If parsing is lenient, then the pad width is treated as a maximum. The padding is parsed greedily. Thus, if the decorated element starts with the pad character, it will not be parsed.
- Parameters:
padWidth
- the pad width, 1 or greater- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if pad width is too small
-
padNext
Causes the next added printer/parser to pad to a fixed width.This padding is intended for padding other than zero-padding. Zero-padding should be achieved using the appendValue methods.
During formatting, the decorated element will be output and then padded to the specified width. An exception will be thrown during formatting if the pad width is exceeded.
During parsing, the padding and decorated element are parsed. If parsing is lenient, then the pad width is treated as a maximum. If parsing is case insensitive, then the pad character is matched ignoring case. The padding is parsed greedily. Thus, if the decorated element starts with the pad character, it will not be parsed.
- Parameters:
padWidth
- the pad width, 1 or greaterpadChar
- the pad character- Returns:
- this, for chaining, not null
- Throws:
IllegalArgumentException
- if pad width is too small
-
optionalStart
Mark the start of an optional section.The output of formatting 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 formatting, 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 formatting, 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.- Returns:
- this, for chaining, not null
-
optionalEnd
Ends an optional section.The output of formatting 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 callingoptionalStart
has no effect on the formatter other than ending the (empty) optional section.All elements in the optional section are treated as optional. During formatting, 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 formatting, 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.- Returns:
- this, for chaining, not null
- Throws:
IllegalStateException
- if there was no previous call tooptionalStart
-
toFormatter
Completes this builder by creating theDateTimeFormatter
using the default locale.This will create a formatter with the default FORMAT locale. Numbers will be printed and parsed using the standard DecimalStyle. The resolver style will be
SMART
.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
.- Returns:
- the created formatter, not null
-
toFormatter
Completes this builder by creating theDateTimeFormatter
using the specified locale.This will create a formatter with the specified locale. Numbers will be printed and parsed using the standard DecimalStyle. The resolver style will be
SMART
.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
.- Parameters:
locale
- the locale to use for formatting, not null- Returns:
- the created formatter, not null
-