/*

 * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * This file is available under and governed by the GNU General Public

 * License version 2 only, as published by the Free Software Foundation.

 * However, the following notice accompanied the original version of this

 * file:

 *

 * Copyright (c) 2008-2012, Stephen Colebourne & Michael Nascimento Santos

 *

 * All rights reserved.

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions are met:

 *

 *  * Redistributions of source code must retain the above copyright notice,

 *    this list of conditions and the following disclaimer.

 *

 *  * Redistributions in binary form must reproduce the above copyright notice,

 *    this list of conditions and the following disclaimer in the documentation

 *    and/or other materials provided with the distribution.

 *

 *  * Neither the name of JSR-310 nor the names of its contributors

 *    may be used to endorse or promote products derived from this software

 *    without specific prior written permission.

 *

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

package java.time.format;

import static java.time.temporal.ChronoField.DAY_OF_MONTH;

import static java.time.temporal.ChronoField.DAY_OF_WEEK;

import static java.time.temporal.ChronoField.DAY_OF_YEAR;

import static java.time.temporal.ChronoField.HOUR_OF_DAY;

import static java.time.temporal.ChronoField.MINUTE_OF_HOUR;

import static java.time.temporal.ChronoField.MONTH_OF_YEAR;

import static java.time.temporal.ChronoField.NANO_OF_SECOND;

import static java.time.temporal.ChronoField.SECOND_OF_MINUTE;

import static java.time.temporal.ChronoField.YEAR;

import java.io.IOException;

import java.text.FieldPosition;

import java.text.Format;

import java.text.ParseException;

import java.text.ParsePosition;

import java.time.DateTimeException;

import java.time.Period;

import java.time.ZoneId;

import java.time.ZoneOffset;

import java.time.chrono.ChronoLocalDateTime;

import java.time.chrono.Chronology;

import java.time.chrono.IsoChronology;

import java.time.format.DateTimeFormatterBuilder.CompositePrinterParser;

import java.time.temporal.ChronoField;

import java.time.temporal.IsoFields;

import java.time.temporal.TemporalAccessor;

import java.time.temporal.TemporalField;

import java.time.temporal.TemporalQuery;

import java.util.Arrays;

import java.util.Collections;

import java.util.HashMap;

import java.util.HashSet;

import java.util.Locale;

import java.util.Map;

import java.util.Objects;

import java.util.Set;

/**

 * Formatter for printing and parsing date-time objects.

 * <p>

 * This class provides the main application entry point for printing and parsing

 * and provides common implementations of {@code DateTimeFormatter}:

 * <ul>

 * <li>Using predefined constants, such as {@link #ISO_LOCAL_DATE}</li>

 * <li>Using pattern letters, such as {@code uuuu-MMM-dd}</li>

 * <li>Using localized styles, such as {@code long} or {@code medium}</li>

 * </ul>

 * <p>

 * More complex formatters are provided by

 * {@link DateTimeFormatterBuilder DateTimeFormatterBuilder}.

 *

 * <p>

 * The main date-time classes provide two methods - one for formatting,

 * {@code format(DateTimeFormatter formatter)}, and one for parsing,

 * {@code parse(CharSequence text, DateTimeFormatter formatter)}.

 * <p>For example:

 * <blockquote><pre>

 *  LocalDate date = LocalDate.now();

 *  String text = date.format(formatter);

 *  LocalDate parsedDate = LocalDate.parse(text, formatter);

 * </pre></blockquote>

 * <p>

 * In addition to the format, formatters can be created with desired Locale,

 * Chronology, ZoneId, and DecimalStyle.

 * <p>

 * The {@link #withLocale withLocale} method returns a new formatter that

 * overrides the locale. The locale affects some aspects of formatting and

 * parsing. For example, the {@link #ofLocalizedDate ofLocalizedDate} provides a

 * formatter that uses the locale specific date format.

 * <p>

 * The {@link #withChronology withChronology} method returns a new formatter

 * that overrides the chronology. If overridden, the date-time value is

 * converted to the chronology before formatting. During parsing the date-time

 * value is converted to the chronology before it is returned.

 * <p>

 * The {@link #withZone withZone} method returns a new formatter that overrides

 * the zone. If overridden, the date-time value is converted to a ZonedDateTime

 * with the requested ZoneId before formatting. During parsing the ZoneId is

 * applied before the value is returned.

 * <p>

 * The {@link #withDecimalStyle withDecimalStyle} method returns a new formatter that

 * overrides the {@link DecimalStyle}. The DecimalStyle symbols are used for

 * formatting and parsing.

 * <p>

 * Some applications may need to use the older {@link Format java.text.Format}

 * class for formatting. The {@link #toFormat()} method returns an

 * implementation of {@code java.text.Format}.

 *

 * <h3 id="predefined">Predefined Formatters</h3>

 * <table class="striped">

 * <caption>Predefined Formatters</caption>

 * <thead>

 * <tr>

 * </tr>

 * </thead>

 * <tbody>

 * <tr>

 * <td> Formatter with date style from the locale </td>

 * <td> '2011-12-03'</td>

 * </tr>

 * <tr>

 * <td> Formatter with time style from the locale </td>

 * <td> '10:15:30'</td>

 * </tr>

 * <tr>

 * <td> Formatter with a style for date and time from the locale</td>

 * <td> '3 Jun 2008 11:05:30'</td>

 * </tr>

 * <tr>

 * <td> Formatter with date and time styles from the locale </td>

 * <td> '3 Jun 2008 11:05'</td>

 * </tr>

 * <tr>

 * <td>Basic ISO date </td> <td>'20111203'</td>

 * </tr>

 * <tr>

 * <td> ISO Local Date </td>

 * <td>'2011-12-03'</td>

 * </tr>

 * <tr>

 * <td> ISO Date with offset </td>

 * <td>'2011-12-03+01:00'</td>

 * </tr>

 * <tr>

 * <td> ISO Date with or without offset </td>

 * <td> '2011-12-03+01:00'; '2011-12-03'</td>

 * </tr>

 * <tr>

 * <td> Time without offset </td>

 * <td>'10:15:30'</td>

 * </tr>

 * <tr>

 * <td> Time with offset </td>

 * <td>'10:15:30+01:00'</td>

 * </tr>

 * <tr>

 * <td> Time with or without offset </td>

 * <td>'10:15:30+01:00'; '10:15:30'</td>

 * </tr>

 * <tr>

 * <td> ISO Local Date and Time </td>

 * <td>'2011-12-03T10:15:30'</td>

 * </tr>

 * <tr>

 * <td> Date Time with Offset

 * </td><td>2011-12-03T10:15:30+01:00'</td>

 * </tr>

 * <tr>

 * <td> Zoned Date Time </td>

 * <td>'2011-12-03T10:15:30+01:00[Europe/Paris]'</td>

 * </tr>

 * <tr>

 * <td> Date and time with ZoneId </td>

 * <td>'2011-12-03T10:15:30+01:00[Europe/Paris]'</td>

 * </tr>

 * <tr>

 * <td> Year and day of year </td>

 * <td>'2012-337'</td>

 * </tr>

 * <tr>

 * <td> Year and Week </td>

 * <td>2012-W48-6'</td></tr>

 * <tr>

 * <td> Date and Time of an Instant </td>

 * <td>'2011-12-03T10:15:30Z' </td>

 * </tr>

 * <tr>

 * <td> RFC 1123 / RFC 822 </td>

 * <td>'Tue, 3 Jun 2008 11:05:30 GMT'</td>

 * </tr>

 * </tbody>

 * </table>

 *

 * <h3 id="patterns">Patterns for Formatting and Parsing</h3>

 * Patterns are based on a simple sequence of letters and symbols.

 * A pattern is used to create a Formatter using the

 * {@link #ofPattern(String)} and {@link #ofPattern(String, Locale)} methods.

 * For example,

 * {@code "d MMM uuuu"} will format 2011-12-03 as '3 Dec 2011'.

 * A formatter created from a pattern can be used as many times as necessary,

 * it is immutable and is thread-safe.

 * <p>

 * For example:

 * <blockquote><pre>

 *  LocalDate date = LocalDate.now();

 *  DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy MM dd");

 *  String text = date.format(formatter);

 *  LocalDate parsedDate = LocalDate.parse(text, formatter);

 * </pre></blockquote>

 * <p>

 * All letters 'A' to 'Z' and 'a' to 'z' are reserved as pattern letters. The

 * following pattern letters are defined:

 * <pre>

 *  Symbol  Meaning                     Presentation      Examples

 *  ------  -------                     ------------      -------

 *   G       era                         text              AD; Anno Domini; A

 *   u       year                        year              2004; 04

 *   y       year-of-era                 year              2004; 04

 *   D       day-of-year                 number            189

 *   M/L     month-of-year               number/text       7; 07; Jul; July; J

 *   d       day-of-month                number            10

 *   g       modified-julian-day         number            2451334

 *

 *   Q/q     quarter-of-year             number/text       3; 03; Q3; 3rd quarter

 *   Y       week-based-year             year              1996; 96

 *   w       week-of-week-based-year     number            27

 *   W       week-of-month               number            4

 *   E       day-of-week                 text              Tue; Tuesday; T

 *   e/c     localized day-of-week       number/text       2; 02; Tue; Tuesday; T

 *   F       day-of-week-in-month        number            3

 *

 *   a       am-pm-of-day                text              PM

 *   h       clock-hour-of-am-pm (1-12)  number            12

 *   K       hour-of-am-pm (0-11)        number            0

 *   k       clock-hour-of-day (1-24)    number            24

 *

 *   H       hour-of-day (0-23)          number            0

 *   m       minute-of-hour              number            30

 *   s       second-of-minute            number            55

 *   S       fraction-of-second          fraction          978

 *   A       milli-of-day                number            1234

 *   n       nano-of-second              number            987654321

 *   N       nano-of-day                 number            1234000000

 *

 *   V       time-zone ID                zone-id           America/Los_Angeles; Z; -08:30

 *   v       generic time-zone name      zone-name         Pacific Time; PT

 *   z       time-zone name              zone-name         Pacific Standard Time; PST

 *   O       localized zone-offset       offset-O          GMT+8; GMT+08:00; UTC-08:00

 *   X       zone-offset 'Z' for zero    offset-X          Z; -08; -0830; -08:30; -083015; -08:30:15

 *   x       zone-offset                 offset-x          +0000; -08; -0830; -08:30; -083015; -08:30:15

 *   Z       zone-offset                 offset-Z          +0000; -0800; -08:00

 *

 *   p       pad next                    pad modifier      1

 *

 *   '       escape for text             delimiter

 *   ''      single quote                literal           '

 *   [       optional section start

 *   ]       optional section end

 *   #       reserved for future use

 *   {       reserved for future use

 *   }       reserved for future use

 * </pre>

 * <p>

 * The count of pattern letters determines the format.

 * <p>

 * <b>Text</b>: The text style is determined based on the number of pattern

 * letters used. Less than 4 pattern letters will use the

 * {@link TextStyle#SHORT short form}. Exactly 4 pattern letters will use the

 * {@link TextStyle#FULL full form}. Exactly 5 pattern letters will use the

 * {@link TextStyle#NARROW narrow form}.

 * Pattern letters 'L', 'c', and 'q' specify the stand-alone form of the text styles.

 * <p>

 * <b>Number</b>: If the count of letters is one, then the value is output using

 * the minimum number of digits and without padding. Otherwise, the count of digits

 * is used as the width of the output field, with the value zero-padded as necessary.

 * The following pattern letters have constraints on the count of letters.

 * Only one letter of 'c' and 'F' can be specified.

 * Up to two letters of 'd', 'H', 'h', 'K', 'k', 'm', and 's' can be specified.

 * Up to three letters of 'D' can be specified.

 * <p>

 * <b>Number/Text</b>: If the count of pattern letters is 3 or greater, use the

 * Text rules above. Otherwise use the Number rules above.

 * <p>

 * <b>Fraction</b>: Outputs the nano-of-second field as a fraction-of-second.

 * The nano-of-second value has nine digits, thus the count of pattern letters

 * is from 1 to 9. If it is less than 9, then the nano-of-second value is

 * truncated, with only the most significant digits being output.

 * <p>

 * <b>Year</b>: The count of letters determines the minimum field width below

 * which padding is used. If the count of letters is two, then a

 * {@link DateTimeFormatterBuilder#appendValueReduced reduced} two digit form is

 * used. For printing, this outputs the rightmost two digits. For parsing, this

 * will parse using the base value of 2000, resulting in a year within the range

 * 2000 to 2099 inclusive. If the count of letters is less than four (but not

 * two), then the sign is only output for negative years as per

 * {@link SignStyle#NORMAL}. Otherwise, the sign is output if the pad width is

 * exceeded, as per {@link SignStyle#EXCEEDS_PAD}.

 * <p>

 * <b>ZoneId</b>: This outputs the time-zone ID, such as 'Europe/Paris'. If the

 * count of letters is two, then the time-zone ID is output. Any other count of

 * letters throws {@code IllegalArgumentException}.

 * <p>

 * <b>Zone names</b>: This outputs the display name of the time-zone ID. If the

 * pattern letter is 'z' the output is the daylight savings aware zone name.

 * If there is insufficient information to determine whether DST applies,

 * the name ignoring daylight savings time will be used.

 * If the count of letters is one, two or three, then the short name is output.

 * If the count of letters is four, then the full name is output.

 * Five or more letters throws {@code IllegalArgumentException}.

 * <p>

 * If the pattern letter is 'v' the output provides the zone name ignoring

 * daylight savings time. If the count of letters is one, then the short name is output.

 * If the count of letters is four, then the full name is output.

 * Two, three and five or more letters throw {@code IllegalArgumentException}.

 * <p>

 * <b>Offset X and x</b>: This formats the offset based on the number of pattern

 * letters. One letter outputs just the hour, such as '+01', unless the minute

 * is non-zero in which case the minute is also output, such as '+0130'. Two

 * letters outputs the hour and minute, without a colon, such as '+0130'. Three

 * letters outputs the hour and minute, with a colon, such as '+01:30'. Four

 * letters outputs the hour and minute and optional second, without a colon,

 * such as '+013015'. Five letters outputs the hour and minute and optional

 * second, with a colon, such as '+01:30:15'. Six or more letters throws

 * {@code IllegalArgumentException}. Pattern letter 'X' (upper case) will output

 * 'Z' when the offset to be output would be zero, whereas pattern letter 'x'

 * (lower case) will output '+00', '+0000', or '+00:00'.

 * <p>

 * <b>Offset O</b>: This formats the localized offset based on the number of

 * pattern letters. One letter outputs the {@linkplain TextStyle#SHORT short}

 * form of the localized offset, which is localized offset text, such as 'GMT',

 * with hour without leading zero, optional 2-digit minute and second if

 * non-zero, and colon, for example 'GMT+8'. Four letters outputs the

 * {@linkplain TextStyle#FULL full} form, which is localized offset text,

 * such as 'GMT, with 2-digit hour and minute field, optional second field

 * if non-zero, and colon, for example 'GMT+08:00'. Any other count of letters

 * throws {@code IllegalArgumentException}.

 * <p>

 * <b>Offset Z</b>: This formats the offset based on the number of pattern

 * letters. One, two or three letters outputs the hour and minute, without a

 * colon, such as '+0130'. The output will be '+0000' when the offset is zero.

 * Four letters outputs the {@linkplain TextStyle#FULL full} form of localized

 * offset, equivalent to four letters of Offset-O. The output will be the

 * corresponding localized offset text if the offset is zero. Five

 * letters outputs the hour, minute, with optional second if non-zero, with

 * colon. It outputs 'Z' if the offset is zero.

 * Six or more letters throws {@code IllegalArgumentException}.

 * <p>

 * <b>Optional section</b>: The optional section markers work exactly like

 * calling {@link DateTimeFormatterBuilder#optionalStart()} and

 * {@link DateTimeFormatterBuilder#optionalEnd()}.

 * <p>

 * <b>Pad modifier</b>: Modifies the pattern that immediately follows to be

 * padded with spaces. The pad width is determined by the number of pattern

 * letters. This is the same as calling

 * {@link DateTimeFormatterBuilder#padNext(int)}.

 * <p>

 * For example, 'ppH' outputs the hour-of-day padded on the left with spaces to

 * a width of 2.

 * <p>

 * Any unrecognized letter is an error. Any non-letter character, other than

 * '[', ']', '{', '}', '#' and the single quote will be output directly.

 * Despite this, it is recommended to use single quotes around all characters

 * that you want to output directly to ensure that future changes do not break

 * your application.

 *

 * <h3 id="resolving">Resolving</h3>

 * Parsing is implemented as a two-phase operation.

 * First, the text is parsed using the layout defined by the formatter, producing

 * a {@code Map} of field to value, a {@code ZoneId} and a {@code Chronology}.

 * Second, the parsed data is <em>resolved</em>, by validating, combining and

 * simplifying the various fields into more useful ones.

 * <p>

 * Five parsing methods are supplied by this class.

 * Four of these perform both the parse and resolve phases.

 * The fifth method, {@link #parseUnresolved(CharSequence, ParsePosition)},

 * only performs the first phase, leaving the result unresolved.

 * As such, it is essentially a low-level operation.

 * <p>

 * The resolve phase is controlled by two parameters, set on this class.

 * <p>

 * The {@link ResolverStyle} is an enum that offers three different approaches,

 * strict, smart and lenient. The smart option is the default.

 * It can be set using {@link #withResolverStyle(ResolverStyle)}.

 * <p>

 * The {@link #withResolverFields(TemporalField...)} parameter allows the

 * set of fields that will be resolved to be filtered before resolving starts.

 * For example, if the formatter has parsed a year, month, day-of-month

 * and day-of-year, then there are two approaches to resolve a date:

 * (year + month + day-of-month) and (year + day-of-year).

 * The resolver fields allows one of the two approaches to be selected.

 * If no resolver fields are set then both approaches must result in the same date.

 * <p>

 * Resolving separate fields to form a complete date and time is a complex

 * process with behaviour distributed across a number of classes.

 * It follows these steps:

 * <ol>

 * <li>The chronology is determined.

 * The chronology of the result is either the chronology that was parsed,

 * or if no chronology was parsed, it is the chronology set on this class,

 * or if that is null, it is {@code IsoChronology}.

 * <li>The {@code ChronoField} date fields are resolved.

 * This is achieved using {@link Chronology#resolveDate(Map, ResolverStyle)}.

 * Documentation about field resolution is located in the implementation

 * of {@code Chronology}.

 * <li>The {@code ChronoField} time fields are resolved.

 * This is documented on {@link ChronoField} and is the same for all chronologies.

 * <li>Any fields that are not {@code ChronoField} are processed.

 * This is achieved using {@link TemporalField#resolve(Map, TemporalAccessor, ResolverStyle)}.

 * Documentation about field resolution is located in the implementation

 * of {@code TemporalField}.

 * <li>The {@code ChronoField} date and time fields are re-resolved.

 * This allows fields in step four to produce {@code ChronoField} values

 * and have them be processed into dates and times.

 * <li>A {@code LocalTime} is formed if there is at least an hour-of-day available.

 * This involves providing default values for minute, second and fraction of second.

 * <li>Any remaining unresolved fields are cross-checked against any

 * date and/or time that was resolved. Thus, an earlier stage would resolve

 * (year + month + day-of-month) to a date, and this stage would check that

 * day-of-week was valid for the date.

 * <li>If an {@linkplain #parsedExcessDays() excess number of days}

 * was parsed then it is added to the date if a date is available.

 * <li> If a second-based field is present, but {@code LocalTime} was not parsed,

 * then the resolver ensures that milli, micro and nano second values are

 * available to meet the contract of {@link ChronoField}.

 * These will be set to zero if missing.

 * <li>If both date and time were parsed and either an offset or zone is present,

 * the field {@link ChronoField#INSTANT_SECONDS} is created.