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
DateTimeException
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
DateTimeException
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 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.
LocalDateTime.FROM); 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
DateTimeParseException
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
DateTimeParseException
if unable to parse the requested result
IndexOutOfBoundsException
if 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
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
DateTimeParseException
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.
else { ... } 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
DateTimeParseException
if unable to parse the requested result
IllegalArgumentException
if 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 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
DateTimeException
if some problem occurs during parsing
IndexOutOfBoundsException
if 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 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 YEAR
and 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
, 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 YEAR
and 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
, 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 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 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
DateTimeFormatter
are provided:yyyy-MMM-dd
long
ormedium
#ISO_LOCAL_DATE
For more complex formatters, a
builder
is 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
Format
class for formatting. The#toFormat()
method returns an implementation of the old API.Specification for implementors
This class is immutable and thread-safe.
LocalDate.parse(text, formatter); the locale. The locale can be changed using the `[[#withLocale(Locale)]]` method which returns a new formatter in the requested locale. Some applications may need to use the older `[[Format]]` class for formatting. The `[[ #toFormat()]]` method returns an implementation of the old API. === Specification for implementors === This class is immutable and thread-safe.