1 /*
2 * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /*
27 * This file is available under and governed by the GNU General Public
28 * License version 2 only, as published by the Free Software Foundation.
29 * However, the following notice accompanied the original version of this
30 * file:
31 *
32 * Copyright (c) 2008-2012, Stephen Colebourne & Michael Nascimento Santos
33 *
34 * All rights reserved.
35 *
36 * Redistribution and use in source and binary forms, with or without
37 * modification, are permitted provided that the following conditions are met:
38 *
39 * * Redistributions of source code must retain the above copyright notice,
40 * this list of conditions and the following disclaimer.
41 *
42 * * Redistributions in binary form must reproduce the above copyright notice,
43 * this list of conditions and the following disclaimer in the documentation
44 * and/or other materials provided with the distribution.
45 *
46 * * Neither the name of JSR-310 nor the names of its contributors
47 * may be used to endorse or promote products derived from this software
48 * without specific prior written permission.
49 *
50 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
51 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
52 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
53 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
54 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
55 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
56 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
57 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
58 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
59 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
60 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
61 */
62 package java.time.format;
63
64 import static java.time.temporal.ChronoField.DAY_OF_MONTH;
65 import static java.time.temporal.ChronoField.DAY_OF_WEEK;
66 import static java.time.temporal.ChronoField.DAY_OF_YEAR;
67 import static java.time.temporal.ChronoField.HOUR_OF_DAY;
68 import static java.time.temporal.ChronoField.MINUTE_OF_HOUR;
69 import static java.time.temporal.ChronoField.MONTH_OF_YEAR;
70 import static java.time.temporal.ChronoField.NANO_OF_SECOND;
71 import static java.time.temporal.ChronoField.SECOND_OF_MINUTE;
72 import static java.time.temporal.ChronoField.YEAR;
73
74 import java.io.IOException;
75 import java.text.FieldPosition;
76 import java.text.Format;
77 import java.text.ParseException;
78 import java.text.ParsePosition;
79 import java.time.DateTimeException;
80 import java.time.Period;
81 import java.time.ZoneId;
82 import java.time.ZoneOffset;
83 import java.time.chrono.ChronoLocalDateTime;
84 import java.time.chrono.Chronology;
85 import java.time.chrono.IsoChronology;
86 import java.time.format.DateTimeFormatterBuilder.CompositePrinterParser;
87 import java.time.temporal.ChronoField;
88 import java.time.temporal.IsoFields;
89 import java.time.temporal.TemporalAccessor;
90 import java.time.temporal.TemporalField;
91 import java.time.temporal.TemporalQuery;
92 import java.util.Arrays;
93 import java.util.Collections;
94 import java.util.HashMap;
95 import java.util.HashSet;
96 import java.util.Locale;
97 import java.util.Map;
98 import java.util.Objects;
99 import java.util.Set;
100
101 /**
102 * Formatter for printing and parsing date-time objects.
103 * <p>
104 * This class provides the main application entry point for printing and parsing
105 * and provides common implementations of {@code DateTimeFormatter}:
106 * <ul>
107 * <li>Using predefined constants, such as {@link #ISO_LOCAL_DATE}</li>
108 * <li>Using pattern letters, such as {@code uuuu-MMM-dd}</li>
109 * <li>Using localized styles, such as {@code long} or {@code medium}</li>
110 * </ul>
111 * <p>
112 * More complex formatters are provided by
113 * {@link DateTimeFormatterBuilder DateTimeFormatterBuilder}.
114 *
115 * <p>
116 * The main date-time classes provide two methods - one for formatting,
117 * {@code format(DateTimeFormatter formatter)}, and one for parsing,
118 * {@code parse(CharSequence text, DateTimeFormatter formatter)}.
119 * <p>For example:
120 * <blockquote><pre>
121 * LocalDate date = LocalDate.now();
122 * String text = date.format(formatter);
123 * LocalDate parsedDate = LocalDate.parse(text, formatter);
124 * </pre></blockquote>
125 * <p>
126 * In addition to the format, formatters can be created with desired Locale,
127 * Chronology, ZoneId, and DecimalStyle.
128 * <p>
129 * The {@link #withLocale withLocale} method returns a new formatter that
130 * overrides the locale. The locale affects some aspects of formatting and
131 * parsing. For example, the {@link #ofLocalizedDate ofLocalizedDate} provides a
132 * formatter that uses the locale specific date format.
133 * <p>
134 * The {@link #withChronology withChronology} method returns a new formatter
135 * that overrides the chronology. If overridden, the date-time value is
136 * converted to the chronology before formatting. During parsing the date-time
137 * value is converted to the chronology before it is returned.
138 * <p>
139 * The {@link #withZone withZone} method returns a new formatter that overrides
140 * the zone. If overridden, the date-time value is converted to a ZonedDateTime
141 * with the requested ZoneId before formatting. During parsing the ZoneId is
142 * applied before the value is returned.
143 * <p>
144 * The {@link #withDecimalStyle withDecimalStyle} method returns a new formatter that
145 * overrides the {@link DecimalStyle}. The DecimalStyle symbols are used for
146 * formatting and parsing.
147 * <p>
148 * Some applications may need to use the older {@link Format java.text.Format}
149 * class for formatting. The {@link #toFormat()} method returns an
150 * implementation of {@code java.text.Format}.
151 *
152 * <h3 id="predefined">Predefined Formatters</h3>
153 * <table class="striped">
154 * <caption>Predefined Formatters</caption>
155 * <thead>
156 * <tr>
157 * <th style="text-align:left">Formatter</th>
158 * <th style="text-align:left">Description</th>
159 * <th style="text-align:left">Example</th>
160 * </tr>
161 * </thead>
162 * <tbody>
163 * <tr>
164 * <td>{@link #ofLocalizedDate ofLocalizedDate(dateStyle)} </td>
165 * <td> Formatter with date style from the locale </td>
166 * <td> '2011-12-03'</td>
167 * </tr>
168 * <tr>
169 * <td> {@link #ofLocalizedTime ofLocalizedTime(timeStyle)} </td>
170 * <td> Formatter with time style from the locale </td>
171 * <td> '10:15:30'</td>
172 * </tr>
173 * <tr>
174 * <td> {@link #ofLocalizedDateTime ofLocalizedDateTime(dateTimeStyle)} </td>
175 * <td> Formatter with a style for date and time from the locale</td>
176 * <td> '3 Jun 2008 11:05:30'</td>
177 * </tr>
178 * <tr>
179 * <td> {@link #ofLocalizedDateTime ofLocalizedDateTime(dateStyle,timeStyle)}
180 * </td>
181 * <td> Formatter with date and time styles from the locale </td>
182 * <td> '3 Jun 2008 11:05'</td>
183 * </tr>
184 * <tr>
185 * <td> {@link #BASIC_ISO_DATE}</td>
186 * <td>Basic ISO date </td> <td>'20111203'</td>
187 * </tr>
188 * <tr>
189 * <td> {@link #ISO_LOCAL_DATE}</td>
190 * <td> ISO Local Date </td>
191 * <td>'2011-12-03'</td>
192 * </tr>
193 * <tr>
194 * <td> {@link #ISO_OFFSET_DATE}</td>
195 * <td> ISO Date with offset </td>
196 * <td>'2011-12-03+01:00'</td>
197 * </tr>
198 * <tr>
199 * <td> {@link #ISO_DATE}</td>
200 * <td> ISO Date with or without offset </td>
201 * <td> '2011-12-03+01:00'; '2011-12-03'</td>
202 * </tr>
203 * <tr>
204 * <td> {@link #ISO_LOCAL_TIME}</td>
205 * <td> Time without offset </td>
206 * <td>'10:15:30'</td>
207 * </tr>
208 * <tr>
209 * <td> {@link #ISO_OFFSET_TIME}</td>
210 * <td> Time with offset </td>
211 * <td>'10:15:30+01:00'</td>
212 * </tr>
213 * <tr>
214 * <td> {@link #ISO_TIME}</td>
215 * <td> Time with or without offset </td>
216 * <td>'10:15:30+01:00'; '10:15:30'</td>
217 * </tr>
218 * <tr>
219 * <td> {@link #ISO_LOCAL_DATE_TIME}</td>
220 * <td> ISO Local Date and Time </td>
221 * <td>'2011-12-03T10:15:30'</td>
222 * </tr>
223 * <tr>
224 * <td> {@link #ISO_OFFSET_DATE_TIME}</td>
225 * <td> Date Time with Offset
226 * </td><td>2011-12-03T10:15:30+01:00'</td>
227 * </tr>
228 * <tr>
229 * <td> {@link #ISO_ZONED_DATE_TIME}</td>
230 * <td> Zoned Date Time </td>
231 * <td>'2011-12-03T10:15:30+01:00[Europe/Paris]'</td>
232 * </tr>
233 * <tr>
234 * <td> {@link #ISO_DATE_TIME}</td>
235 * <td> Date and time with ZoneId </td>
236 * <td>'2011-12-03T10:15:30+01:00[Europe/Paris]'</td>
237 * </tr>
238 * <tr>
239 * <td> {@link #ISO_ORDINAL_DATE}</td>
240 * <td> Year and day of year </td>
241 * <td>'2012-337'</td>
242 * </tr>
243 * <tr>
244 * <td> {@link #ISO_WEEK_DATE}</td>
245 * <td> Year and Week </td>
246 * <td>2012-W48-6'</td></tr>
247 * <tr>
248 * <td> {@link #ISO_INSTANT}</td>
249 * <td> Date and Time of an Instant </td>
250 * <td>'2011-12-03T10:15:30Z' </td>
251 * </tr>
252 * <tr>
253 * <td> {@link #RFC_1123_DATE_TIME}</td>
254 * <td> RFC 1123 / RFC 822 </td>
255 * <td>'Tue, 3 Jun 2008 11:05:30 GMT'</td>
256 * </tr>
257 * </tbody>
258 * </table>
259 *
260 * <h3 id="patterns">Patterns for Formatting and Parsing</h3>
261 * Patterns are based on a simple sequence of letters and symbols.
262 * A pattern is used to create a Formatter using the
263 * {@link #ofPattern(String)} and {@link #ofPattern(String, Locale)} methods.
264 * For example,
265 * {@code "d MMM uuuu"} will format 2011-12-03 as '3 Dec 2011'.
266 * A formatter created from a pattern can be used as many times as necessary,
267 * it is immutable and is thread-safe.
268 * <p>
269 * For example:
270 * <blockquote><pre>
271 * LocalDate date = LocalDate.now();
272 * DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");
273 * String text = date.format(formatter);
274 * LocalDate parsedDate = LocalDate.parse(text, formatter);
275 * </pre></blockquote>
276 * <p>
277 * All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The
278 * following pattern letters are defined:
279 * <pre>
280 * Symbol Meaning Presentation Examples
281 * ------ ------- ------------ -------
282 * G era text AD; Anno Domini; A
283 * u year year 2004; 04
284 * y year-of-era year 2004; 04
285 * D day-of-year number 189
286 * M/L month-of-year number/text 7; 07; Jul; July; J
287 * d day-of-month number 10
288 * g modified-julian-day number 2451334
289 *
290 * Q/q quarter-of-year number/text 3; 03; Q3; 3rd quarter
291 * Y week-based-year year 1996; 96
292 * w week-of-week-based-year number 27
293 * W week-of-month number 4
294 * E day-of-week text Tue; Tuesday; T
295 * e/c localized day-of-week number/text 2; 02; Tue; Tuesday; T
296 * F day-of-week-in-month number 3
297 *
298 * a am-pm-of-day text PM
299 * h clock-hour-of-am-pm (1-12) number 12
300 * K hour-of-am-pm (0-11) number 0
301 * k clock-hour-of-day (1-24) number 24
302 *
303 * H hour-of-day (0-23) number 0
304 * m minute-of-hour number 30
305 * s second-of-minute number 55
306 * S fraction-of-second fraction 978
307 * A milli-of-day number 1234
308 * n nano-of-second number 987654321
309 * N nano-of-day number 1234000000
310 *
311 * V time-zone ID zone-id America/Los_Angeles; Z; -08:30
312 * v generic time-zone name zone-name Pacific Time; PT
313 * z time-zone name zone-name Pacific Standard Time; PST
314 * O localized zone-offset offset-O GMT+8; GMT+08:00; UTC-08:00
315 * X zone-offset 'Z' for zero offset-X Z; -08; -0830; -08:30; -083015; -08:30:15
316 * x zone-offset offset-x +0000; -08; -0830; -08:30; -083015; -08:30:15
317 * Z zone-offset offset-Z +0000; -0800; -08:00
318 *
319 * p pad next pad modifier 1
320 *
321 * ' escape for text delimiter
322 * '' single quote literal '
323 * [ optional section start
324 * ] optional section end
325 * # reserved for future use
326 * { reserved for future use
327 * } reserved for future use
328 * </pre>
329 * <p>
330 * The count of pattern letters determines the format.
331 * <p>
332 * <b>Text</b>: The text style is determined based on the number of pattern
333 * letters used. Less than 4 pattern letters will use the
334 * {@link TextStyle#SHORT short form}. Exactly 4 pattern letters will use the
335 * {@link TextStyle#FULL full form}. Exactly 5 pattern letters will use the
336 * {@link TextStyle#NARROW narrow form}.
337 * Pattern letters 'L', 'c', and 'q' specify the stand-alone form of the text styles.
338 * <p>
339 * <b>Number</b>: If the count of letters is one, then the value is output using
340 * the minimum number of digits and without padding. Otherwise, the count of digits
341 * is used as the width of the output field, with the value zero-padded as necessary.
342 * The following pattern letters have constraints on the count of letters.
343 * Only one letter of 'c' and 'F' can be specified.
344 * Up to two letters of 'd', 'H', 'h', 'K', 'k', 'm', and 's' can be specified.
345 * Up to three letters of 'D' can be specified.
346 * <p>
347 * <b>Number/Text</b>: If the count of pattern letters is 3 or greater, use the
348 * Text rules above. Otherwise use the Number rules above.
349 * <p>
350 * <b>Fraction</b>: Outputs the nano-of-second field as a fraction-of-second.
351 * The nano-of-second value has nine digits, thus the count of pattern letters
352 * is from 1 to 9. If it is less than 9, then the nano-of-second value is
353 * truncated, with only the most significant digits being output.
354 * <p>
355 * <b>Year</b>: The count of letters determines the minimum field width below
356 * which padding is used. If the count of letters is two, then a
357 * {@link DateTimeFormatterBuilder#appendValueReduced reduced} two digit form is
358 * used. For printing, this outputs the rightmost two digits. For parsing, this
359 * will parse using the base value of 2000, resulting in a year within the range
360 * 2000 to 2099 inclusive. If the count of letters is less than four (but not
361 * two), then the sign is only output for negative years as per
362 * {@link SignStyle#NORMAL}. Otherwise, the sign is output if the pad width is
363 * exceeded, as per {@link SignStyle#EXCEEDS_PAD}.
364 * <p>
365 * <b>ZoneId</b>: This outputs the time-zone ID, such as 'Europe/Paris'. If the
366 * count of letters is two, then the time-zone ID is output. Any other count of
367 * letters throws {@code IllegalArgumentException}.
368 * <p>
369 * <b>Zone names</b>: This outputs the display name of the time-zone ID. If the
370 * pattern letter is 'z' the output is the daylight savings aware zone name.
371 * If there is insufficient information to determine whether DST applies,
372 * the name ignoring daylight savings time will be used.
373 * If the count of letters is one, two or three, then the short name is output.
374 * If the count of letters is four, then the full name is output.
375 * Five or more letters throws {@code IllegalArgumentException}.
376 * <p>
377 * If the pattern letter is 'v' the output provides the zone name ignoring
378 * daylight savings time. If the count of letters is one, then the short name is output.
379 * If the count of letters is four, then the full name is output.
380 * Two, three and five or more letters throw {@code IllegalArgumentException}.
381 * <p>
382 * <b>Offset X and x</b>: This formats the offset based on the number of pattern
383 * letters. One letter outputs just the hour, such as '+01', unless the minute
384 * is non-zero in which case the minute is also output, such as '+0130'. Two
385 * letters outputs the hour and minute, without a colon, such as '+0130'. Three
386 * letters outputs the hour and minute, with a colon, such as '+01:30'. Four
387 * letters outputs the hour and minute and optional second, without a colon,
388 * such as '+013015'. Five letters outputs the hour and minute and optional
389 * second, with a colon, such as '+01:30:15'. Six or more letters throws
390 * {@code IllegalArgumentException}. Pattern letter 'X' (upper case) will output
391 * 'Z' when the offset to be output would be zero, whereas pattern letter 'x'
392 * (lower case) will output '+00', '+0000', or '+00:00'.
393 * <p>
394 * <b>Offset O</b>: This formats the localized offset based on the number of
395 * pattern letters. One letter outputs the {@linkplain TextStyle#SHORT short}
396 * form of the localized offset, which is localized offset text, such as 'GMT',
397 * with hour without leading zero, optional 2-digit minute and second if
398 * non-zero, and colon, for example 'GMT+8'. Four letters outputs the
399 * {@linkplain TextStyle#FULL full} form, which is localized offset text,
400 * such as 'GMT, with 2-digit hour and minute field, optional second field
401 * if non-zero, and colon, for example 'GMT+08:00'. Any other count of letters
402 * throws {@code IllegalArgumentException}.
403 * <p>
404 * <b>Offset Z</b>: This formats the offset based on the number of pattern
405 * letters. One, two or three letters outputs the hour and minute, without a
406 * colon, such as '+0130'. The output will be '+0000' when the offset is zero.
407 * Four letters outputs the {@linkplain TextStyle#FULL full} form of localized
408 * offset, equivalent to four letters of Offset-O. The output will be the
409 * corresponding localized offset text if the offset is zero. Five
410 * letters outputs the hour, minute, with optional second if non-zero, with
411 * colon. It outputs 'Z' if the offset is zero.
412 * Six or more letters throws {@code IllegalArgumentException}.
413 * <p>
414 * <b>Optional section</b>: The optional section markers work exactly like
415 * calling {@link DateTimeFormatterBuilder#optionalStart()} and
416 * {@link DateTimeFormatterBuilder#optionalEnd()}.
417 * <p>
418 * <b>Pad modifier</b>: Modifies the pattern that immediately follows to be
419 * padded with spaces. The pad width is determined by the number of pattern
420 * letters. This is the same as calling
421 * {@link DateTimeFormatterBuilder#padNext(int)}.
422 * <p>
423 * For example, 'ppH' outputs the hour-of-day padded on the left with spaces to
424 * a width of 2.
425 * <p>
426 * Any unrecognized letter is an error. Any non-letter character, other than
427 * '[', ']', '{', '}', '#' and the single quote will be output directly.
428 * Despite this, it is recommended to use single quotes around all characters
429 * that you want to output directly to ensure that future changes do not break
430 * your application.
431 *
432 * <h3 id="resolving">Resolving</h3>
433 * Parsing is implemented as a two-phase operation.
434 * First, the text is parsed using the layout defined by the formatter, producing
435 * a {@code Map} of field to value, a {@code ZoneId} and a {@code Chronology}.
436 * Second, the parsed data is <em>resolved</em>, by validating, combining and
437 * simplifying the various fields into more useful ones.
438 * <p>
439 * Five parsing methods are supplied by this class.
440 * Four of these perform both the parse and resolve phases.
441 * The fifth method, {@link #parseUnresolved(CharSequence, ParsePosition)},
442 * only performs the first phase, leaving the result unresolved.
443 * As such, it is essentially a low-level operation.
444 * <p>
445 * The resolve phase is controlled by two parameters, set on this class.
446 * <p>
447 * The {@link ResolverStyle} is an enum that offers three different approaches,
448 * strict, smart and lenient. The smart option is the default.
449 * It can be set using {@link #withResolverStyle(ResolverStyle)}.
450 * <p>
451 * The {@link #withResolverFields(TemporalField...)} parameter allows the
452 * set of fields that will be resolved to be filtered before resolving starts.
453 * For example, if the formatter has parsed a year, month, day-of-month
454 * and day-of-year, then there are two approaches to resolve a date:
455 * (year + month + day-of-month) and (year + day-of-year).
456 * The resolver fields allows one of the two approaches to be selected.
457 * If no resolver fields are set then both approaches must result in the same date.
458 * <p>
459 * Resolving separate fields to form a complete date and time is a complex
460 * process with behaviour distributed across a number of classes.
461 * It follows these steps:
462 * <ol>
463 * <li>The chronology is determined.
464 * The chronology of the result is either the chronology that was parsed,
465 * or if no chronology was parsed, it is the chronology set on this class,
466 * or if that is null, it is {@code IsoChronology}.
467 * <li>The {@code ChronoField} date fields are resolved.
468 * This is achieved using {@link Chronology#resolveDate(Map, ResolverStyle)}.
469 * Documentation about field resolution is located in the implementation
470 * of {@code Chronology}.
471 * <li>The {@code ChronoField} time fields are resolved.
472 * This is documented on {@link ChronoField} and is the same for all chronologies.
473 * <li>Any fields that are not {@code ChronoField} are processed.
474 * This is achieved using {@link TemporalField#resolve(Map, TemporalAccessor, ResolverStyle)}.
475 * Documentation about field resolution is located in the implementation
476 * of {@code TemporalField}.
477 * <li>The {@code ChronoField} date and time fields are re-resolved.
478 * This allows fields in step four to produce {@code ChronoField} values
479 * and have them be processed into dates and times.
480 * <li>A {@code LocalTime} is formed if there is at least an hour-of-day available.
481 * This involves providing default values for minute, second and fraction of second.
482 * <li>Any remaining unresolved fields are cross-checked against any
483 * date and/or time that was resolved. Thus, an earlier stage would resolve
484 * (year + month + day-of-month) to a date, and this stage would check that
485 * day-of-week was valid for the date.
486 * <li>If an {@linkplain #parsedExcessDays() excess number of days}
487 * was parsed then it is added to the date if a date is available.
488 * <li> If a second-based field is present, but {@code LocalTime} was not parsed,
489 * then the resolver ensures that milli, micro and nano second values are
490 * available to meet the contract of {@link ChronoField}.
491 * These will be set to zero if missing.
492 * <li>If both date and time were parsed and either an offset or zone is present,
493 * the field {@link ChronoField#INSTANT_SECONDS} is created.
494 * If an offset was parsed then the offset will be combined with the
495 * {@code LocalDateTime} to form the instant, with any zone ignored.
496 * If a {@code ZoneId} was parsed without an offset then the zone will be
497 * combined with the {@code LocalDateTime} to form the instant using the rules
498 * of {@link ChronoLocalDateTime#atZone(ZoneId)}.
499 * </ol>
500 *
501 * @implSpec
502 * This class is immutable and thread-safe.
503 *
504 * @since 1.8
505 */
506 public final class DateTimeFormatter {
507
508 /**
509 * The printer and/or parser to use, not null.
510 */
511 private final CompositePrinterParser printerParser;
512 /**
513 * The locale to use for formatting, not null.
514 */
515 private final Locale locale;
516 /**
517 * The symbols to use for formatting, not null.
518 */
519 private final DecimalStyle decimalStyle;
520 /**
521 * The resolver style to use, not null.
522 */
523 private final ResolverStyle resolverStyle;
524 /**
525 * The fields to use in resolving, null for all fields.
526 */
527 private final Set<TemporalField> resolverFields;
528 /**
529 * The chronology to use for formatting, null for no override.
530 */
531 private final Chronology chrono;
532 /**
533 * The zone to use for formatting, null for no override.
534 */
535 private final ZoneId zone;
536
537 //-----------------------------------------------------------------------
538 /**
539 * Creates a formatter using the specified pattern.
540 * <p>
541 * This method will create a formatter based on a simple
542 * <a href="#patterns">pattern of letters and symbols</a>
543 * as described in the class documentation.
544 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
545 * <p>
546 * The formatter will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
547 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter
548 * Alternatively use the {@link #ofPattern(String, Locale)} variant of this method.
549 * <p>
550 * The returned formatter has no override chronology or zone.
551 * It uses {@link ResolverStyle#SMART SMART} resolver style.
552 *
553 * @param pattern the pattern to use, not null
554 * @return the formatter based on the pattern, not null
555 * @throws IllegalArgumentException if the pattern is invalid
556 * @see DateTimeFormatterBuilder#appendPattern(String)
557 */
558 public static DateTimeFormatter ofPattern(String pattern) {
559 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter();
560 }
561
562 /**
563 * Creates a formatter using the specified pattern and locale.
564 * <p>
565 * This method will create a formatter based on a simple
566 * <a href="#patterns">pattern of letters and symbols</a>
567 * as described in the class documentation.
568 * For example, {@code d MMM uuuu} will format 2011-12-03 as '3 Dec 2011'.
569 * <p>
570 * The formatter will use the specified locale.
571 * This can be changed using {@link DateTimeFormatter#withLocale(Locale)} on the returned formatter
572 * <p>
573 * The returned formatter has no override chronology or zone.
574 * It uses {@link ResolverStyle#SMART SMART} resolver style.
575 *
576 * @param pattern the pattern to use, not null
577 * @param locale the locale to use, not null
578 * @return the formatter based on the pattern, not null
579 * @throws IllegalArgumentException if the pattern is invalid
580 * @see DateTimeFormatterBuilder#appendPattern(String)
581 */
582 public static DateTimeFormatter ofPattern(String pattern, Locale locale) {
583 return new DateTimeFormatterBuilder().appendPattern(pattern).toFormatter(locale);
584 }
585
586 //-----------------------------------------------------------------------
587 /**
588 * Returns a locale specific date format for the ISO chronology.
589 * <p>
590 * This returns a formatter that will format or parse a date.
591 * The exact format pattern used varies by locale.
592 * <p>
593 * The locale is determined from the formatter. The formatter returned directly by
594 * this method will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
595 * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)}
596 * on the result of this method.
597 * <p>
598 * Note that the localized pattern is looked up lazily.
599 * This {@code DateTimeFormatter} holds the style required and the locale,
600 * looking up the pattern required on demand.
601 * <p>
602 * The returned formatter has a chronology of ISO set to ensure dates in
603 * other calendar systems are correctly converted.
604 * It has no override zone and uses the {@link ResolverStyle#SMART SMART} resolver style.
605 *
606 * @param dateStyle the formatter style to obtain, not null
607 * @return the date formatter, not null
608 */
609 public static DateTimeFormatter ofLocalizedDate(FormatStyle dateStyle) {
610 Objects.requireNonNull(dateStyle, "dateStyle");
611 return new DateTimeFormatterBuilder().appendLocalized(dateStyle, null)
612 .toFormatter(ResolverStyle.SMART, IsoChronology.INSTANCE);
613 }
614
615 /**
616 * Returns a locale specific time format for the ISO chronology.
617 * <p>
618 * This returns a formatter that will format or parse a time.
619 * The exact format pattern used varies by locale.
620 * <p>
621 * The locale is determined from the formatter. The formatter returned directly by
622 * this method will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
623 * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)}
624 * on the result of this method.
625 * <p>
626 * Note that the localized pattern is looked up lazily.
627 * This {@code DateTimeFormatter} holds the style required and the locale,
628 * looking up the pattern required on demand.
629 * <p>
630 * The returned formatter has a chronology of ISO set to ensure dates in
631 * other calendar systems are correctly converted.
632 * It has no override zone and uses the {@link ResolverStyle#SMART SMART} resolver style.
633 * The {@code FULL} and {@code LONG} styles typically require a time-zone.
634 * When formatting using these styles, a {@code ZoneId} must be available,
635 * either by using {@code ZonedDateTime} or {@link DateTimeFormatter#withZone}.
636 *
637 * @param timeStyle the formatter style to obtain, not null
638 * @return the time formatter, not null
639 */
640 public static DateTimeFormatter ofLocalizedTime(FormatStyle timeStyle) {
641 Objects.requireNonNull(timeStyle, "timeStyle");
642 return new DateTimeFormatterBuilder().appendLocalized(null, timeStyle)
643 .toFormatter(ResolverStyle.SMART, IsoChronology.INSTANCE);
644 }
645
646 /**
647 * Returns a locale specific date-time formatter for the ISO chronology.
648 * <p>
649 * This returns a formatter that will format or parse a date-time.
650 * The exact format pattern used varies by locale.
651 * <p>
652 * The locale is determined from the formatter. The formatter returned directly by
653 * this method will use the {@link Locale#getDefault(Locale.Category) default FORMAT locale}.
654 * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)}
655 * on the result of this method.
656 * <p>
657 * Note that the localized pattern is looked up lazily.
658 * This {@code DateTimeFormatter} holds the style required and the locale,
659 * looking up the pattern required on demand.
660 * <p>
661 * The returned formatter has a chronology of ISO set to ensure dates in
662 * other calendar systems are correctly converted.
663 * It has no override zone and uses the {@link ResolverStyle#SMART SMART} resolver style.
664 * The {@code FULL} and {@code LONG} styles typically require a time-zone.
665 * When formatting using these styles, a {@code ZoneId} must be available,
666 * either by using {@code ZonedDateTime} or {@link DateTimeFormatter#withZone}.
667 *
668 * @param dateTimeStyle the formatter style to obtain, not null
669 * @return the date-time formatter, not null
670 */
671 public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateTimeStyle) {
672 Objects.requireNonNull(dateTimeStyle, "dateTimeStyle");
673 return new DateTimeFormatterBuilder().appendLocalized(dateTimeStyle, dateTimeStyle)
674 .toFormatter(ResolverStyle.SMART, IsoChronology.INSTANCE);
675 }
676
677 /**
678 * Returns a locale specific date and time format for the ISO chronology.
679 * <p>
680 * This returns a formatter that will format or parse a date-time.
681 * The exact format pattern used varies by locale.
682 * <p>
683 * The locale is determined from the formatter. The formatter returned directly by
684 * this method will use the {@link Locale#getDefault() default FORMAT locale}.
685 * The locale can be controlled using {@link DateTimeFormatter#withLocale(Locale) withLocale(Locale)}
686 * on the result of this method.
687 * <p>
688 * Note that the localized pattern is looked up lazily.
689 * This {@code DateTimeFormatter} holds the style required and the locale,
690 * looking up the pattern required on demand.
691 * <p>
692 * The returned formatter has a chronology of ISO set to ensure dates in
693 * other calendar systems are correctly converted.
694 * It has no override zone and uses the {@link ResolverStyle#SMART SMART} resolver style.
695 * The {@code FULL} and {@code LONG} styles typically require a time-zone.
696 * When formatting using these styles, a {@code ZoneId} must be available,
697 * either by using {@code ZonedDateTime} or {@link DateTimeFormatter#withZone}.
698 *
699 * @param dateStyle the date formatter style to obtain, not null
700 * @param timeStyle the time formatter style to obtain, not null
701 * @return the date, time or date-time formatter, not null
702 */
703 public static DateTimeFormatter ofLocalizedDateTime(FormatStyle dateStyle, FormatStyle timeStyle) {
704 Objects.requireNonNull(dateStyle, "dateStyle");
705 Objects.requireNonNull(timeStyle, "timeStyle");
706 return new DateTimeFormatterBuilder().appendLocalized(dateStyle, timeStyle)
707 .toFormatter(ResolverStyle.SMART, IsoChronology.INSTANCE);
708 }
709
710 //-----------------------------------------------------------------------
711 /**
712 * The ISO date formatter that formats or parses a date without an
713 * offset, such as '2011-12-03'.
714 * <p>
715 * This returns an immutable formatter capable of formatting and parsing
716 * the ISO-8601 extended local date format.
717 * The format consists of:
718 * <ul>
719 * <li>Four digits or more for the {@link ChronoField#YEAR year}.
720 * Years in the range 0000 to 9999 will be pre-padded by zero to ensure four digits.
721 * Years outside that range will have a prefixed positive or negative symbol.
722 * <li>A dash
723 * <li>Two digits for the {@link ChronoField#MONTH_OF_YEAR month-of-year}.
724 * This is pre-padded by zero to ensure two digits.
725 * <li>A dash
726 * <li>Two digits for the {@link ChronoField#DAY_OF_MONTH day-of-month}.
727 * This is pre-padded by zero to ensure two digits.
728 * </ul>
729 * <p>
730 * The returned formatter has a chronology of ISO set to ensure dates in
731 * other calendar systems are correctly converted.
732 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
733 */
734 public static final DateTimeFormatter ISO_LOCAL_DATE;
735 static {
736 ISO_LOCAL_DATE = new DateTimeFormatterBuilder()
737 .appendValue(YEAR, 4, 10, SignStyle.EXCEEDS_PAD)
738 .appendLiteral('-')
739 .appendValue(MONTH_OF_YEAR, 2)
740 .appendLiteral('-')
741 .appendValue(DAY_OF_MONTH, 2)
742 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
743 }
744
745 //-----------------------------------------------------------------------
746 /**
747 * The ISO date formatter that formats or parses a date with an
748 * offset, such as '2011-12-03+01:00'.
749 * <p>
750 * This returns an immutable formatter capable of formatting and parsing
751 * the ISO-8601 extended offset date format.
752 * The format consists of:
753 * <ul>
754 * <li>The {@link #ISO_LOCAL_DATE}
755 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
756 * they will be handled even though this is not part of the ISO-8601 standard.
757 * Parsing is case insensitive.
758 * </ul>
759 * <p>
760 * The returned formatter has a chronology of ISO set to ensure dates in
761 * other calendar systems are correctly converted.
762 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
763 */
764 public static final DateTimeFormatter ISO_OFFSET_DATE;
765 static {
766 ISO_OFFSET_DATE = new DateTimeFormatterBuilder()
767 .parseCaseInsensitive()
768 .append(ISO_LOCAL_DATE)
769 .appendOffsetId()
770 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
771 }
772
773 //-----------------------------------------------------------------------
774 /**
775 * The ISO date formatter that formats or parses a date with the
776 * offset if available, such as '2011-12-03' or '2011-12-03+01:00'.
777 * <p>
778 * This returns an immutable formatter capable of formatting and parsing
779 * the ISO-8601 extended date format.
780 * The format consists of:
781 * <ul>
782 * <li>The {@link #ISO_LOCAL_DATE}
783 * <li>If the offset is not available then the format is complete.
784 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
785 * they will be handled even though this is not part of the ISO-8601 standard.
786 * Parsing is case insensitive.
787 * </ul>
788 * <p>
789 * As this formatter has an optional element, it may be necessary to parse using
790 * {@link DateTimeFormatter#parseBest}.
791 * <p>
792 * The returned formatter has a chronology of ISO set to ensure dates in
793 * other calendar systems are correctly converted.
794 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
795 */
796 public static final DateTimeFormatter ISO_DATE;
797 static {
798 ISO_DATE = new DateTimeFormatterBuilder()
799 .parseCaseInsensitive()
800 .append(ISO_LOCAL_DATE)
801 .optionalStart()
802 .appendOffsetId()
803 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
804 }
805
806 //-----------------------------------------------------------------------
807 /**
808 * The ISO time formatter that formats or parses a time without an
809 * offset, such as '10:15' or '10:15:30'.
810 * <p>
811 * This returns an immutable formatter capable of formatting and parsing
812 * the ISO-8601 extended local time format.
813 * The format consists of:
814 * <ul>
815 * <li>Two digits for the {@link ChronoField#HOUR_OF_DAY hour-of-day}.
816 * This is pre-padded by zero to ensure two digits.
817 * <li>A colon
818 * <li>Two digits for the {@link ChronoField#MINUTE_OF_HOUR minute-of-hour}.
819 * This is pre-padded by zero to ensure two digits.
820 * <li>If the second-of-minute is not available then the format is complete.
821 * <li>A colon
822 * <li>Two digits for the {@link ChronoField#SECOND_OF_MINUTE second-of-minute}.
823 * This is pre-padded by zero to ensure two digits.
824 * <li>If the nano-of-second is zero or not available then the format is complete.
825 * <li>A decimal point
826 * <li>One to nine digits for the {@link ChronoField#NANO_OF_SECOND nano-of-second}.
827 * As many digits will be output as required.
828 * </ul>
829 * <p>
830 * The returned formatter has no override chronology or zone.
831 * It uses the {@link ResolverStyle#STRICT STRICT} resolver style.
832 */
833 public static final DateTimeFormatter ISO_LOCAL_TIME;
834 static {
835 ISO_LOCAL_TIME = new DateTimeFormatterBuilder()
836 .appendValue(HOUR_OF_DAY, 2)
837 .appendLiteral(':')
838 .appendValue(MINUTE_OF_HOUR, 2)
839 .optionalStart()
840 .appendLiteral(':')
841 .appendValue(SECOND_OF_MINUTE, 2)
842 .optionalStart()
843 .appendFraction(NANO_OF_SECOND, 0, 9, true)
844 .toFormatter(ResolverStyle.STRICT, null);
845 }
846
847 //-----------------------------------------------------------------------
848 /**
849 * The ISO time formatter that formats or parses a time with an
850 * offset, such as '10:15+01:00' or '10:15:30+01:00'.
851 * <p>
852 * This returns an immutable formatter capable of formatting and parsing
853 * the ISO-8601 extended offset time format.
854 * The format consists of:
855 * <ul>
856 * <li>The {@link #ISO_LOCAL_TIME}
857 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
858 * they will be handled even though this is not part of the ISO-8601 standard.
859 * Parsing is case insensitive.
860 * </ul>
861 * <p>
862 * The returned formatter has no override chronology or zone.
863 * It uses the {@link ResolverStyle#STRICT STRICT} resolver style.
864 */
865 public static final DateTimeFormatter ISO_OFFSET_TIME;
866 static {
867 ISO_OFFSET_TIME = new DateTimeFormatterBuilder()
868 .parseCaseInsensitive()
869 .append(ISO_LOCAL_TIME)
870 .appendOffsetId()
871 .toFormatter(ResolverStyle.STRICT, null);
872 }
873
874 //-----------------------------------------------------------------------
875 /**
876 * The ISO time formatter that formats or parses a time, with the
877 * offset if available, such as '10:15', '10:15:30' or '10:15:30+01:00'.
878 * <p>
879 * This returns an immutable formatter capable of formatting and parsing
880 * the ISO-8601 extended offset time format.
881 * The format consists of:
882 * <ul>
883 * <li>The {@link #ISO_LOCAL_TIME}
884 * <li>If the offset is not available then the format is complete.
885 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
886 * they will be handled even though this is not part of the ISO-8601 standard.
887 * Parsing is case insensitive.
888 * </ul>
889 * <p>
890 * As this formatter has an optional element, it may be necessary to parse using
891 * {@link DateTimeFormatter#parseBest}.
892 * <p>
893 * The returned formatter has no override chronology or zone.
894 * It uses the {@link ResolverStyle#STRICT STRICT} resolver style.
895 */
896 public static final DateTimeFormatter ISO_TIME;
897 static {
898 ISO_TIME = new DateTimeFormatterBuilder()
899 .parseCaseInsensitive()
900 .append(ISO_LOCAL_TIME)
901 .optionalStart()
902 .appendOffsetId()
903 .toFormatter(ResolverStyle.STRICT, null);
904 }
905
906 //-----------------------------------------------------------------------
907 /**
908 * The ISO date-time formatter that formats or parses a date-time without
909 * an offset, such as '2011-12-03T10:15:30'.
910 * <p>
911 * This returns an immutable formatter capable of formatting and parsing
912 * the ISO-8601 extended offset date-time format.
913 * The format consists of:
914 * <ul>
915 * <li>The {@link #ISO_LOCAL_DATE}
916 * <li>The letter 'T'. Parsing is case insensitive.
917 * <li>The {@link #ISO_LOCAL_TIME}
918 * </ul>
919 * <p>
920 * The returned formatter has a chronology of ISO set to ensure dates in
921 * other calendar systems are correctly converted.
922 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
923 */
924 public static final DateTimeFormatter ISO_LOCAL_DATE_TIME;
925 static {
926 ISO_LOCAL_DATE_TIME = new DateTimeFormatterBuilder()
927 .parseCaseInsensitive()
928 .append(ISO_LOCAL_DATE)
929 .appendLiteral('T')
930 .append(ISO_LOCAL_TIME)
931 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
932 }
933
934 //-----------------------------------------------------------------------
935 /**
936 * The ISO date-time formatter that formats or parses a date-time with an
937 * offset, such as '2011-12-03T10:15:30+01:00'.
938 * <p>
939 * This returns an immutable formatter capable of formatting and parsing
940 * the ISO-8601 extended offset date-time format.
941 * The format consists of:
942 * <ul>
943 * <li>The {@link #ISO_LOCAL_DATE_TIME}
944 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
945 * they will be handled even though this is not part of the ISO-8601 standard.
946 * The offset parsing is lenient, which allows the minutes and seconds to be optional.
947 * Parsing is case insensitive.
948 * </ul>
949 * <p>
950 * The returned formatter has a chronology of ISO set to ensure dates in
951 * other calendar systems are correctly converted.
952 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
953 */
954 public static final DateTimeFormatter ISO_OFFSET_DATE_TIME;
955 static {
956 ISO_OFFSET_DATE_TIME = new DateTimeFormatterBuilder()
957 .parseCaseInsensitive()
958 .append(ISO_LOCAL_DATE_TIME)
959 .parseLenient()
960 .appendOffsetId()
961 .parseStrict()
962 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
963 }
964
965 //-----------------------------------------------------------------------
966 /**
967 * The ISO-like date-time formatter that formats or parses a date-time with
968 * offset and zone, such as '2011-12-03T10:15:30+01:00[Europe/Paris]'.
969 * <p>
970 * This returns an immutable formatter capable of formatting and parsing
971 * a format that extends the ISO-8601 extended offset date-time format
972 * to add the time-zone.
973 * The section in square brackets is not part of the ISO-8601 standard.
974 * The format consists of:
975 * <ul>
976 * <li>The {@link #ISO_OFFSET_DATE_TIME}
977 * <li>If the zone ID is not available or is a {@code ZoneOffset} then the format is complete.
978 * <li>An open square bracket '['.
979 * <li>The {@link ZoneId#getId() zone ID}. This is not part of the ISO-8601 standard.
980 * Parsing is case sensitive.
981 * <li>A close square bracket ']'.
982 * </ul>
983 * <p>
984 * The returned formatter has a chronology of ISO set to ensure dates in
985 * other calendar systems are correctly converted.
986 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
987 */
988 public static final DateTimeFormatter ISO_ZONED_DATE_TIME;
989 static {
990 ISO_ZONED_DATE_TIME = new DateTimeFormatterBuilder()
991 .append(ISO_OFFSET_DATE_TIME)
992 .optionalStart()
993 .appendLiteral('[')
994 .parseCaseSensitive()
995 .appendZoneRegionId()
996 .appendLiteral(']')
997 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
998 }
999
1000 //-----------------------------------------------------------------------
1001 /**
1002 * The ISO-like date-time formatter that formats or parses a date-time with
1003 * the offset and zone if available, such as '2011-12-03T10:15:30',
1004 * '2011-12-03T10:15:30+01:00' or '2011-12-03T10:15:30+01:00[Europe/Paris]'.
1005 * <p>
1006 * This returns an immutable formatter capable of formatting and parsing
1007 * the ISO-8601 extended local or offset date-time format, as well as the
1008 * extended non-ISO form specifying the time-zone.
1009 * The format consists of:
1010 * <ul>
1011 * <li>The {@link #ISO_LOCAL_DATE_TIME}
1012 * <li>If the offset is not available to format or parse then the format is complete.
1013 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
1014 * they will be handled even though this is not part of the ISO-8601 standard.
1015 * <li>If the zone ID is not available or is a {@code ZoneOffset} then the format is complete.
1016 * <li>An open square bracket '['.
1017 * <li>The {@link ZoneId#getId() zone ID}. This is not part of the ISO-8601 standard.
1018 * Parsing is case sensitive.
1019 * <li>A close square bracket ']'.
1020 * </ul>
1021 * <p>
1022 * As this formatter has an optional element, it may be necessary to parse using
1023 * {@link DateTimeFormatter#parseBest}.
1024 * <p>
1025 * The returned formatter has a chronology of ISO set to ensure dates in
1026 * other calendar systems are correctly converted.
1027 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
1028 */
1029 public static final DateTimeFormatter ISO_DATE_TIME;
1030 static {
1031 ISO_DATE_TIME = new DateTimeFormatterBuilder()
1032 .append(ISO_LOCAL_DATE_TIME)
1033 .optionalStart()
1034 .appendOffsetId()
1035 .optionalStart()
1036 .appendLiteral('[')
1037 .parseCaseSensitive()
1038 .appendZoneRegionId()
1039 .appendLiteral(']')
1040 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
1041 }
1042
1043 //-----------------------------------------------------------------------
1044 /**
1045 * The ISO date formatter that formats or parses the ordinal date
1046 * without an offset, such as '2012-337'.
1047 * <p>
1048 * This returns an immutable formatter capable of formatting and parsing
1049 * the ISO-8601 extended ordinal date format.
1050 * The format consists of:
1051 * <ul>
1052 * <li>Four digits or more for the {@link ChronoField#YEAR year}.
1053 * Years in the range 0000 to 9999 will be pre-padded by zero to ensure four digits.
1054 * Years outside that range will have a prefixed positive or negative symbol.
1055 * <li>A dash
1056 * <li>Three digits for the {@link ChronoField#DAY_OF_YEAR day-of-year}.
1057 * This is pre-padded by zero to ensure three digits.
1058 * <li>If the offset is not available to format or parse then the format is complete.
1059 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
1060 * they will be handled even though this is not part of the ISO-8601 standard.
1061 * Parsing is case insensitive.
1062 * </ul>
1063 * <p>
1064 * As this formatter has an optional element, it may be necessary to parse using
1065 * {@link DateTimeFormatter#parseBest}.
1066 * <p>
1067 * The returned formatter has a chronology of ISO set to ensure dates in
1068 * other calendar systems are correctly converted.
1069 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
1070 */
1071 public static final DateTimeFormatter ISO_ORDINAL_DATE;
1072 static {
1073 ISO_ORDINAL_DATE = new DateTimeFormatterBuilder()
1074 .parseCaseInsensitive()
1075 .appendValue(YEAR, 4, 10, SignStyle.EXCEEDS_PAD)
1076 .appendLiteral('-')
1077 .appendValue(DAY_OF_YEAR, 3)
1078 .optionalStart()
1079 .appendOffsetId()
1080 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
1081 }
1082
1083 //-----------------------------------------------------------------------
1084 /**
1085 * The ISO date formatter that formats or parses the week-based date
1086 * without an offset, such as '2012-W48-6'.
1087 * <p>
1088 * This returns an immutable formatter capable of formatting and parsing
1089 * the ISO-8601 extended week-based date format.
1090 * The format consists of:
1091 * <ul>
1092 * <li>Four digits or more for the {@link IsoFields#WEEK_BASED_YEAR week-based-year}.
1093 * Years in the range 0000 to 9999 will be pre-padded by zero to ensure four digits.
1094 * Years outside that range will have a prefixed positive or negative symbol.
1095 * <li>A dash
1096 * <li>The letter 'W'. Parsing is case insensitive.
1097 * <li>Two digits for the {@link IsoFields#WEEK_OF_WEEK_BASED_YEAR week-of-week-based-year}.
1098 * This is pre-padded by zero to ensure three digits.
1099 * <li>A dash
1100 * <li>One digit for the {@link ChronoField#DAY_OF_WEEK day-of-week}.
1101 * The value run from Monday (1) to Sunday (7).
1102 * <li>If the offset is not available to format or parse then the format is complete.
1103 * <li>The {@link ZoneOffset#getId() offset ID}. If the offset has seconds then
1104 * they will be handled even though this is not part of the ISO-8601 standard.
1105 * Parsing is case insensitive.
1106 * </ul>
1107 * <p>
1108 * As this formatter has an optional element, it may be necessary to parse using
1109 * {@link DateTimeFormatter#parseBest}.
1110 * <p>
1111 * The returned formatter has a chronology of ISO set to ensure dates in
1112 * other calendar systems are correctly converted.
1113 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
1114 */
1115 public static final DateTimeFormatter ISO_WEEK_DATE;
1116 static {
1117 ISO_WEEK_DATE = new DateTimeFormatterBuilder()
1118 .parseCaseInsensitive()
1119 .appendValue(IsoFields.WEEK_BASED_YEAR, 4, 10, SignStyle.EXCEEDS_PAD)
1120 .appendLiteral("-W")
1121 .appendValue(IsoFields.WEEK_OF_WEEK_BASED_YEAR, 2)
1122 .appendLiteral('-')
1123 .appendValue(DAY_OF_WEEK, 1)
1124 .optionalStart()
1125 .appendOffsetId()
1126 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
1127 }
1128
1129 //-----------------------------------------------------------------------
1130 /**
1131 * The ISO instant formatter that formats or parses an instant in UTC,
1132 * such as '2011-12-03T10:15:30Z'.
1133 * <p>
1134 * This returns an immutable formatter capable of formatting and parsing
1135 * the ISO-8601 instant format.
1136 * When formatting, the second-of-minute is always output.
1137 * The nano-of-second outputs zero, three, six or nine digits as necessary.
1138 * When parsing, time to at least the seconds field is required.
1139 * Fractional seconds from zero to nine are parsed.
1140 * The localized decimal style is not used.
1141 * <p>
1142 * This is a special case formatter intended to allow a human readable form
1143 * of an {@link java.time.Instant}. The {@code Instant} class is designed to
1144 * only represent a point in time and internally stores a value in nanoseconds
1145 * from a fixed epoch of 1970-01-01Z. As such, an {@code Instant} cannot be
1146 * formatted as a date or time without providing some form of time-zone.
1147 * This formatter allows the {@code Instant} to be formatted, by providing
1148 * a suitable conversion using {@code ZoneOffset.UTC}.
1149 * <p>
1150 * The format consists of:
1151 * <ul>
1152 * <li>The {@link #ISO_OFFSET_DATE_TIME} where the instant is converted from
1153 * {@link ChronoField#INSTANT_SECONDS} and {@link ChronoField#NANO_OF_SECOND}
1154 * using the {@code UTC} offset. Parsing is case insensitive.
1155 * </ul>
1156 * <p>
1157 * The returned formatter has no override chronology or zone.
1158 * It uses the {@link ResolverStyle#STRICT STRICT} resolver style.
1159 */
1160 public static final DateTimeFormatter ISO_INSTANT;
1161 static {
1162 ISO_INSTANT = new DateTimeFormatterBuilder()
1163 .parseCaseInsensitive()
1164 .appendInstant()
1165 .toFormatter(ResolverStyle.STRICT, null);
1166 }
1167
1168 //-----------------------------------------------------------------------
1169 /**
1170 * The ISO date formatter that formats or parses a date without an
1171 * offset, such as '20111203'.
1172 * <p>
1173 * This returns an immutable formatter capable of formatting and parsing
1174 * the ISO-8601 basic local date format.
1175 * The format consists of:
1176 * <ul>
1177 * <li>Four digits for the {@link ChronoField#YEAR year}.
1178 * Only years in the range 0000 to 9999 are supported.
1179 * <li>Two digits for the {@link ChronoField#MONTH_OF_YEAR month-of-year}.
1180 * This is pre-padded by zero to ensure two digits.
1181 * <li>Two digits for the {@link ChronoField#DAY_OF_MONTH day-of-month}.
1182 * This is pre-padded by zero to ensure two digits.
1183 * <li>If the offset is not available to format or parse then the format is complete.
1184 * <li>The {@link ZoneOffset#getId() offset ID} without colons. If the offset has
1185 * seconds then they will be handled even though this is not part of the ISO-8601 standard.
1186 * The offset parsing is lenient, which allows the minutes and seconds to be optional.
1187 * Parsing is case insensitive.
1188 * </ul>
1189 * <p>
1190 * As this formatter has an optional element, it may be necessary to parse using
1191 * {@link DateTimeFormatter#parseBest}.
1192 * <p>
1193 * The returned formatter has a chronology of ISO set to ensure dates in
1194 * other calendar systems are correctly converted.
1195 * It has no override zone and uses the {@link ResolverStyle#STRICT STRICT} resolver style.
1196 */
1197 public static final DateTimeFormatter BASIC_ISO_DATE;
1198 static {
1199 BASIC_ISO_DATE = new DateTimeFormatterBuilder()
1200 .parseCaseInsensitive()
1201 .appendValue(YEAR, 4)
1202 .appendValue(MONTH_OF_YEAR, 2)
1203 .appendValue(DAY_OF_MONTH, 2)
1204 .optionalStart()
1205 .parseLenient()
1206 .appendOffset("+HHMMss", "Z")
1207 .parseStrict()
1208 .toFormatter(ResolverStyle.STRICT, IsoChronology.INSTANCE);
1209 }
1210
1211 //-----------------------------------------------------------------------
1212 /**
1213 * The RFC-1123 date-time formatter, such as 'Tue, 3 Jun 2008 11:05:30 GMT'.
1214 * <p>
1215 * This returns an immutable formatter capable of formatting and parsing
1216 * most of the RFC-1123 format.
1217 * RFC-1123 updates RFC-822 changing the year from two digits to four.
1218 * This implementation requires a four digit year.
1219 * This implementation also does not handle North American or military zone
1220 * names, only 'GMT' and offset amounts.
1221 * <p>
1222 * The format consists of:
1223 * <ul>
1224 * <li>If the day-of-week is not available to format or parse then jump to day-of-month.
1225 * <li>Three letter {@link ChronoField#DAY_OF_WEEK day-of-week} in English.
1226 * <li>A comma
1227 * <li>A space
1228 * <li>One or two digits for the {@link ChronoField#DAY_OF_MONTH day-of-month}.
1229 * <li>A space
1230 * <li>Three letter {@link ChronoField#MONTH_OF_YEAR month-of-year} in English.
1231 * <li>A space
1232 * <li>Four digits for the {@link ChronoField#YEAR year}.
1233 * Only years in the range 0000 to 9999 are supported.
1234 * <li>A space
1235 * <li>Two digits for the {@link ChronoField#HOUR_OF_DAY hour-of-day}.
1236 * This is pre-padded by zero to ensure two digits.
1237 * <li>A colon
1238 * <li>Two digits for the {@link ChronoField#MINUTE_OF_HOUR minute-of-hour}.
1239 * This is pre-padded by zero to ensure two digits.
1240 * <li>If the second-of-minute is not available then jump to the next space.
1241 * <li>A colon
1242 * <li>Two digits for the {@link ChronoField#SECOND_OF_MINUTE second-of-minute}.
1243 * This is pre-padded by zero to ensure two digits.
1244 * <li>A space
1245 * <li>The {@link ZoneOffset#getId() offset ID} without colons or seconds.
1246 * An offset of zero uses "GMT". North American zone names and military zone names are not handled.
1247 * </ul>
1248 * <p>
1249 * Parsing is case insensitive.
1250 * <p>
1251 * The returned formatter has a chronology of ISO set to ensure dates in
1252 * other calendar systems are correctly converted.
1253 * It has no override zone and uses the {@link ResolverStyle#SMART SMART} resolver style.
1254 */
1255 public static final DateTimeFormatter RFC_1123_DATE_TIME;
1256 static {
1257 // manually code maps to ensure correct data always used
1258 // (locale data can be changed by application code)
1259 Map<Long, String> dow = new HashMap<>();
1260 dow.put(1L, "Mon");
1261 dow.put(2L, "Tue");
1262 dow.put(3L, "Wed");
1263 dow.put(4L, "Thu");
1264 dow.put(5L, "Fri");
1265 dow.put(6L, "Sat");
1266 dow.put(7L, "Sun");
1267 Map<Long, String> moy = new HashMap<>();
1268 moy.put(1L, "Jan");
1269 moy.put(2L, "Feb");
1270 moy.put(3L, "Mar");
1271 moy.put(4L, "Apr");
1272 moy.put(5L, "May");
1273 moy.put(6L, "Jun");
1274 moy.put(7L, "Jul");
1275 moy.put(8L, "Aug");
1276 moy.put(9L, "Sep");
1277 moy.put(10L, "Oct");
1278 moy.put(11L, "Nov");
1279 moy.put(12L, "Dec");
1280 RFC_1123_DATE_TIME = new DateTimeFormatterBuilder()
1281 .parseCaseInsensitive()
1282 .parseLenient()
1283 .optionalStart()
1284 .appendText(DAY_OF_WEEK, dow)
1285 .appendLiteral(", ")
1286 .optionalEnd()
1287 .appendValue(DAY_OF_MONTH, 1, 2, SignStyle.NOT_NEGATIVE)
1288 .appendLiteral(' ')
1289 .appendText(MONTH_OF_YEAR, moy)
1290 .appendLiteral(' ')
1291 .appendValue(YEAR, 4) // 2 digit year not handled
1292 .appendLiteral(' ')
1293 .appendValue(HOUR_OF_DAY, 2)
1294 .appendLiteral(':')
1295 .appendValue(MINUTE_OF_HOUR, 2)
1296 .optionalStart()
1297 .appendLiteral(':')
1298 .appendValue(SECOND_OF_MINUTE, 2)
1299 .optionalEnd()
1300 .appendLiteral(' ')
1301 .appendOffset("+HHMM", "GMT") // should handle UT/Z/EST/EDT/CST/CDT/MST/MDT/PST/MDT
1302 .toFormatter(ResolverStyle.SMART, IsoChronology.INSTANCE);
1303 }
1304
1305 //-----------------------------------------------------------------------
1306 /**
1307 * A query that provides access to the excess days that were parsed.
1308 * <p>
1309 * This returns a singleton {@linkplain TemporalQuery query} that provides
1310 * access to additional information from the parse. The query always returns
1311 * a non-null period, with a zero period returned instead of null.
1312 * <p>
1313 * There are two situations where this query may return a non-zero period.
1314 * <ul>
1315 * <li>If the {@code ResolverStyle} is {@code LENIENT} and a time is parsed
1316 * without a date, then the complete result of the parse consists of a
1317 * {@code LocalTime} and an excess {@code Period} in days.
1318 *
1319 * <li>If the {@code ResolverStyle} is {@code SMART} and a time is parsed
1320 * without a date where the time is 24:00:00, then the complete result of
1321 * the parse consists of a {@code LocalTime} of 00:00:00 and an excess
1322 * {@code Period} of one day.
1323 * </ul>
1324 * <p>
1325 * In both cases, if a complete {@code ChronoLocalDateTime} or {@code Instant}
1326 * is parsed, then the excess days are added to the date part.
1327 * As a result, this query will return a zero period.
1328 * <p>
1329 * The {@code SMART} behaviour handles the common "end of day" 24:00 value.
1330 * Processing in {@code LENIENT} mode also produces the same result:
1331 * <pre>
1332 * Text to parse Parsed object Excess days
1333 * "2012-12-03T00:00" LocalDateTime.of(2012, 12, 3, 0, 0) ZERO
1334 * "2012-12-03T24:00" LocalDateTime.of(2012, 12, 4, 0, 0) ZERO
1335 * "00:00" LocalTime.of(0, 0) ZERO
1336 * "24:00" LocalTime.of(0, 0) Period.ofDays(1)
1337 * </pre>
1338 * The query can be used as follows:
1339 * <pre>
1340 * TemporalAccessor parsed = formatter.parse(str);
1341 * LocalTime time = parsed.query(LocalTime::from);
1342 * Period extraDays = parsed.query(DateTimeFormatter.parsedExcessDays());
1343 * </pre>
1344 * @return a query that provides access to the excess days that were parsed
1345 */
1346 public static final TemporalQuery<Period> parsedExcessDays() {
1347 return PARSED_EXCESS_DAYS;
1348 }
1349 private static final TemporalQuery<Period> PARSED_EXCESS_DAYS = t -> {
1350 if (t instanceof Parsed) {
1351 return ((Parsed) t).excessDays;
1352 } else {
1353 return Period.ZERO;
1354 }
1355 };
1356
1357 /**
1358 * A query that provides access to whether a leap-second was parsed.
1359 * <p>
1360 * This returns a singleton {@linkplain TemporalQuery query} that provides
1361 * access to additional information from the parse. The query always returns
1362 * a non-null boolean, true if parsing saw a leap-second, false if not.
1363 * <p>
1364 * Instant parsing handles the special "leap second" time of '23:59:60'.
1365 * Leap seconds occur at '23:59:60' in the UTC time-zone, but at other
1366 * local times in different time-zones. To avoid this potential ambiguity,
1367 * the handling of leap-seconds is limited to
1368 * {@link DateTimeFormatterBuilder#appendInstant()}, as that method
1369 * always parses the instant with the UTC zone offset.
1370 * <p>
1371 * If the time '23:59:60' is received, then a simple conversion is applied,
1372 * replacing the second-of-minute of 60 with 59. This query can be used
1373 * on the parse result to determine if the leap-second adjustment was made.
1374 * The query will return {@code true} if it did adjust to remove the
1375 * leap-second, and {@code false} if not. Note that applying a leap-second
1376 * smoothing mechanism, such as UTC-SLS, is the responsibility of the
1377 * application, as follows:
1378 * <pre>
1379 * TemporalAccessor parsed = formatter.parse(str);
1380 * Instant instant = parsed.query(Instant::from);
1381 * if (parsed.query(DateTimeFormatter.parsedLeapSecond())) {
1382 * // validate leap-second is correct and apply correct smoothing
1383 * }
1384 * </pre>
1385 * @return a query that provides access to whether a leap-second was parsed
1386 */
1387 public static final TemporalQuery<Boolean> parsedLeapSecond() {
1388 return PARSED_LEAP_SECOND;
1389 }
1390 private static final TemporalQuery<Boolean> PARSED_LEAP_SECOND = t -> {
1391 if (t instanceof Parsed) {
1392 return ((Parsed) t).leapSecond;
1393 } else {
1394 return Boolean.FALSE;
1395 }
1396 };
1397
1398 //-----------------------------------------------------------------------
1399 /**
1400 * Constructor.
1401 *
1402 * @param printerParser the printer/parser to use, not null
1403 * @param locale the locale to use, not null
1404 * @param decimalStyle the DecimalStyle to use, not null
1405 * @param resolverStyle the resolver style to use, not null
1406 * @param resolverFields the fields to use during resolving, null for all fields
1407 * @param chrono the chronology to use, null for no override
1408 * @param zone the zone to use, null for no override
1409 */
1410 DateTimeFormatter(CompositePrinterParser printerParser,
1411 Locale locale, DecimalStyle decimalStyle,
1412 ResolverStyle resolverStyle, Set<TemporalField> resolverFields,
1413 Chronology chrono, ZoneId zone) {
1414 this.printerParser = Objects.requireNonNull(printerParser, "printerParser");
1415 this.resolverFields = resolverFields;
1416 this.locale = Objects.requireNonNull(locale, "locale");
1417 this.decimalStyle = Objects.requireNonNull(decimalStyle, "decimalStyle");
1418 this.resolverStyle = Objects.requireNonNull(resolverStyle, "resolverStyle");
1419 this.chrono = chrono;
1420 this.zone = zone;
1421 }
1422
1423 //-----------------------------------------------------------------------
1424 /**
1425 * Gets the locale to be used during formatting.
1426 * <p>
1427 * This is used to lookup any part of the formatter needing specific
1428 * localization, such as the text or localized pattern.
1429 *
1430 * @return the locale of this formatter, not null
1431 */
1432 public Locale getLocale() {
1433 return locale;
1434 }
1435
1436 /**
1437 * Returns a copy of this formatter with a new locale.
1438 * <p>
1439 * This is used to lookup any part of the formatter needing specific
1440 * localization, such as the text or localized pattern.
1441 * <p>
1442 * This instance is immutable and unaffected by this method call.
1443 *
1444 * @param locale the new locale, not null
1445 * @return a formatter based on this formatter with the requested locale, not null
1446 */
1447 public DateTimeFormatter withLocale(Locale locale) {
1448 if (this.locale.equals(locale)) {
1449 return this;
1450 }
1451 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1452 }
1453
1454 //-----------------------------------------------------------------------
1455 /**
1456 * Gets the DecimalStyle to be used during formatting.
1457 *
1458 * @return the locale of this formatter, not null
1459 */
1460 public DecimalStyle getDecimalStyle() {
1461 return decimalStyle;
1462 }
1463
1464 /**
1465 * Returns a copy of this formatter with a new DecimalStyle.
1466 * <p>
1467 * This instance is immutable and unaffected by this method call.
1468 *
1469 * @param decimalStyle the new DecimalStyle, not null
1470 * @return a formatter based on this formatter with the requested DecimalStyle, not null
1471 */
1472 public DateTimeFormatter withDecimalStyle(DecimalStyle decimalStyle) {
1473 if (this.decimalStyle.equals(decimalStyle)) {
1474 return this;
1475 }
1476 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1477 }
1478
1479 //-----------------------------------------------------------------------
1480 /**
1481 * Gets the overriding chronology to be used during formatting.
1482 * <p>
1483 * This returns the override chronology, used to convert dates.
1484 * By default, a formatter has no override chronology, returning null.
1485 * See {@link #withChronology(Chronology)} for more details on overriding.
1486 *
1487 * @return the override chronology of this formatter, null if no override
1488 */
1489 public Chronology getChronology() {
1490 return chrono;
1491 }
1492
1493 /**
1494 * Returns a copy of this formatter with a new override chronology.
1495 * <p>
1496 * This returns a formatter with similar state to this formatter but
1497 * with the override chronology set.
1498 * By default, a formatter has no override chronology, returning null.
1499 * <p>
1500 * If an override is added, then any date that is formatted or parsed will be affected.
1501 * <p>
1502 * When formatting, if the temporal object contains a date, then it will
1503 * be converted to a date in the override chronology.
1504 * Whether the temporal contains a date is determined by querying the
1505 * {@link ChronoField#EPOCH_DAY EPOCH_DAY} field.
1506 * Any time or zone will be retained unaltered unless overridden.
1507 * <p>
1508 * If the temporal object does not contain a date, but does contain one
1509 * or more {@code ChronoField} date fields, then a {@code DateTimeException}
1510 * is thrown. In all other cases, the override chronology is added to the temporal,
1511 * replacing any previous chronology, but without changing the date/time.
1512 * <p>
1513 * When parsing, there are two distinct cases to consider.
1514 * If a chronology has been parsed directly from the text, perhaps because
1515 * {@link DateTimeFormatterBuilder#appendChronologyId()} was used, then
1516 * this override chronology has no effect.
1517 * If no zone has been parsed, then this override chronology will be used
1518 * to interpret the {@code ChronoField} values into a date according to the
1519 * date resolving rules of the chronology.
1520 * <p>
1521 * This instance is immutable and unaffected by this method call.
1522 *
1523 * @param chrono the new chronology, null if no override
1524 * @return a formatter based on this formatter with the requested override chronology, not null
1525 */
1526 public DateTimeFormatter withChronology(Chronology chrono) {
1527 if (Objects.equals(this.chrono, chrono)) {
1528 return this;
1529 }
1530 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1531 }
1532
1533 //-----------------------------------------------------------------------
1534 /**
1535 * Gets the overriding zone to be used during formatting.
1536 * <p>
1537 * This returns the override zone, used to convert instants.
1538 * By default, a formatter has no override zone, returning null.
1539 * See {@link #withZone(ZoneId)} for more details on overriding.
1540 *
1541 * @return the override zone of this formatter, null if no override
1542 */
1543 public ZoneId getZone() {
1544 return zone;
1545 }
1546
1547 /**
1548 * Returns a copy of this formatter with a new override zone.
1549 * <p>
1550 * This returns a formatter with similar state to this formatter but
1551 * with the override zone set.
1552 * By default, a formatter has no override zone, returning null.
1553 * <p>
1554 * If an override is added, then any instant that is formatted or parsed will be affected.
1555 * <p>
1556 * When formatting, if the temporal object contains an instant, then it will
1557 * be converted to a zoned date-time using the override zone.
1558 * Whether the temporal is an instant is determined by querying the
1559 * {@link ChronoField#INSTANT_SECONDS INSTANT_SECONDS} field.
1560 * If the input has a chronology then it will be retained unless overridden.
1561 * If the input does not have a chronology, such as {@code Instant}, then
1562 * the ISO chronology will be used.
1563 * <p>
1564 * If the temporal object does not contain an instant, but does contain
1565 * an offset then an additional check is made. If the normalized override
1566 * zone is an offset that differs from the offset of the temporal, then
1567 * a {@code DateTimeException} is thrown. In all other cases, the override
1568 * zone is added to the temporal, replacing any previous zone, but without
1569 * changing the date/time.
1570 * <p>
1571 * When parsing, there are two distinct cases to consider.
1572 * If a zone has been parsed directly from the text, perhaps because
1573 * {@link DateTimeFormatterBuilder#appendZoneId()} was used, then
1574 * this override zone has no effect.
1575 * If no zone has been parsed, then this override zone will be included in
1576 * the result of the parse where it can be used to build instants and date-times.
1577 * <p>
1578 * This instance is immutable and unaffected by this method call.
1579 *
1580 * @param zone the new override zone, null if no override
1581 * @return a formatter based on this formatter with the requested override zone, not null
1582 */
1583 public DateTimeFormatter withZone(ZoneId zone) {
1584 if (Objects.equals(this.zone, zone)) {
1585 return this;
1586 }
1587 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1588 }
1589
1590 //-----------------------------------------------------------------------
1591 /**
1592 * Gets the resolver style to use during parsing.
1593 * <p>
1594 * This returns the resolver style, used during the second phase of parsing
1595 * when fields are resolved into dates and times.
1596 * By default, a formatter has the {@link ResolverStyle#SMART SMART} resolver style.
1597 * See {@link #withResolverStyle(ResolverStyle)} for more details.
1598 *
1599 * @return the resolver style of this formatter, not null
1600 */
1601 public ResolverStyle getResolverStyle() {
1602 return resolverStyle;
1603 }
1604
1605 /**
1606 * Returns a copy of this formatter with a new resolver style.
1607 * <p>
1608 * This returns a formatter with similar state to this formatter but
1609 * with the resolver style set. By default, a formatter has the
1610 * {@link ResolverStyle#SMART SMART} resolver style.
1611 * <p>
1612 * Changing the resolver style only has an effect during parsing.
1613 * Parsing a text string occurs in two phases.
1614 * Phase 1 is a basic text parse according to the fields added to the builder.
1615 * Phase 2 resolves the parsed field-value pairs into date and/or time objects.
1616 * The resolver style is used to control how phase 2, resolving, happens.
1617 * See {@code ResolverStyle} for more information on the options available.
1618 * <p>
1619 * This instance is immutable and unaffected by this method call.
1620 *
1621 * @param resolverStyle the new resolver style, not null
1622 * @return a formatter based on this formatter with the requested resolver style, not null
1623 */
1624 public DateTimeFormatter withResolverStyle(ResolverStyle resolverStyle) {
1625 Objects.requireNonNull(resolverStyle, "resolverStyle");
1626 if (Objects.equals(this.resolverStyle, resolverStyle)) {
1627 return this;
1628 }
1629 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1630 }
1631
1632 //-----------------------------------------------------------------------
1633 /**
1634 * Gets the resolver fields to use during parsing.
1635 * <p>
1636 * This returns the resolver fields, used during the second phase of parsing
1637 * when fields are resolved into dates and times.
1638 * By default, a formatter has no resolver fields, and thus returns null.
1639 * See {@link #withResolverFields(Set)} for more details.
1640 *
1641 * @return the immutable set of resolver fields of this formatter, null if no fields
1642 */
1643 public Set<TemporalField> getResolverFields() {
1644 return resolverFields;
1645 }
1646
1647 /**
1648 * Returns a copy of this formatter with a new set of resolver fields.
1649 * <p>
1650 * This returns a formatter with similar state to this formatter but with
1651 * the resolver fields set. By default, a formatter has no resolver fields.
1652 * <p>
1653 * Changing the resolver fields only has an effect during parsing.
1654 * Parsing a text string occurs in two phases.
1655 * Phase 1 is a basic text parse according to the fields added to the builder.
1656 * Phase 2 resolves the parsed field-value pairs into date and/or time objects.
1657 * The resolver fields are used to filter the field-value pairs between phase 1 and 2.
1658 * <p>
1659 * This can be used to select between two or more ways that a date or time might
1660 * be resolved. For example, if the formatter consists of year, month, day-of-month
1661 * and day-of-year, then there are two ways to resolve a date.
1662 * Calling this method with the arguments {@link ChronoField#YEAR YEAR} and
1663 * {@link ChronoField#DAY_OF_YEAR DAY_OF_YEAR} will ensure that the date is
1664 * resolved using the year and day-of-year, effectively meaning that the month
1665 * and day-of-month are ignored during the resolving phase.
1666 * <p>
1667 * In a similar manner, this method can be used to ignore secondary fields that
1668 * would otherwise be cross-checked. For example, if the formatter consists of year,
1669 * month, day-of-month and day-of-week, then there is only one way to resolve a
1670 * date, but the parsed value for day-of-week will be cross-checked against the
1671 * resolved date. Calling this method with the arguments {@link ChronoField#YEAR YEAR},
1672 * {@link ChronoField#MONTH_OF_YEAR MONTH_OF_YEAR} and
1673 * {@link ChronoField#DAY_OF_MONTH DAY_OF_MONTH} will ensure that the date is
1674 * resolved correctly, but without any cross-check for the day-of-week.
1675 * <p>
1676 * In implementation terms, this method behaves as follows. The result of the
1677 * parsing phase can be considered to be a map of field to value. The behavior
1678 * of this method is to cause that map to be filtered between phase 1 and 2,
1679 * removing all fields other than those specified as arguments to this method.
1680 * <p>
1681 * This instance is immutable and unaffected by this method call.
1682 *
1683 * @param resolverFields the new set of resolver fields, null if no fields
1684 * @return a formatter based on this formatter with the requested resolver style, not null
1685 */
1686 public DateTimeFormatter withResolverFields(TemporalField... resolverFields) {
1687 Set<TemporalField> fields = null;
1688 if (resolverFields != null) {
1689 // Set.of cannot be used because it is hostile to nulls and duplicate elements
1690 fields = Collections.unmodifiableSet(new HashSet<>(Arrays.asList(resolverFields)));
1691 }
1692 if (Objects.equals(this.resolverFields, fields)) {
1693 return this;
1694 }
1695 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, fields, chrono, zone);
1696 }
1697
1698 /**
1699 * Returns a copy of this formatter with a new set of resolver fields.
1700 * <p>
1701 * This returns a formatter with similar state to this formatter but with
1702 * the resolver fields set. By default, a formatter has no resolver fields.
1703 * <p>
1704 * Changing the resolver fields only has an effect during parsing.
1705 * Parsing a text string occurs in two phases.
1706 * Phase 1 is a basic text parse according to the fields added to the builder.
1707 * Phase 2 resolves the parsed field-value pairs into date and/or time objects.
1708 * The resolver fields are used to filter the field-value pairs between phase 1 and 2.
1709 * <p>
1710 * This can be used to select between two or more ways that a date or time might
1711 * be resolved. For example, if the formatter consists of year, month, day-of-month
1712 * and day-of-year, then there are two ways to resolve a date.
1713 * Calling this method with the arguments {@link ChronoField#YEAR YEAR} and
1714 * {@link ChronoField#DAY_OF_YEAR DAY_OF_YEAR} will ensure that the date is
1715 * resolved using the year and day-of-year, effectively meaning that the month
1716 * and day-of-month are ignored during the resolving phase.
1717 * <p>
1718 * In a similar manner, this method can be used to ignore secondary fields that
1719 * would otherwise be cross-checked. For example, if the formatter consists of year,
1720 * month, day-of-month and day-of-week, then there is only one way to resolve a
1721 * date, but the parsed value for day-of-week will be cross-checked against the
1722 * resolved date. Calling this method with the arguments {@link ChronoField#YEAR YEAR},
1723 * {@link ChronoField#MONTH_OF_YEAR MONTH_OF_YEAR} and
1724 * {@link ChronoField#DAY_OF_MONTH DAY_OF_MONTH} will ensure that the date is
1725 * resolved correctly, but without any cross-check for the day-of-week.
1726 * <p>
1727 * In implementation terms, this method behaves as follows. The result of the
1728 * parsing phase can be considered to be a map of field to value. The behavior
1729 * of this method is to cause that map to be filtered between phase 1 and 2,
1730 * removing all fields other than those specified as arguments to this method.
1731 * <p>
1732 * This instance is immutable and unaffected by this method call.
1733 *
1734 * @param resolverFields the new set of resolver fields, null if no fields
1735 * @return a formatter based on this formatter with the requested resolver style, not null
1736 */
1737 public DateTimeFormatter withResolverFields(Set<TemporalField> resolverFields) {
1738 if (Objects.equals(this.resolverFields, resolverFields)) {
1739 return this;
1740 }
1741 if (resolverFields != null) {
1742 resolverFields = Collections.unmodifiableSet(new HashSet<>(resolverFields));
1743 }
1744 return new DateTimeFormatter(printerParser, locale, decimalStyle, resolverStyle, resolverFields, chrono, zone);
1745 }
1746
1747 //-----------------------------------------------------------------------
1748 /**
1749 * Formats a date-time object using this formatter.
1750 * <p>
1751 * This formats the date-time to a String using the rules of the formatter.
1752 *
1753 * @param temporal the temporal object to format, not null
1754 * @return the formatted string, not null
1755 * @throws DateTimeException if an error occurs during formatting
1756 */
1757 public String format(TemporalAccessor temporal) {
1758 StringBuilder buf = new StringBuilder(32);
1759 formatTo(temporal, buf);
1760 return buf.toString();
1761 }
1762
1763 //-----------------------------------------------------------------------
1764 /**
1765 * Formats a date-time object to an {@code Appendable} using this formatter.
1766 * <p>
1767 * This outputs the formatted date-time to the specified destination.
1768 * {@link Appendable} is a general purpose interface that is implemented by all
1769 * key character output classes including {@code StringBuffer}, {@code StringBuilder},
1770 * {@code PrintStream} and {@code Writer}.
1771 * <p>
1772 * Although {@code Appendable} methods throw an {@code IOException}, this method does not.
1773 * Instead, any {@code IOException} is wrapped in a runtime exception.
1774 *
1775 * @param temporal the temporal object to format, not null
1776 * @param appendable the appendable to format to, not null
1777 * @throws DateTimeException if an error occurs during formatting
1778 */
1779 public void formatTo(TemporalAccessor temporal, Appendable appendable) {
1780 Objects.requireNonNull(temporal, "temporal");
1781 Objects.requireNonNull(appendable, "appendable");
1782 try {
1783 DateTimePrintContext context = new DateTimePrintContext(temporal, this);
1784 if (appendable instanceof StringBuilder) {
1785 printerParser.format(context, (StringBuilder) appendable);
1786 } else {
1787 // buffer output to avoid writing to appendable in case of error
1788 StringBuilder buf = new StringBuilder(32);
1789 printerParser.format(context, buf);
1790 appendable.append(buf);
1791 }
1792 } catch (IOException ex) {
1793 throw new DateTimeException(ex.getMessage(), ex);
1794 }
1795 }
1796
1797 //-----------------------------------------------------------------------
1798 /**
1799 * Fully parses the text producing a temporal object.
1800 * <p>
1801 * This parses the entire text producing a temporal object.
1802 * It is typically more useful to use {@link #parse(CharSequence, TemporalQuery)}.
1803 * The result of this method is {@code TemporalAccessor} which has been resolved,
1804 * applying basic validation checks to help ensure a valid date-time.
1805 * <p>
1806 * If the parse completes without reading the entire length of the text,
1807 * or a problem occurs during parsing or merging, then an exception is thrown.
1808 *
1809 * @param text the text to parse, not null
1810 * @return the parsed temporal object, not null
1811 * @throws DateTimeParseException if unable to parse the requested result
1812 */
1813 public TemporalAccessor parse(CharSequence text) {
1814 Objects.requireNonNull(text, "text");
1815 try {
1816 return parseResolved0(text, null);
1817 } catch (DateTimeParseException ex) {
1818 throw ex;
1819 } catch (RuntimeException ex) {
1820 throw createError(text, ex);
1821 }
1822 }
1823
1824 /**
1825 * Parses the text using this formatter, providing control over the text position.
1826 * <p>
1827 * This parses the text without requiring the parse to start from the beginning
1828 * of the string or finish at the end.
1829 * The result of this method is {@code TemporalAccessor} which has been resolved,
1830 * applying basic validation checks to help ensure a valid date-time.
1831 * <p>
1832 * The text will be parsed from the specified start {@code ParsePosition}.
1833 * The entire length of the text does not have to be parsed, the {@code ParsePosition}
1834 * will be updated with the index at the end of parsing.
1835 * <p>
1836 * The operation of this method is slightly different to similar methods using
1837 * {@code ParsePosition} on {@code java.text.Format}. That class will return
1838 * errors using the error index on the {@code ParsePosition}. By contrast, this
1839 * method will throw a {@link DateTimeParseException} if an error occurs, with
1840 * the exception containing the error index.
1841 * This change in behavior is necessary due to the increased complexity of
1842 * parsing and resolving dates/times in this API.
1843 * <p>
1844 * If the formatter parses the same field more than once with different values,
1845 * the result will be an error.
1846 *
1847 * @param text the text to parse, not null
1848 * @param position the position to parse from, updated with length parsed
1849 * and the index of any error, not null
1850 * @return the parsed temporal object, not null
1851 * @throws DateTimeParseException if unable to parse the requested result
1852 * @throws IndexOutOfBoundsException if the position is invalid
1853 */
1854 public TemporalAccessor parse(CharSequence text, ParsePosition position) {
1855 Objects.requireNonNull(text, "text");
1856 Objects.requireNonNull(position, "position");
1857 try {
1858 return parseResolved0(text, position);
1859 } catch (DateTimeParseException | IndexOutOfBoundsException ex) {
1860 throw ex;
1861 } catch (RuntimeException ex) {
1862 throw createError(text, ex);
1863 }
1864 }
1865
1866 //-----------------------------------------------------------------------
1867 /**
1868 * Fully parses the text producing an object of the specified type.
1869 * <p>
1870 * Most applications should use this method for parsing.
1871 * It parses the entire text to produce the required date-time.
1872 * The query is typically a method reference to a {@code from(TemporalAccessor)} method.
1873 * For example:
1874 * <pre>
1875 * LocalDateTime dt = parser.parse(str, LocalDateTime::from);
1876 * </pre>
1877 * If the parse completes without reading the entire length of the text,
1878 * or a problem occurs during parsing or merging, then an exception is thrown.
1879 *
1880 * @param <T> the type of the parsed date-time
1881 * @param text the text to parse, not null
1882 * @param query the query defining the type to parse to, not null
1883 * @return the parsed date-time, not null
1884 * @throws DateTimeParseException if unable to parse the requested result
1885 */
1886 public <T> T parse(CharSequence text, TemporalQuery<T> query) {
1887 Objects.requireNonNull(text, "text");
1888 Objects.requireNonNull(query, "query");
1889 try {
1890 return parseResolved0(text, null).query(query);
1891 } catch (DateTimeParseException ex) {
1892 throw ex;
1893 } catch (RuntimeException ex) {
1894 throw createError(text, ex);
1895 }
1896 }
1897
1898 /**
1899 * Fully parses the text producing an object of one of the specified types.
1900 * <p>
1901 * This parse method is convenient for use when the parser can handle optional elements.
1902 * For example, a pattern of 'uuuu-MM-dd HH.mm[ VV]' can be fully parsed to a {@code ZonedDateTime},
1903 * or partially parsed to a {@code LocalDateTime}.
1904 * The queries must be specified in order, starting from the best matching full-parse option
1905 * and ending with the worst matching minimal parse option.
1906 * The query is typically a method reference to a {@code from(TemporalAccessor)} method.
1907 * <p>
1908 * The result is associated with the first type that successfully parses.
1909 * Normally, applications will use {@code instanceof} to check the result.
1910 * For example:
1911 * <pre>
1912 * TemporalAccessor dt = parser.parseBest(str, ZonedDateTime::from, LocalDateTime::from);
1913 * if (dt instanceof ZonedDateTime) {
1914 * ...
1915 * } else {
1916 * ...
1917 * }
1918 * </pre>
1919 * If the parse completes without reading the entire length of the text,
1920 * or a problem occurs during parsing or merging, then an exception is thrown.
1921 *
1922 * @param text the text to parse, not null
1923 * @param queries the queries defining the types to attempt to parse to,
1924 * must implement {@code TemporalAccessor}, not null
1925 * @return the parsed date-time, not null
1926 * @throws IllegalArgumentException if less than 2 types are specified
1927 * @throws DateTimeParseException if unable to parse the requested result
1928 */
1929 public TemporalAccessor parseBest(CharSequence text, TemporalQuery<?>... queries) {
1930 Objects.requireNonNull(text, "text");
1931 Objects.requireNonNull(queries, "queries");
1932 if (queries.length < 2) {
1933 throw new IllegalArgumentException("At least two queries must be specified");
1934 }
1935 try {
1936 TemporalAccessor resolved = parseResolved0(text, null);
1937 for (TemporalQuery<?> query : queries) {
1938 try {
1939 return (TemporalAccessor) resolved.query(query);
1940 } catch (RuntimeException ex) {
1941 // continue
1942 }
1943 }
1944 throw new DateTimeException("Unable to convert parsed text using any of the specified queries");
1945 } catch (DateTimeParseException ex) {
1946 throw ex;
1947 } catch (RuntimeException ex) {
1948 throw createError(text, ex);
1949 }
1950 }
1951
1952 private DateTimeParseException createError(CharSequence text, RuntimeException ex) {
1953 String abbr;
1954 if (text.length() > 64) {
1955 abbr = text.subSequence(0, 64).toString() + "...";
1956 } else {
1957 abbr = text.toString();
1958 }
1959 return new DateTimeParseException("Text '" + abbr + "' could not be parsed: " + ex.getMessage(), text, 0, ex);
1960 }
1961
1962 //-----------------------------------------------------------------------
1963 /**
1964 * Parses and resolves the specified text.
1965 * <p>
1966 * This parses to a {@code TemporalAccessor} ensuring that the text is fully parsed.
1967 *
1968 * @param text the text to parse, not null
1969 * @param position the position to parse from, updated with length parsed
1970 * and the index of any error, null if parsing whole string
1971 * @return the resolved result of the parse, not null
1972 * @throws DateTimeParseException if the parse fails
1973 * @throws DateTimeException if an error occurs while resolving the date or time
1974 * @throws IndexOutOfBoundsException if the position is invalid
1975 */
1976 private TemporalAccessor parseResolved0(final CharSequence text, final ParsePosition position) {
1977 ParsePosition pos = (position != null ? position : new ParsePosition(0));
1978 DateTimeParseContext context = parseUnresolved0(text, pos);
1979 if (context == null || pos.getErrorIndex() >= 0 || (position == null && pos.getIndex() < text.length())) {
1980 String abbr;
1981 if (text.length() > 64) {
1982 abbr = text.subSequence(0, 64).toString() + "...";
1983 } else {
1984 abbr = text.toString();
1985 }
1986 if (pos.getErrorIndex() >= 0) {
1987 throw new DateTimeParseException("Text '" + abbr + "' could not be parsed at index " +
1988 pos.getErrorIndex(), text, pos.getErrorIndex());
1989 } else {
1990 throw new DateTimeParseException("Text '" + abbr + "' could not be parsed, unparsed text found at index " +
1991 pos.getIndex(), text, pos.getIndex());
1992 }
1993 }
1994 return context.toResolved(resolverStyle, resolverFields);
1995 }
1996
1997 /**
1998 * Parses the text using this formatter, without resolving the result, intended
1999 * for advanced use cases.
2000 * <p>
2001 * Parsing is implemented as a two-phase operation.
2002 * First, the text is parsed using the layout defined by the formatter, producing
2003 * a {@code Map} of field to value, a {@code ZoneId} and a {@code Chronology}.
2004 * Second, the parsed data is <em>resolved</em>, by validating, combining and
2005 * simplifying the various fields into more useful ones.
2006 * This method performs the parsing stage but not the resolving stage.
2007 * <p>
2008 * The result of this method is {@code TemporalAccessor} which represents the
2009 * data as seen in the input. Values are not validated, thus parsing a date string
2010 * of '2012-00-65' would result in a temporal with three fields - year of '2012',
2011 * month of '0' and day-of-month of '65'.
2012 * <p>
2013 * The text will be parsed from the specified start {@code ParsePosition}.
2014 * The entire length of the text does not have to be parsed, the {@code ParsePosition}
2015 * will be updated with the index at the end of parsing.
2016 * <p>
2017 * Errors are returned using the error index field of the {@code ParsePosition}
2018 * instead of {@code DateTimeParseException}.
2019 * The returned error index will be set to an index indicative of the error.
2020 * Callers must check for errors before using the result.
2021 * <p>
2022 * If the formatter parses the same field more than once with different values,
2023 * the result will be an error.
2024 * <p>
2025 * This method is intended for advanced use cases that need access to the
2026 * internal state during parsing. Typical application code should use
2027 * {@link #parse(CharSequence, TemporalQuery)} or the parse method on the target type.
2028 *
2029 * @param text the text to parse, not null
2030 * @param position the position to parse from, updated with length parsed
2031 * and the index of any error, not null
2032 * @return the parsed text, null if the parse results in an error
2033 * @throws DateTimeException if some problem occurs during parsing
2034 * @throws IndexOutOfBoundsException if the position is invalid
2035 */
2036 public TemporalAccessor parseUnresolved(CharSequence text, ParsePosition position) {
2037 DateTimeParseContext context = parseUnresolved0(text, position);
2038 if (context == null) {
2039 return null;
2040 }
2041 return context.toUnresolved();
2042 }
2043
2044 private DateTimeParseContext parseUnresolved0(CharSequence text, ParsePosition position) {
2045 Objects.requireNonNull(text, "text");
2046 Objects.requireNonNull(position, "position");
2047 DateTimeParseContext context = new DateTimeParseContext(this);
2048 int pos = position.getIndex();
2049 pos = printerParser.parse(context, text, pos);
2050 if (pos < 0) {
2051 position.setErrorIndex(~pos); // index not updated from input
2052 return null;
2053 }
2054 position.setIndex(pos); // errorIndex not updated from input
2055 return context;
2056 }
2057
2058 //-----------------------------------------------------------------------
2059 /**
2060 * Returns the formatter as a composite printer parser.
2061 *
2062 * @param optional whether the printer/parser should be optional
2063 * @return the printer/parser, not null
2064 */
2065 CompositePrinterParser toPrinterParser(boolean optional) {
2066 return printerParser.withOptional(optional);
2067 }
2068
2069 /**
2070 * Returns this formatter as a {@code java.text.Format} instance.
2071 * <p>
2072 * The returned {@link Format} instance will format any {@link TemporalAccessor}
2073 * and parses to a resolved {@link TemporalAccessor}.
2074 * <p>
2075 * Exceptions will follow the definitions of {@code Format}, see those methods
2076 * for details about {@code IllegalArgumentException} during formatting and
2077 * {@code ParseException} or null during parsing.
2078 * The format does not support attributing of the returned format string.
2079 *
2080 * @return this formatter as a classic format instance, not null
2081 */
2082 public Format toFormat() {
2083 return new ClassicFormat(this, null);
2084 }
2085
2086 /**
2087 * Returns this formatter as a {@code java.text.Format} instance that will
2088 * parse using the specified query.
2089 * <p>
2090 * The returned {@link Format} instance will format any {@link TemporalAccessor}
2091 * and parses to the type specified.
2092 * The type must be one that is supported by {@link #parse}.
2093 * <p>
2094 * Exceptions will follow the definitions of {@code Format}, see those methods
2095 * for details about {@code IllegalArgumentException} during formatting and
2096 * {@code ParseException} or null during parsing.
2097 * The format does not support attributing of the returned format string.
2098 *
2099 * @param parseQuery the query defining the type to parse to, not null
2100 * @return this formatter as a classic format instance, not null
2101 */
2102 public Format toFormat(TemporalQuery<?> parseQuery) {
2103 Objects.requireNonNull(parseQuery, "parseQuery");
2104 return new ClassicFormat(this, parseQuery);
2105 }
2106
2107 //-----------------------------------------------------------------------
2108 /**
2109 * Returns a description of the underlying formatters.
2110 *
2111 * @return a description of this formatter, not null
2112 */
2113 @Override
2114 public String toString() {
2115 String pattern = printerParser.toString();
2116 pattern = pattern.startsWith("[") ? pattern : pattern.substring(1, pattern.length() - 1);
2117 return pattern;
2118 // TODO: Fix tests to not depend on toString()
2119 // return "DateTimeFormatter[" + locale +
2120 // (chrono != null ? "," + chrono : "") +
2121 // (zone != null ? "," + zone : "") +
2122 // pattern + "]";
2123 }
2124
2125 //-----------------------------------------------------------------------
2126 /**
2127 * Implements the classic Java Format API.
2128 * @serial exclude
2129 */
2130 @SuppressWarnings("serial") // not actually serializable
2131 static class ClassicFormat extends Format {
2132 /** The formatter. */
2133 private final DateTimeFormatter formatter;
2134 /** The type to be parsed. */
2135 private final TemporalQuery<?> parseType;
2136 /** Constructor. */
2137 public ClassicFormat(DateTimeFormatter formatter, TemporalQuery<?> parseType) {
2138 this.formatter = formatter;
2139 this.parseType = parseType;
2140 }
2141
2142 @Override
2143 public StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos) {
2144 Objects.requireNonNull(obj, "obj");
2145 Objects.requireNonNull(toAppendTo, "toAppendTo");
2146 Objects.requireNonNull(pos, "pos");
2147 if (obj instanceof TemporalAccessor == false) {
2148 throw new IllegalArgumentException("Format target must implement TemporalAccessor");
2149 }
2150 pos.setBeginIndex(0);
2151 pos.setEndIndex(0);
2152 try {
2153 formatter.formatTo((TemporalAccessor) obj, toAppendTo);
2154 } catch (RuntimeException ex) {
2155 throw new IllegalArgumentException(ex.getMessage(), ex);
2156 }
2157 return toAppendTo;
2158 }
2159 @Override
2160 public Object parseObject(String text) throws ParseException {
2161 Objects.requireNonNull(text, "text");
2162 try {
2163 if (parseType == null) {
2164 return formatter.parseResolved0(text, null);
2165 }
2166 return formatter.parse(text, parseType);
2167 } catch (DateTimeParseException ex) {
2168 throw new ParseException(ex.getMessage(), ex.getErrorIndex());
2169 } catch (RuntimeException ex) {
2170 throw (ParseException) new ParseException(ex.getMessage(), 0).initCause(ex);
2171 }
2172 }
2173 @Override
2174 public Object parseObject(String text, ParsePosition pos) {
2175 Objects.requireNonNull(text, "text");
2176 DateTimeParseContext context;
2177 try {
2178 context = formatter.parseUnresolved0(text, pos);
2179 } catch (IndexOutOfBoundsException ex) {
2180 if (pos.getErrorIndex() < 0) {
2181 pos.setErrorIndex(0);
2182 }
2183 return null;
2184 }
2185 if (context == null) {
2186 if (pos.getErrorIndex() < 0) {
2187 pos.setErrorIndex(0);
2188 }
2189 return null;
2190 }
2191 try {
2192 TemporalAccessor resolved = context.toResolved(formatter.resolverStyle, formatter.resolverFields);
2193 if (parseType == null) {
2194 return resolved;
2195 }
2196 return resolved.query(parseType);
2197 } catch (RuntimeException ex) {
2198 pos.setErrorIndex(0);
2199 return null;
2200 }
2201 }
2202 }
2203
2204 }