APIdia Launch Partner
Top Description Inners Fields Constructors Methods
java.time.format

public final Class DateTimeFormatterBuilder

extends Object
Class Inheritance
Static Imports
java.time.temporal.ChronoField.DAY_OF_MONTH, .ChronoField.HOUR_OF_DAY, .ChronoField.INSTANT_SECONDS, .ChronoField.MINUTE_OF_HOUR, .ChronoField.MONTH_OF_YEAR, .ChronoField.NANO_OF_SECOND, .ChronoField.OFFSET_SECONDS, .ChronoField.SECOND_OF_MINUTE, .ChronoField.YEAR, .ChronoField.ERA
Builder to create date-time formatters.

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.

Implementation Specification

This class is a mutable builder intended for use from a single thread.

Since
1.8

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
DateTimeFormatterBuilder.CharLiteralPrinterParser

Prints or parses a character literal.

pack-priv static class
DateTimeFormatterBuilder.ChronoPrinterParser

Prints or parses a chronology.

pack-priv static class
DateTimeFormatterBuilder.CompositePrinterParser

Composite printer and parser.

pack-priv static interface
DateTimeFormatterBuilder.DateTimePrinterParser

Strategy for formatting/parsing date-time information.

pack-priv static class
DateTimeFormatterBuilder.DayPeriod

DayPeriod class that represents a DayPeriod defined in CLDR.

pack-priv static class
DateTimeFormatterBuilder.DayPeriodPrinterParser

Prints or parses day periods.

pack-priv static class
DateTimeFormatterBuilder.DefaultValueParser

Defaults a value into the parse if not currently present.

pack-priv static class
DateTimeFormatterBuilder.FractionPrinterParser

Prints and parses a numeric date-time field with optional padding.

pack-priv static class
DateTimeFormatterBuilder.InstantPrinterParser

Prints or parses an ISO-8601 instant.

pack-priv static class
DateTimeFormatterBuilder.LocalizedOffsetIdPrinterParser

Prints or parses an offset ID.

pack-priv static class
DateTimeFormatterBuilder.LocalizedPrinterParser

Prints or parses a localized pattern.

pack-priv static class
DateTimeFormatterBuilder.NanosPrinterParser

Prints and parses a NANO_OF_SECOND field with optional padding.

pack-priv static class
DateTimeFormatterBuilder.NumberPrinterParser

Prints and parses a numeric date-time field with optional padding.

pack-priv static class
DateTimeFormatterBuilder.OffsetIdPrinterParser

Prints or parses an offset ID.

pack-priv static class
DateTimeFormatterBuilder.PadPrinterParserDecorator

Pads the output to a fixed width.

pack-priv static class
DateTimeFormatterBuilder.PrefixTree

A String based prefix tree for parsing time-zone names.

pack-priv static class
DateTimeFormatterBuilder.ReducedPrinterParser

Prints and parses a reduced numeric date-time field.

pack-priv static enum
DateTimeFormatterBuilder.SettingsParser

Enumeration to apply simple parse settings.

pack-priv static class
DateTimeFormatterBuilder.StringLiteralPrinterParser

Prints or parses a string literal.

pack-priv static class
DateTimeFormatterBuilder.TextPrinterParser

Prints or parses field text.

pack-priv static class
DateTimeFormatterBuilder.WeekBasedFieldPrinterParser

Prints or parses a localized pattern from a localized field.

pack-priv static class
DateTimeFormatterBuilder.ZoneIdPrinterParser

Prints or parses a zone ID.

pack-priv static class
DateTimeFormatterBuilder.ZoneTextPrinterParser

Prints or parses a zone ID.

Field Summary

Modifier and TypeField and Description
private DateTimeFormatterBuilder
active

The currently active builder, used by the outermost builder.

private final boolean
optional

Whether this builder produces an optional formatter.

private char
padNextChar

The character to pad the next field with.

private int
padNextWidth

The width to pad the next field to.

private final DateTimeFormatterBuilder
parent

The parent builder, null for the outermost builder.

private final List<DateTimeFormatterBuilder.DateTimePrinterParser>
printerParsers

The list of printers that will be used.

private static final TemporalQuery<ZoneId>
QUERY_REGION_ONLY

