DateTimeFormatter

A query that provides access to the excess days that were parsed.

This returns a singleton {@linkplain TemporalQuery query} that provides access to additional information from the parse. The query always returns a non-null period, with a zero period returned instead of null.

There are two situations where this query may return a non-zero period.

In both cases, if a complete {@code ChronoLocalDateTime} or {@code Instant} is parsed, then the excess days are added to the date part. As a result, this query will return a zero period.

The {@code SMART} behaviour handles the common "end of day" 24:00 value. Processing in {@code LENIENT} mode also produces the same result:

 Text to parse        Parsed object                         Excess days
 "2012-12-03T00:00"   LocalDateTime.of(2012, 12, 3, 0, 0)   ZERO
 "2012-12-03T24:00"   LocalDateTime.of(2012, 12, 4, 0, 0)   ZERO
 "00:00"              LocalTime.of(0, 0)                    ZERO
 "24:00"              LocalTime.of(0, 0)                    Period.ofDays(1)

 TemporalAccessor parsed = formatter.parse(str);
 LocalTime time = parsed.query(LocalTime.FROM);
 Period extraDays = parsed.query(DateTimeFormatter.parsedExcessDays());

A query that provides access to whether a leap-second was parsed.

This returns a singleton {@linkplain TemporalQuery query} that provides access to additional information from the parse. The query always returns a non-null boolean, true if parsing saw a leap-second, false if not.

Instant parsing handles the special "leap second" time of '23:59:60'. Leap seconds occur at '23:59:60' in the UTC time-zone, but at other local times in different time-zones. To avoid this potential ambiguity, the handling of leap-seconds is limited to {@link DateTimeFormatterBuilder#appendInstant()}, as that method always parses the instant with the UTC zone offset.

If the time '23:59:60' is received, then a simple conversion is applied, replacing the second-of-minute of 60 with 59. This query can be used on the parse result to determine if the leap-second adjustment was made. The query will return one second of excess if it did adjust to remove the leap-second, and zero if not. Note that applying a leap-second smoothing mechanism, such as UTC-SLS, is the responsibility of the application, as follows:

 TemporalAccessor parsed = formatter.parse(str);
 Instant instant = parsed.query(Instant::from);
 if (parsed.query(DateTimeFormatter.parsedLeapSecond())) {
   // validate leap-second is correct and apply correct smoothing
 }

Constructor.

Formats a date-time object using this formatter.

This formats the date-time to a String using the rules of the formatter.

Throw:

function overloading for DateTimeFormatter.parse

if called with one arg DateTimeFormatter.parse1 is called otherwise DateTimeFormatter.parse2

Fully parses the text producing a temporal object.

This parses the entire text producing a temporal object. It is typically more useful to use {@link #parse(CharSequence, TemporalQuery)}. The result of this method is {@code 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.

Throw:

Fully parses the text producing a temporal object.

This parses the entire text producing a temporal object. It is typically more useful to use {@link #parse(CharSequence, TemporalQuery)}. The result of this method is {@code 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.

Throw:

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 {@code Map} of field to value, a {@code ZoneId} and a {@code Chronology}. Second, the parsed data is <em>resolved</em>, 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 {@code 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 {@code ParsePosition}. The entire length of the text does not have to be parsed, the {@code ParsePosition} will be updated with the index at the end of parsing.

Errors are returned using the error index field of the {@code ParsePosition} instead of {@code 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 {@link #parse(CharSequence, TemporalQuery)} or the parse method on the target type.

Throw:

Returns the formatter as a composite printer parser.

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 {@code 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 {@code ChronoLocalDate},{@code ChronoLocalDateTime} or {@code ChronoZonedDateTime}.

When parsing, the override chronology will be used to interpret the {@linkplain ChronoField fields} into a date unless the formatter directly parses a valid chronology.

This instance is immutable and unaffected by this method call.

not yet supported