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