Query for a time-zone that is region-only.

private static final Pattern
VALID_TEMPLATE_PATTERN

private int
valueParserIndex

The index of the last variable width value parser.

Constructor Summary

AccessConstructor and Description
public
DateTimeFormatterBuilder()

Constructs a new instance of the builder.

private
DateTimeFormatterBuilder(DateTimeFormatterBuilder
the parent builder, not null
parent, boolean
whether the formatter is optional, not null
optional)

Constructs a new instance of the builder.

Method Summary

Modifier and TypeMethod and Description
public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
append(DateTimeFormatter
the formatter to add, not null
formatter)

Appends all the elements of a formatter to the builder.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendChronologyId()

Appends the chronology ID, such as 'ISO' or 'ThaiBuddhist', to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendChronologyText(TextStyle
the text style to use, not null
textStyle)

Appends the chronology name to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendDayPeriodText(TextStyle
the text style to use, not null
style)

Appends the day period text to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendFraction(TemporalField
the field to append, not null
field, int
the minimum width of the field excluding the decimal point, from 0 to 9
minWidth, int
the maximum width of the field excluding the decimal point, from 1 to 9
maxWidth, boolean
whether to output the localized decimal point symbol
decimalPoint)

Appends the fractional value of a date-time field to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendGenericZoneText(TextStyle
the text style to use, not null
textStyle)

Appends the generic time-zone name, such as 'Pacific Time', to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendGenericZoneText(TextStyle
the text style to use, not null
textStyle, Set<ZoneId>
the set of preferred zone ids, not null
preferredZones)

Appends the generic time-zone name, such as 'Pacific Time', to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendInstant()

Appends an instant using ISO-8601 to the formatter, formatting fractional digits in groups of three.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendInstant(int
the number of fractional second digits to format with, from 0 to 9, or -1 to use as many digits as necessary
fractionalDigits)

Appends an instant using ISO-8601 to the formatter with control over the number of fractional digits.

private int

Returns:

the index into the active parsers list
appendInternal(DateTimeFormatterBuilder.DateTimePrinterParser
the printer-parser to add, not null
pp)

Appends a printer and/or parser to the internal list handling padding.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendLiteral(char
the literal to append, not null
literal)

Appends a character literal to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendLiteral(String
the literal to append, not null
literal)

Appends a string literal to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendLocalized(FormatStyle
the date style to use, null means no date required
dateStyle, FormatStyle
the time style to use, null means no time required
timeStyle)

Appends a localized date-time pattern to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendLocalized(String
the requested template to use, not null
requestedTemplate)

Appends a localized pattern to the formatter using the requested template.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendLocalizedOffset(TextStyle
the format style to use, not null
style)

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

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendOffset(String
the pattern to use, not null
pattern, String
the text to use when the offset is zero, not null
noOffsetText)

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

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendOffsetId()

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

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendOptional(DateTimeFormatter
the formatter to add, not null
formatter)

Appends a formatter to the builder which will optionally format/parse.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendPattern(String
the pattern to add, not null
pattern)

Appends the elements defined by the specified pattern to the builder.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendText(TemporalField
the field to append, not null
field)

Appends the text of a date-time field to the formatter using the full text style.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendText(TemporalField
the field to append, not null
field, TextStyle
the text style to use, not null
textStyle)

Appends the text of a date-time field to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendText(TemporalField
the field to append, not null
field, Map<Long, String>
the map from the value to the text
textLookup)

Appends the text of a date-time field to the formatter using the specified map to supply the text.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendValue(TemporalField
the field to append, not null
field)

Appends the value of a date-time field to the formatter using a normal output style.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendValue(TemporalField
the field to append, not null
field, int
the width of the printed field, from 1 to 19
width)

Appends the value of a date-time field to the formatter using a fixed width, zero-padded approach.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendValue(TemporalField
the field to append, not null
field, int
the minimum field width of the printed field, from 1 to 19
minWidth, int
the maximum field width of the printed field, from 1 to 19
maxWidth, SignStyle
the positive/negative output style, not null
signStyle)

Appends the value of a date-time field to the formatter providing full control over formatting.

private DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendValue(DateTimeFormatterBuilder.NumberPrinterParser
the printer-parser, not null
pp)

Appends a fixed or variable width printer-parser handling adjacent value mode.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendValueReduced(TemporalField
the field to append, not null
field, int
the field width of the printed and parsed field, from 1 to 10
width, int
the maximum field width of the printed field, from 1 to 10
maxWidth, int
the base value of the range of valid values
baseValue)

Appends the reduced value of a date-time field to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendValueReduced(TemporalField
the field to append, not null
field, int
the field width of the printed and parsed field, from 1 to 10
width, int
the maximum field width of the printed field, from 1 to 10
maxWidth, ChronoLocalDate
the base date used to calculate the base value for the range of valid values in the parsed chronology, not null
baseDate)

Appends the reduced value of a date-time field to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendZoneId()

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

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
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.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendZoneRegionId()

Appends the time-zone region ID, such as 'Europe/Paris', to the formatter, rejecting the zone ID if it is a ZoneOffset.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendZoneText(TextStyle
the text style to use, not null
textStyle)

Appends the time-zone name, such as 'British Summer Time', to the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
appendZoneText(TextStyle
the text style to use, not null
textStyle, Set<ZoneId>
the set of preferred zone ids, not null
preferredZones)

Appends the time-zone name, such as 'British Summer Time', to the formatter.

private static int

Returns:

the int style, or -1 if style is null, indicating un-required
convertStyle(FormatStyle
the FormatStyle style
style)

Converts the given FormatStyle to the java.text.DateFormat style.

private static TemporalField

Returns:

the TemporalField for the given pattern character, or null if not applicable
getField(char
the pattern character
ch)

Returns the TemporalField for the given pattern character.

public static String

Returns:

the locale and Chronology specific formatting pattern
getLocalizedDateTimePattern(FormatStyle
the FormatStyle for the date, null for time-only pattern
dateStyle, FormatStyle
the FormatStyle for the time, null for date-only pattern
timeStyle, Chronology
the Chronology, non-null
chrono, Locale
the locale, non-null
locale)

Gets the formatting pattern for date and time styles for a locale and chronology.

public static String

Returns:

the locale and Chronology specific formatting pattern
getLocalizedDateTimePattern(String
the requested template, not null
requestedTemplate, Chronology
the Chronology, non-null
chrono, Locale
the locale, non-null
locale)

Returns the formatting pattern for the requested template for a locale and chronology.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
optionalEnd()

Ends an optional section.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
optionalStart()

Mark the start of an optional section.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
padNext(int
the pad width, 1 or greater
padWidth)

Causes the next added printer/parser to pad to a fixed width using a space.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
padNext(int
the pad width, 1 or greater
padWidth, char
the pad character
padChar)

Causes the next added printer/parser to pad to a fixed width.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
parseCaseInsensitive()

Changes the parse style to be case insensitive for the remainder of the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
parseCaseSensitive()

Changes the parse style to be case sensitive for the remainder of the formatter.

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
parseDefaulting(TemporalField
the field to default the value of, not null
field, long
the value to default the field to
value)

Appends a default value for a field to the formatter for use in parsing.

private void
parseField(char cur, int count, TemporalField field)

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
parseLenient()

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

private void
parsePattern(String pattern)

public DateTimeFormatterBuilder

Returns:

this, for chaining, not null
parseStrict()

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

public DateTimeFormatter

Returns:

the created formatter, not null
toFormatter()

Completes this builder by creating the DateTimeFormatter using the default locale.

public DateTimeFormatter

Returns:

the created formatter, not null
toFormatter(Locale
the locale to use for formatting, not null
locale)

Completes this builder by creating the DateTimeFormatter using the specified locale.

pack-priv DateTimeFormatter

Returns:

the created formatter, not null
toFormatter(ResolverStyle
the resolver style to use, not null
resolverStyle, Chronology chrono)

Completes this builder by creating the formatter.

private DateTimeFormatter

Returns:

the created formatter, not null
toFormatter(Locale
the locale to use for formatting, not null
locale, ResolverStyle resolverStyle, Chronology
the chronology to use, may be null
chrono)

Completes this builder by creating the formatter.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait