DateTimeFormatterBuilder

Constructs a new instance of the builder.

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.

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. 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.

Throw:

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 this.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 ChronoField#INSTANT_SECONDS and optionally (@code NANO_OF_SECOND). The value of INSTANT_SECONDS may be outside the maximum range of LocalDateTime.

The ResolverStyle 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.

An alternative to this method is to format/parse the instant as a single epoch-seconds value. That is achieved using appendValue(INSTANT_SECONDS).

Appends a string literal to the formatter.

This string will be output during a print.

If the literal is empty, nothing is added to the formatter.

Appends the zone offset, such as '+01:00', to the formatter.

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 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.

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 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

The "no offset" text controls what text is printed when the total amount of the offset fields to be output 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.

Appends the zone offset, such as '+01:00', to the formatter.

This appends an instruction to print/parse the offset ID to the builder. This is equivalent to calling appendOffset("HH:MM:ss", "Z").

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                        | number/text      | 1; 01; AD; Anno Domini
 | u      | year                       | year             | 2004; 04
 | y      | year-of-era                | 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
 |        |                            |                  |
 | V      | time-zone ID               | zone-id          | America/Los_Angeles; Z; -08:30
 | z      | time-zone name             | zone-name        | Pacific Standard Time; PST
 | 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    |                  |

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 (see TextStyle#SHORT). Exactly 4 pattern letters will use the full form (see TextStyle#FULL). Exactly 5 pattern letters will use the narrow form (see TextStyle#NARROW).

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. Otherwise, the count of digits is used as the width of the output field as per appendValue.

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 (see appendValueReduced) 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: This outputs the time-zone ID, such as 'Europe/Paris'. If the count of letters is two, then the time-zone ID is output. Any other count of letters throws IllegalArgumentException.

 Pattern     Equivalent builder methods
  VV          appendZoneId()

Zone names: This outputs the display name of the time-zone ID. If the count of letters is one, two or three, then the short name is output. If the count of letters is four, then the full name is output. Five or more letters throws IllegalArgumentException.

 Pattern     Equivalent builder methods
  z           appendZoneText(TextStyle.SHORT)
  zz          appendZoneText(TextStyle.SHORT)
  zzz         appendZoneText(TextStyle.SHORT)
  zzzz        appendZoneText(TextStyle.FULL)

Offset X and x: This formats the offset based on the number of pattern letters. One letter outputs just the hour', such as '+01', unless the minute is non-zero in which case the minute is also output, such as '+0130'. 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'. Six or more letters throws IllegalArgumentException. Pattern letter 'X' (upper case) will output 'Z' when the offset to be output would be zero, whereas pattern letter 'x' (lower case) will output '+00', '+0000', or '+00:00'.

 Pattern     Equivalent builder methods
  X           appendOffset("+HHmm","Z")
  XX          appendOffset("+HHMM","Z")
  XXX         appendOffset("+HH:MM","Z")
  XXXX        appendOffset("+HHMMss","Z")
  XXXXX       appendOffset("+HH:MM:ss","Z")
  x           appendOffset("+HHmm","+00")
  xx          appendOffset("+HHMM","+0000")
  xxx         appendOffset("+HH:MM","+00:00")
  xxxx        appendOffset("+HHMMss","+0000")
  xxxxx       appendOffset("+HH:MM:ss","+00:00")

Offset Z: This formats the offset based on the number of pattern letters. One, two or three letters outputs the hour and minute, without a colon, such as '+0130'. Four or more letters throws IllegalArgumentException. The output will be '+0000' when the offset is zero.

 Pattern     Equivalent builder methods
  Z           appendOffset("+HHMM","+0000")
  ZZ          appendOffset("+HHMM","+0000")
  ZZZ         appendOffset("+HHMM","+0000")

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.

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.

Note that the pattern string is similar, but not identical, to java.text.SimpleDateFormat. The pattern string is also similar, but not identical, to that defined by the Unicode Common Locale Data Repository (CLDR/LDML). Pattern letters 'E' and 'u' are merged, which changes the meaning of "E" and "EE" to be numeric. Pattern letters 'X' is aligned with Unicode CLDR/LDML, which affects pattern 'X'. 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.

Throw:

appendValue function overloading

appendValueReduced function overloading

Appends the time-zone ID, such as 'Europe/Paris' or '+02:00', to the formatter.

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 TemporalQueries#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.

See:

• #appendZoneRegionId()

Ends an optional section.

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.

Throw:

Mark the start of an optional section.

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.

padNext function overloading

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 sensitive 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.

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.

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.

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 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 strict from this point onwards. The change will remain in force until the end of the formatter that is eventually constructed or until parseStrict is called.

Changes the parse style to be strict for the remainder of the formatter.

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.

Completes this builder by creating the DateTimeFormatter.

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.