Formats a date-time object using this formatter.
Formats a date-time object using this formatter.
This formats the date-time to a String using the rules of the formatter.
the temporal object to print, not null
the printed string, not null
if an error occurs during formatting
Formats a date-time object to an Appendable using this formatter.
Formats a date-time object to an Appendable using this formatter.
This formats the date-time to the specified destination.
Appendable is a general purpose interface that is implemented by all
key character output classes including StringBuffer, StringBuilder,
PrintStream and Writer.
Although Appendable methods throw an IOException, this method does not.
Instead, any IOException is wrapped in a runtime exception.
the temporal object to print, not null
the appendable to print to, not null
if an error occurs during formatting
Gets the overriding chronology to be used during formatting.
Gets the overriding chronology to be used during formatting.
This returns the override chronology, used to convert dates.
By default, a formatter has no override chronology, returning null.
See #withChronology(Chronology) for more details on overriding.
the chronology of this formatter, null if no override
Gets the decimal style to be used during formatting.
Gets the decimal style to be used during formatting.
the decimal style of this formatter, not null
Gets the locale to be used during formatting.
Gets the locale to be used during formatting.
This is used to lookup any part of the formatter needing specific localization, such as the text or localized pattern.
the locale of this formatter, not null
Gets the resolver fields to use during parsing.
Gets the resolver fields to use during parsing.
This returns the resolver fields, used during the second phase of parsing
when fields are resolved into dates and times.
By default, a formatter has no resolver fields, and thus returns null.
See #withResolverFields(Set) for more details.
the immutable set of resolver fields of this formatter, null if no fields
Gets the resolver style to use during parsing.
Gets the resolver style to use during parsing.
This returns the resolver style, used during the second phase of parsing
when fields are resolved into dates and times.
By default, a formatter has the ResolverStyle#SMART SMART resolver style.
See #withResolverStyle(ResolverStyle) for more details.
the resolver style of this formatter, not null
Gets the overriding zone to be used during formatting.
Gets the overriding zone to be used during formatting.
This returns the override zone, used to convert instants.
By default, a formatter has no override zone, returning null.
See #withZone(ZoneId) for more details on overriding.
the chronology of this formatter, null if no override
Fully parses the text producing an object of the specified type.
Fully parses the text producing an object of the specified type.
Most applications should use this method for parsing. It parses the entire text to produce the required date-time. For example:
LocalDateTime dt = parser.parse(str, LocalDateTime.FROM);If the parse completes without reading the entire length of the text, or a problem occurs during parsing or merging, then an exception is thrown.
the type to extract
the text to parse, not null
the type to extract, not null
the parsed date-time, not null
if unable to parse the requested result
Parses the text using this formatter, providing control over the text position.
Parses the text using this formatter, providing control over the text position.
This parses the text without requiring the parse to start from the beginning
of the string or finish at the end.
The result of this method is TemporalAccessor which has been resolved,
applying basic validation checks to help ensure a valid date-time.
The text will be parsed from the specified start ParsePosition.
The entire length of the text does not have to be parsed, the ParsePosition
will be updated with the index at the end of parsing.
The operation of this method is slightly different to similar methods using
ParsePosition on java.text.Format. That class will return
errors using the error index on the ParsePosition. By contrast, this
method will throw a DateTimeParseException if an error occurs, with
the exception containing the error index.
This change in behavior is necessary due to the increased complexity of
parsing and resolving dates/times in this API.
If the formatter parses the same field more than once with different values, the result will be an error.
the text to parse, not null
the position to parse from, updated with length parsed and the index of any error, not null
the parsed temporal object, not null
if unable to parse the requested result
IndexOutOfBoundsExceptionif the position is invalid
Fully parses the text producing a temporal object.
Fully parses the text producing a temporal object.
This parses the entire text producing a temporal object.
It is typically more useful to use #parse(CharSequence, TemporalQuery).
The result of this method is TemporalAccessor which has been resolved,
applying basic validation checks to help ensure a valid date-time.
If the parse completes without reading the entire length of the text, or a problem occurs during parsing or merging, then an exception is thrown.
the text to parse, not null
the parsed temporal object, not null
if unable to parse the requested result
Fully parses the text producing an object of one of the specified types.
Fully parses the text producing an object of one of the specified types.
This parse method is convenient for use when the parser can handle optional elements.
For example, a pattern of 'yyyy[-MM[-dd]]' can be fully parsed to a LocalDate,
or partially parsed to a YearMonth or a Year.
The types must be specified in order, starting from the best matching full-parse option
and ending with the worst matching minimal parse option.
The result is associated with the first type that successfully parses.
Normally, applications will use instanceof to check the result.
For example:
TemporalAccessor dt = parser.parseBest(str, LocalDate.FROM, YearMonth.FROM);
if (dt instanceof LocalDate) {
...
} else {
...
}
If the parse completes without reading the entire length of the text,
or a problem occurs during parsing or merging, then an exception is thrown.
the text to parse, not null
the types to attempt to parse to, which must implement { @code TemporalAccessor}, not null
the parsed date-time, not null
if unable to parse the requested result
IllegalArgumentExceptionif less than 2 types are specified
Parses the text using this formatter, without resolving the result, intended for advanced use cases.
Parses the text using this formatter, without resolving the result, intended for advanced use cases.
Parsing is implemented as a two-phase operation.
First, the text is parsed using the layout defined by the formatter, producing
a Map of field to value, a ZoneId and a Chronology.
Second, the parsed data is resolved, by validating, combining and
simplifying the various fields into more useful ones.
This method performs the parsing stage but not the resolving stage.
The result of this method is TemporalAccessor which represents the
data as seen in the input. Values are not validated, thus parsing a date string
of '2012-00-65' would result in a temporal with three fields - year of '2012',
month of '0' and day-of-month of '65'.
The text will be parsed from the specified start ParsePosition.
The entire length of the text does not have to be parsed, the ParsePosition
will be updated with the index at the end of parsing.
Errors are returned using the error index field of the ParsePosition
instead of DateTimeParseException.
The returned error index will be set to an index indicative of the error.
Callers must check for errors before using the context.
If the formatter parses the same field more than once with different values, the result will be an error.
This method is intended for advanced use cases that need access to the
internal state during parsing. Typical application code should use
#parse(CharSequence, TemporalQuery) or the parse method on the target type.
the text to parse, not null
the position to parse from, updated with length parsed and the index of any error, not null
the parsed text, null if the parse results in an error
if some problem occurs during parsing
IndexOutOfBoundsExceptionif the position is invalid
Returns this formatter as a java.text.Format instance that will
parse to the specified type.
Returns this formatter as a java.text.Format instance that will
parse to the specified type.
The returned Format instance will print any TemporalAccessor
and parses to the type specified.
The type must be one that is supported by #parse.
Exceptions will follow the definitions of Format, see those methods
for details about IllegalArgumentException during formatting and
ParseException or null during parsing.
The format does not support attributing of the returned format string.
the query to parse to, not null
this formatter as a classic format instance, not null
Returns this formatter as a java.text.Format instance.
Returns this formatter as a java.text.Format instance.
The returned Format instance will print any TemporalAccessor
and parses to a resolved TemporalAccessor.
Exceptions will follow the definitions of Format, see those methods
for details about IllegalArgumentException during formatting and
ParseException or null during parsing.
The format does not support attributing of the returned format string.
this formatter as a classic format instance, not null
Returns a description of the underlying formatters.
Returns a description of the underlying formatters.
a description of this formatter, not null
Returns a copy of this formatter with a new override chronology.
Returns a copy of this formatter with a new override chronology.
This returns a formatter with similar state to this formatter but with the override chronology set. By default, a formatter has no override chronology, returning null.
If an override is added, then any date that is printed or parsed will be affected.
When printing, if the Temporal object contains a date then it will
be converted to a date in the override chronology.
Any time or zone will be retained unless overridden.
The converted result will behave in a manner equivalent to an implementation
of ChronoLocalDate, ChronoLocalDateTime or ChronoZonedDateTime.
When parsing, the override chronology will be used to interpret the
plain ChronoField fields into a date unless the
formatter directly parses a valid chronology.
This instance is immutable and unaffected by this method call.
the new chronology, not null
a formatter based on this formatter with the requested override chronology, not null
Returns a copy of this formatter with a new decimal style.
Returns a copy of this formatter with a new decimal style.
This instance is immutable and unaffected by this method call.
the new decimal style, not null
a formatter based on this formatter with the requested symbols, not null
Returns a copy of this formatter with a new locale.
Returns a copy of this formatter with a new locale.
This is used to lookup any part of the formatter needing specific localization, such as the text or localized pattern.
This instance is immutable and unaffected by this method call.
the new locale, not null
a formatter based on this formatter with the requested locale, not null
Returns a copy of this formatter with a new set of resolver fields.
Returns a copy of this formatter with a new set of resolver fields.
This returns a formatter with similar state to this formatter but with the resolver fields set. By default, a formatter has no resolver fields.
Changing the resolver fields only has an effect during parsing. Parsing a text string occurs in two phases. Phase 1 is a basic text parse according to the fields added to the builder. Phase 2 resolves the parsed field-value pairs into date and/or time objects. The resolver fields are used to filter the field-value pairs between phase 1 and 2.
This can be used to select between two or more ways that a date or time might
be resolved. For example, if the formatter consists of year, month, day-of-month
and day-of-year, then there are two ways to resolve a date.
Calling this method with the arguments ChronoField#YEAR YEAR and
ChronoField#DAY_OF_YEAR DAY_OF_YEAR will ensure that the date is
resolved using the year and day-of-year, effectively meaning that the month
and day-of-month are ignored during the resolving phase.
In a similar manner, this method can be used to ignore secondary fields that
would otherwise be cross-checked. For example, if the formatter consists of year,
month, day-of-month and day-of-week, then there is only one way to resolve a
date, but the parsed value for day-of-week will be cross-checked against the
resolved date. Calling this method with the arguments ChronoField#YEAR YEAR,
ChronoField#MONTH_OF_YEAR MONTH_OF_YEAR and
ChronoField#DAY_OF_MONTH DAY_OF_MONTH will ensure that the date is
resolved correctly, but without any cross-check for the day-of-week.
In implementation terms, this method behaves as follows. The result of the parsing phase can be considered to be a map of field to value. The behavior of this method is to cause that map to be filtered between phase 1 and 2, removing all fields other than those specified as arguments to this method.
This instance is immutable and unaffected by this method call.
the new set of resolver fields, null if no fields
a formatter based on this formatter with the requested resolver style, not null
Returns a copy of this formatter with a new set of resolver fields.
Returns a copy of this formatter with a new set of resolver fields.
This returns a formatter with similar state to this formatter but with the resolver fields set. By default, a formatter has no resolver fields.
Changing the resolver fields only has an effect during parsing. Parsing a text string occurs in two phases. Phase 1 is a basic text parse according to the fields added to the builder. Phase 2 resolves the parsed field-value pairs into date and/or time objects. The resolver fields are used to filter the field-value pairs between phase 1 and 2.
This can be used to select between two or more ways that a date or time might
be resolved. For example, if the formatter consists of year, month, day-of-month
and day-of-year, then there are two ways to resolve a date.
Calling this method with the arguments ChronoField#YEAR YEAR and
ChronoField#DAY_OF_YEAR DAY_OF_YEAR will ensure that the date is
resolved using the year and day-of-year, effectively meaning that the month
and day-of-month are ignored during the resolving phase.
In a similar manner, this method can be used to ignore secondary fields that
would otherwise be cross-checked. For example, if the formatter consists of year,
month, day-of-month and day-of-week, then there is only one way to resolve a
date, but the parsed value for day-of-week will be cross-checked against the
resolved date. Calling this method with the arguments ChronoField#YEAR YEAR,
ChronoField#MONTH_OF_YEAR MONTH_OF_YEAR and
ChronoField#DAY_OF_MONTH DAY_OF_MONTH will ensure that the date is
resolved correctly, but without any cross-check for the day-of-week.
In implementation terms, this method behaves as follows. The result of the parsing phase can be considered to be a map of field to value. The behavior of this method is to cause that map to be filtered between phase 1 and 2, removing all fields other than those specified as arguments to this method.
This instance is immutable and unaffected by this method call.
the new set of resolver fields, null if no fields
a formatter based on this formatter with the requested resolver style, not null
Returns a copy of this formatter with a new resolver style.
Returns a copy of this formatter with a new resolver style.
This returns a formatter with similar state to this formatter but
with the resolver style set. By default, a formatter has the
ResolverStyle#SMART SMART resolver style.
Changing the resolver style only has an effect during parsing.
Parsing a text string occurs in two phases.
Phase 1 is a basic text parse according to the fields added to the builder.
Phase 2 resolves the parsed field-value pairs into date and/or time objects.
The resolver style is used to control how phase 2, resolving, happens.
See ResolverStyle for more information on the options available.
This instance is immutable and unaffected by this method call.
the new resolver style, not null
a formatter based on this formatter with the requested resolver style, not null
Returns a copy of this formatter with a new override zone.
Returns a copy of this formatter with a new override zone.
This returns a formatter with similar state to this formatter but with the override zone set. By default, a formatter has no override zone, returning null.
If an override is added, then any instant that is printed or parsed will be affected.
When printing, if the Temporal object contains an instant then it will
be converted to a zoned date-time using the override zone.
If the input has a chronology then it will be retained unless overridden.
If the input does not have a chronology, such as Instant, then
the ISO chronology will be used.
The converted result will behave in a manner equivalent to an implementation
of ChronoZonedDateTime.
When parsing, the override zone will be used to interpret the
plain ChronoField fields into an instant unless the
formatter directly parses a valid zone.
This instance is immutable and unaffected by this method call.
the new override zone, not null
a formatter based on this formatter with the requested override zone, not null
Formatter for printing and parsing date-time objects.
This class provides the main application entry point for printing and parsing. Common instances of
DateTimeFormatterare provided:yyyy-MMM-ddlongormedium#ISO_LOCAL_DATEFor more complex formatters, a
DateTimeFormatterBuilder builderis provided.In most cases, it is not necessary to use this class directly when formatting. The main date-time classes provide two methods - one for formatting,
Some aspects of printing and parsing are dependent on the locale. The locale can be changed using theformat(DateTimeFormatter formatter), and one for parsing, For example:#withLocale(Locale)method which returns a new formatter in the requested locale.Some applications may need to use the older
Formatclass for formatting. The#toFormat()method returns an implementation of the old API.Specification for implementors
This class is immutable and thread-safe.