1 /*
   2  * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * Copyright (c) 2012, Stephen Colebourne & Michael Nascimento Santos
  28  *
  29  * All rights reserved.
  30  *
  31  * Redistribution and use in source and binary forms, with or without
  32  * modification, are permitted provided that the following conditions are met:
  33  *
  34  *  * Redistributions of source code must retain the above copyright notice,
  35  *    this list of conditions and the following disclaimer.
  36  *
  37  *  * Redistributions in binary form must reproduce the above copyright notice,
  38  *    this list of conditions and the following disclaimer in the documentation
  39  *    and/or other materials provided with the distribution.
  40  *
  41  *  * Neither the name of JSR-310 nor the names of its contributors
  42  *    may be used to endorse or promote products derived from this software
  43  *    without specific prior written permission.
  44  *
  45  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  46  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  47  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  48  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  49  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  50  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  51  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  52  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  53  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  54  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  55  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  56  */
  57 package java.time.temporal;
  58 
  59 import static java.time.temporal.ChronoUnit.DAYS;
  60 import static java.time.temporal.ChronoUnit.ERAS;
  61 import static java.time.temporal.ChronoUnit.FOREVER;
  62 import static java.time.temporal.ChronoUnit.HALF_DAYS;
  63 import static java.time.temporal.ChronoUnit.HOURS;
  64 import static java.time.temporal.ChronoUnit.MICROS;
  65 import static java.time.temporal.ChronoUnit.MILLIS;
  66 import static java.time.temporal.ChronoUnit.MINUTES;
  67 import static java.time.temporal.ChronoUnit.MONTHS;
  68 import static java.time.temporal.ChronoUnit.NANOS;
  69 import static java.time.temporal.ChronoUnit.SECONDS;
  70 import static java.time.temporal.ChronoUnit.WEEKS;
  71 import static java.time.temporal.ChronoUnit.YEARS;
  72 
  73 import java.time.DayOfWeek;
  74 import java.time.Instant;
  75 import java.time.Year;
  76 import java.time.ZoneOffset;
  77 import java.time.chrono.ChronoLocalDate;
  78 import java.time.chrono.Chronology;
  79 import java.util.Locale;
  80 import java.util.Objects;
  81 import java.util.ResourceBundle;
  82 import sun.util.locale.provider.LocaleProviderAdapter;
  83 import sun.util.locale.provider.LocaleResources;
  84 
  85 /**
  86  * A standard set of fields.
  87  * <p>
  88  * This set of fields provide field-based access to manipulate a date, time or date-time.
  89  * The standard set of fields can be extended by implementing {@link TemporalField}.
  90  * <p>
  91  * These fields are intended to be applicable in multiple calendar systems.
  92  * For example, most non-ISO calendar systems define dates as a year, month and day,
  93  * just with slightly different rules.
  94  * The documentation of each field explains how it operates.
  95  *
  96  * @implSpec
  97  * This is a final, immutable and thread-safe enum.
  98  *
  99  * @since 1.8
 100  */
 101 public enum ChronoField implements TemporalField {
 102 
 103     /**
 104      * The nano-of-second.
 105      * <p>
 106      * This counts the nanosecond within the second, from 0 to 999,999,999.
 107      * This field has the same meaning for all calendar systems.
 108      * <p>
 109      * This field is used to represent the nano-of-second handling any fraction of the second.
 110      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 111      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 112      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 113      * <p>
 114      * When this field is used for setting a value, it should set as much precision as the
 115      * object stores, using integer division to remove excess precision.
 116      * For example, if the {@code TemporalAccessor} stores time to millisecond precision,
 117      * then the nano-of-second must be divided by 1,000,000 before replacing the milli-of-second.
 118      * <p>
 119      * When parsing this field it behaves equivalent to the following:
 120      * The value is validated in strict and smart mode but not in lenient mode.
 121      * The field is resolved in combination with {@code MILLI_OF_SECOND} and {@code MICRO_OF_SECOND}.
 122      */
 123     NANO_OF_SECOND("NanoOfSecond", NANOS, SECONDS, ValueRange.of(0, 999_999_999)),
 124     /**
 125      * The nano-of-day.
 126      * <p>
 127      * This counts the nanosecond within the day, from 0 to (24 * 60 * 60 * 1,000,000,000) - 1.
 128      * This field has the same meaning for all calendar systems.
 129      * <p>
 130      * This field is used to represent the nano-of-day handling any fraction of the second.
 131      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 132      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 133      * <p>
 134      * When parsing this field it behaves equivalent to the following:
 135      * The value is validated in strict and smart mode but not in lenient mode.
 136      * The value is split to form {@code NANO_OF_SECOND}, {@code SECOND_OF_MINUTE},
 137      * {@code MINUTE_OF_HOUR} and {@code HOUR_OF_DAY} fields.
 138      */
 139     NANO_OF_DAY("NanoOfDay", NANOS, DAYS, ValueRange.of(0, 86400L * 1000_000_000L - 1)),
 140     /**
 141      * The micro-of-second.
 142      * <p>
 143      * This counts the microsecond within the second, from 0 to 999,999.
 144      * This field has the same meaning for all calendar systems.
 145      * <p>
 146      * This field is used to represent the micro-of-second handling any fraction of the second.
 147      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 148      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 149      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 150      * <p>
 151      * When this field is used for setting a value, it should behave in the same way as
 152      * setting {@link #NANO_OF_SECOND} with the value multiplied by 1,000.
 153      * <p>
 154      * When parsing this field it behaves equivalent to the following:
 155      * The value is validated in strict and smart mode but not in lenient mode.
 156      * The field is resolved in combination with {@code MILLI_OF_SECOND} to produce
 157      * {@code NANO_OF_SECOND}.
 158      */
 159     MICRO_OF_SECOND("MicroOfSecond", MICROS, SECONDS, ValueRange.of(0, 999_999)),
 160     /**
 161      * The micro-of-day.
 162      * <p>
 163      * This counts the microsecond within the day, from 0 to (24 * 60 * 60 * 1,000,000) - 1.
 164      * This field has the same meaning for all calendar systems.
 165      * <p>
 166      * This field is used to represent the micro-of-day handling any fraction of the second.
 167      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 168      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 169      * <p>
 170      * When this field is used for setting a value, it should behave in the same way as
 171      * setting {@link #NANO_OF_DAY} with the value multiplied by 1,000.
 172      * <p>
 173      * When parsing this field it behaves equivalent to the following:
 174      * The value is validated in strict and smart mode but not in lenient mode.
 175      * The value is split to form {@code MICRO_OF_SECOND}, {@code SECOND_OF_MINUTE},
 176      * {@code MINUTE_OF_HOUR} and {@code HOUR_OF_DAY} fields.
 177      */
 178     MICRO_OF_DAY("MicroOfDay", MICROS, DAYS, ValueRange.of(0, 86400L * 1000_000L - 1)),
 179     /**
 180      * The milli-of-second.
 181      * <p>
 182      * This counts the millisecond within the second, from 0 to 999.
 183      * This field has the same meaning for all calendar systems.
 184      * <p>
 185      * This field is used to represent the milli-of-second handling any fraction of the second.
 186      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 187      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 188      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 189      * <p>
 190      * When this field is used for setting a value, it should behave in the same way as
 191      * setting {@link #NANO_OF_SECOND} with the value multiplied by 1,000,000.
 192      * <p>
 193      * When parsing this field it behaves equivalent to the following:
 194      * The value is validated in strict and smart mode but not in lenient mode.
 195      * The field is resolved in combination with {@code MICRO_OF_SECOND} to produce
 196      * {@code NANO_OF_SECOND}.
 197      */
 198     MILLI_OF_SECOND("MilliOfSecond", MILLIS, SECONDS, ValueRange.of(0, 999)),
 199     /**
 200      * The milli-of-day.
 201      * <p>
 202      * This counts the millisecond within the day, from 0 to (24 * 60 * 60 * 1,000) - 1.
 203      * This field has the same meaning for all calendar systems.
 204      * <p>
 205      * This field is used to represent the milli-of-day handling any fraction of the second.
 206      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 207      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 208      * <p>
 209      * When this field is used for setting a value, it should behave in the same way as
 210      * setting {@link #NANO_OF_DAY} with the value multiplied by 1,000,000.
 211      * <p>
 212      * When parsing this field it behaves equivalent to the following:
 213      * The value is validated in strict and smart mode but not in lenient mode.
 214      * The value is split to form {@code MILLI_OF_SECOND}, {@code SECOND_OF_MINUTE},
 215      * {@code MINUTE_OF_HOUR} and {@code HOUR_OF_DAY} fields.
 216      */
 217     MILLI_OF_DAY("MilliOfDay", MILLIS, DAYS, ValueRange.of(0, 86400L * 1000L - 1)),
 218     /**
 219      * The second-of-minute.
 220      * <p>
 221      * This counts the second within the minute, from 0 to 59.
 222      * This field has the same meaning for all calendar systems.
 223      * <p>
 224      * When parsing this field it behaves equivalent to the following:
 225      * The value is validated in strict and smart mode but not in lenient mode.
 226      */
 227     SECOND_OF_MINUTE("SecondOfMinute", SECONDS, MINUTES, ValueRange.of(0, 59), "second"),
 228     /**
 229      * The second-of-day.
 230      * <p>
 231      * This counts the second within the day, from 0 to (24 * 60 * 60) - 1.
 232      * This field has the same meaning for all calendar systems.
 233      * <p>
 234      * When parsing this field it behaves equivalent to the following:
 235      * The value is validated in strict and smart mode but not in lenient mode.
 236      * The value is split to form {@code SECOND_OF_MINUTE}, {@code MINUTE_OF_HOUR}
 237      * and {@code HOUR_OF_DAY} fields.
 238      */
 239     SECOND_OF_DAY("SecondOfDay", SECONDS, DAYS, ValueRange.of(0, 86400L - 1)),
 240     /**
 241      * The minute-of-hour.
 242      * <p>
 243      * This counts the minute within the hour, from 0 to 59.
 244      * This field has the same meaning for all calendar systems.
 245      * <p>
 246      * When parsing this field it behaves equivalent to the following:
 247      * The value is validated in strict and smart mode but not in lenient mode.
 248      */
 249     MINUTE_OF_HOUR("MinuteOfHour", MINUTES, HOURS, ValueRange.of(0, 59), "minute"),
 250     /**
 251      * The minute-of-day.
 252      * <p>
 253      * This counts the minute within the day, from 0 to (24 * 60) - 1.
 254      * This field has the same meaning for all calendar systems.
 255      * <p>
 256      * When parsing this field it behaves equivalent to the following:
 257      * The value is validated in strict and smart mode but not in lenient mode.
 258      * The value is split to form {@code MINUTE_OF_HOUR} and {@code HOUR_OF_DAY} fields.
 259      */
 260     MINUTE_OF_DAY("MinuteOfDay", MINUTES, DAYS, ValueRange.of(0, (24 * 60) - 1)),
 261     /**
 262      * The hour-of-am-pm.
 263      * <p>
 264      * This counts the hour within the AM/PM, from 0 to 11.
 265      * This is the hour that would be observed on a standard 12-hour digital clock.
 266      * This field has the same meaning for all calendar systems.
 267      * <p>
 268      * When parsing this field it behaves equivalent to the following:
 269      * The value is validated from 0 to 11 in strict and smart mode.
 270      * In lenient mode the value is not validated. It is combined with
 271      * {@code AMPM_OF_DAY} to form {@code HOUR_OF_DAY} by multiplying
 272      * the {AMPM_OF_DAY} value by 12.
 273      * <p>
 274      * See {@link #CLOCK_HOUR_OF_AMPM} for the related field that counts hours from 1 to 12.
 275      */
 276     HOUR_OF_AMPM("HourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(0, 11)),
 277     /**
 278      * The clock-hour-of-am-pm.
 279      * <p>
 280      * This counts the hour within the AM/PM, from 1 to 12.
 281      * This is the hour that would be observed on a standard 12-hour analog wall clock.
 282      * This field has the same meaning for all calendar systems.
 283      * <p>
 284      * When parsing this field it behaves equivalent to the following:
 285      * The value is validated from 1 to 12 in strict mode and from
 286      * 0 to 12 in smart mode. In lenient mode the value is not validated.
 287      * The field is converted to an {@code HOUR_OF_AMPM} with the same value,
 288      * unless the value is 12, in which case it is converted to 0.
 289      * <p>
 290      * See {@link #HOUR_OF_AMPM} for the related field that counts hours from 0 to 11.
 291      */
 292     CLOCK_HOUR_OF_AMPM("ClockHourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(1, 12)),
 293     /**
 294      * The hour-of-day.
 295      * <p>
 296      * This counts the hour within the day, from 0 to 23.
 297      * This is the hour that would be observed on a standard 24-hour digital clock.
 298      * This field has the same meaning for all calendar systems.
 299      * <p>
 300      * When parsing this field it behaves equivalent to the following:
 301      * The value is validated in strict and smart mode but not in lenient mode.
 302      * The field is combined with {@code MINUTE_OF_HOUR}, {@code SECOND_OF_MINUTE} and
 303      * {@code NANO_OF_SECOND} to produce a {@code LocalTime}.
 304      * In lenient mode, any excess days are added to the parsed date, or
 305      * made available via {@link java.time.format.DateTimeFormatter#parsedExcessDays()}.
 306      * <p>
 307      * See {@link #CLOCK_HOUR_OF_DAY} for the related field that counts hours from 1 to 24.
 308      */
 309     HOUR_OF_DAY("HourOfDay", HOURS, DAYS, ValueRange.of(0, 23), "hour"),
 310     /**
 311      * The clock-hour-of-day.
 312      * <p>
 313      * This counts the hour within the day, from 1 to 24.
 314      * This is the hour that would be observed on a 24-hour analog wall clock.
 315      * This field has the same meaning for all calendar systems.
 316      * <p>
 317      * When parsing this field it behaves equivalent to the following:
 318      * The value is validated from 1 to 24 in strict mode and from
 319      * 0 to 24 in smart mode. In lenient mode the value is not validated.
 320      * The field is converted to an {@code HOUR_OF_DAY} with the same value,
 321      * unless the value is 24, in which case it is converted to 0.
 322      * <p>
 323      * See {@link #HOUR_OF_DAY} for the related field that counts hours from 0 to 23.
 324      */
 325     CLOCK_HOUR_OF_DAY("ClockHourOfDay", HOURS, DAYS, ValueRange.of(1, 24)),
 326     /**
 327      * The am-pm-of-day.
 328      * <p>
 329      * This counts the AM/PM within the day, from 0 (AM) to 1 (PM).
 330      * This field has the same meaning for all calendar systems.
 331      * <p>
 332      * When parsing this field it behaves equivalent to the following:
 333      * The value is validated from 0 to 1 in strict and smart mode.
 334      * In lenient mode the value is not validated. It is combined with
 335      * {@code HOUR_OF_AMPM} to form {@code HOUR_OF_DAY} by multiplying
 336      * the {AMPM_OF_DAY} value by 12.
 337      */
 338     AMPM_OF_DAY("AmPmOfDay", HALF_DAYS, DAYS, ValueRange.of(0, 1), "dayperiod"),
 339     /**
 340      * The day-of-week, such as Tuesday.
 341      * <p>
 342      * This represents the standard concept of the day of the week.
 343      * In the default ISO calendar system, this has values from Monday (1) to Sunday (7).
 344      * The {@link DayOfWeek} class can be used to interpret the result.
 345      * <p>
 346      * Most non-ISO calendar systems also define a seven day week that aligns with ISO.
 347      * Those calendar systems must also use the same numbering system, from Monday (1) to
 348      * Sunday (7), which allows {@code DayOfWeek} to be used.
 349      * <p>
 350      * Calendar systems that do not have a standard seven day week should implement this field
 351      * if they have a similar concept of named or numbered days within a period similar
 352      * to a week. It is recommended that the numbering starts from 1.
 353      */
 354     DAY_OF_WEEK("DayOfWeek", DAYS, WEEKS, ValueRange.of(1, 7), "weekday"),
 355     /**
 356      * The aligned day-of-week within a month.
 357      * <p>
 358      * This represents concept of the count of days within the period of a week
 359      * where the weeks are aligned to the start of the month.
 360      * This field is typically used with {@link #ALIGNED_WEEK_OF_MONTH}.
 361      * <p>
 362      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 363      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 364      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 365      * as the value of this field.
 366      * As such, day-of-month 1 to 7 will have aligned-day-of-week values from 1 to 7.
 367      * And day-of-month 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 368      * <p>
 369      * Calendar systems that do not have a seven day week should typically implement this
 370      * field in the same way, but using the alternate week length.
 371      */
 372     ALIGNED_DAY_OF_WEEK_IN_MONTH("AlignedDayOfWeekInMonth", DAYS, WEEKS, ValueRange.of(1, 7)),
 373     /**
 374      * The aligned day-of-week within a year.
 375      * <p>
 376      * This represents concept of the count of days within the period of a week
 377      * where the weeks are aligned to the start of the year.
 378      * This field is typically used with {@link #ALIGNED_WEEK_OF_YEAR}.
 379      * <p>
 380      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 381      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 382      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 383      * as the value of this field.
 384      * As such, day-of-year 1 to 7 will have aligned-day-of-week values from 1 to 7.
 385      * And day-of-year 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 386      * <p>
 387      * Calendar systems that do not have a seven day week should typically implement this
 388      * field in the same way, but using the alternate week length.
 389      */
 390     ALIGNED_DAY_OF_WEEK_IN_YEAR("AlignedDayOfWeekInYear", DAYS, WEEKS, ValueRange.of(1, 7)),
 391     /**
 392      * The day-of-month.
 393      * <p>
 394      * This represents the concept of the day within the month.
 395      * In the default ISO calendar system, this has values from 1 to 31 in most months.
 396      * April, June, September, November have days from 1 to 30, while February has days
 397      * from 1 to 28, or 29 in a leap year.
 398      * <p>
 399      * Non-ISO calendar systems should implement this field using the most recognized
 400      * day-of-month values for users of the calendar system.
 401      * Normally, this is a count of days from 1 to the length of the month.
 402      */
 403     DAY_OF_MONTH("DayOfMonth", DAYS, MONTHS, ValueRange.of(1, 28, 31), "day"),
 404     /**
 405      * The day-of-year.
 406      * <p>
 407      * This represents the concept of the day within the year.
 408      * In the default ISO calendar system, this has values from 1 to 365 in standard
 409      * years and 1 to 366 in leap years.
 410      * <p>
 411      * Non-ISO calendar systems should implement this field using the most recognized
 412      * day-of-year values for users of the calendar system.
 413      * Normally, this is a count of days from 1 to the length of the year.
 414      * <p>
 415      * Note that a non-ISO calendar system may have year numbering system that changes
 416      * at a different point to the natural reset in the month numbering. An example
 417      * of this is the Japanese calendar system where a change of era, which resets
 418      * the year number to 1, can happen on any date. The era and year reset also cause
 419      * the day-of-year to be reset to 1, but not the month-of-year or day-of-month.
 420      */
 421     DAY_OF_YEAR("DayOfYear", DAYS, YEARS, ValueRange.of(1, 365, 366)),
 422     /**
 423      * The epoch-day, based on the Java epoch of 1970-01-01 (ISO).
 424      * <p>
 425      * This field is the sequential count of days where 1970-01-01 (ISO) is zero.
 426      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 427      * <p>
 428      * This field is strictly defined to have the same meaning in all calendar systems.
 429      * This is necessary to ensure interoperation between calendars.
 430      */
 431     EPOCH_DAY("EpochDay", DAYS, FOREVER, ValueRange.of(-365243219162L , 365241780471L)),
 432     /**
 433      * The aligned week within a month.
 434      * <p>
 435      * This represents concept of the count of weeks within the period of a month
 436      * where the weeks are aligned to the start of the month.
 437      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_MONTH}.
 438      * <p>
 439      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 440      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 441      * Thus, day-of-month values 1 to 7 are in aligned-week 1, while day-of-month values
 442      * 8 to 14 are in aligned-week 2, and so on.
 443      * <p>
 444      * Calendar systems that do not have a seven day week should typically implement this
 445      * field in the same way, but using the alternate week length.
 446      */
 447     ALIGNED_WEEK_OF_MONTH("AlignedWeekOfMonth", WEEKS, MONTHS, ValueRange.of(1, 4, 5)),
 448     /**
 449      * The aligned week within a year.
 450      * <p>
 451      * This represents concept of the count of weeks within the period of a year
 452      * where the weeks are aligned to the start of the year.
 453      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_YEAR}.
 454      * <p>
 455      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 456      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 457      * Thus, day-of-year values 1 to 7 are in aligned-week 1, while day-of-year values
 458      * 8 to 14 are in aligned-week 2, and so on.
 459      * <p>
 460      * Calendar systems that do not have a seven day week should typically implement this
 461      * field in the same way, but using the alternate week length.
 462      */
 463     ALIGNED_WEEK_OF_YEAR("AlignedWeekOfYear", WEEKS, YEARS, ValueRange.of(1, 53)),
 464     /**
 465      * The month-of-year, such as March.
 466      * <p>
 467      * This represents the concept of the month within the year.
 468      * In the default ISO calendar system, this has values from January (1) to December (12).
 469      * <p>
 470      * Non-ISO calendar systems should implement this field using the most recognized
 471      * month-of-year values for users of the calendar system.
 472      * Normally, this is a count of months starting from 1.
 473      */
 474     MONTH_OF_YEAR("MonthOfYear", MONTHS, YEARS, ValueRange.of(1, 12), "month"),
 475     /**
 476      * The proleptic-month based, counting months sequentially from year 0.
 477      * <p>
 478      * This field is the sequential count of months where the first month
 479      * in proleptic-year zero has the value zero.
 480      * Later months have increasingly larger values.
 481      * Earlier months have increasingly small values.
 482      * There are no gaps or breaks in the sequence of months.
 483      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 484      * <p>
 485      * In the default ISO calendar system, June 2012 would have the value
 486      * {@code (2012 * 12 + 6 - 1)}. This field is primarily for internal use.
 487      * <p>
 488      * Non-ISO calendar systems must implement this field as per the definition above.
 489      * It is just a simple zero-based count of elapsed months from the start of proleptic-year 0.
 490      * All calendar systems with a full proleptic-year definition will have a year zero.
 491      * If the calendar system has a minimum year that excludes year zero, then one must
 492      * be extrapolated in order for this method to be defined.
 493      */
 494     PROLEPTIC_MONTH("ProlepticMonth", MONTHS, FOREVER, ValueRange.of(Year.MIN_VALUE * 12L, Year.MAX_VALUE * 12L + 11)),
 495     /**
 496      * The year within the era.
 497      * <p>
 498      * This represents the concept of the year within the era.
 499      * This field is typically used with {@link #ERA}.
 500      * <p>
 501      * The standard mental model for a date is based on three concepts - year, month and day.
 502      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 503      * Note that there is no reference to eras.
 504      * The full model for a date requires four concepts - era, year, month and day. These map onto
 505      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 506      * Whether this field or {@code YEAR} is used depends on which mental model is being used.
 507      * See {@link ChronoLocalDate} for more discussion on this topic.
 508      * <p>
 509      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 510      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 511      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 512      * <p>
 513      * For example, subtracting a year each time yield the following:<br>
 514      * - year-proleptic 2  = 'CE' year-of-era 2<br>
 515      * - year-proleptic 1  = 'CE' year-of-era 1<br>
 516      * - year-proleptic 0  = 'BCE' year-of-era 1<br>
 517      * - year-proleptic -1 = 'BCE' year-of-era 2<br>
 518      * <p>
 519      * Note that the ISO-8601 standard does not actually define eras.
 520      * Note also that the ISO eras do not align with the well-known AD/BC eras due to the
 521      * change between the Julian and Gregorian calendar systems.
 522      * <p>
 523      * Non-ISO calendar systems should implement this field using the most recognized
 524      * year-of-era value for users of the calendar system.
 525      * Since most calendar systems have only two eras, the year-of-era numbering approach
 526      * will typically be the same as that used by the ISO calendar system.
 527      * The year-of-era value should typically always be positive, however this is not required.
 528      */
 529     YEAR_OF_ERA("YearOfEra", YEARS, FOREVER, ValueRange.of(1, Year.MAX_VALUE, Year.MAX_VALUE + 1)),
 530     /**
 531      * The proleptic year, such as 2012.
 532      * <p>
 533      * This represents the concept of the year, counting sequentially and using negative numbers.
 534      * The proleptic year is not interpreted in terms of the era.
 535      * See {@link #YEAR_OF_ERA} for an example showing the mapping from proleptic year to year-of-era.
 536      * <p>
 537      * The standard mental model for a date is based on three concepts - year, month and day.
 538      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 539      * Note that there is no reference to eras.
 540      * The full model for a date requires four concepts - era, year, month and day. These map onto
 541      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 542      * Whether this field or {@code YEAR_OF_ERA} is used depends on which mental model is being used.
 543      * See {@link ChronoLocalDate} for more discussion on this topic.
 544      * <p>
 545      * Non-ISO calendar systems should implement this field as follows.
 546      * If the calendar system has only two eras, before and after a fixed date, then the
 547      * proleptic-year value must be the same as the year-of-era value for the later era,
 548      * and increasingly negative for the earlier era.
 549      * If the calendar system has more than two eras, then the proleptic-year value may be
 550      * defined with any appropriate value, although defining it to be the same as ISO may be
 551      * the best option.
 552      */
 553     YEAR("Year", YEARS, FOREVER, ValueRange.of(Year.MIN_VALUE, Year.MAX_VALUE), "year"),
 554     /**
 555      * The era.
 556      * <p>
 557      * This represents the concept of the era, which is the largest division of the time-line.
 558      * This field is typically used with {@link #YEAR_OF_ERA}.
 559      * <p>
 560      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 561      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 562      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 563      * See {@link #YEAR_OF_ERA} for a full example.
 564      * <p>
 565      * Non-ISO calendar systems should implement this field to define eras.
 566      * The value of the era that was active on 1970-01-01 (ISO) must be assigned the value 1.
 567      * Earlier eras must have sequentially smaller values.
 568      * Later eras must have sequentially larger values,
 569      */
 570     ERA("Era", ERAS, FOREVER, ValueRange.of(0, 1), "era"),
 571     /**
 572      * The instant epoch-seconds.
 573      * <p>
 574      * This represents the concept of the sequential count of seconds where
 575      * 1970-01-01T00:00Z (ISO) is zero.
 576      * This field may be used with {@link #NANO_OF_SECOND} to represent the fraction of the second.
 577      * <p>
 578      * An {@link Instant} represents an instantaneous point on the time-line.
 579      * On their own, an instant has insufficient information to allow a local date-time to be obtained.
 580      * Only when paired with an offset or time-zone can the local date or time be calculated.
 581      * <p>
 582      * This field is strictly defined to have the same meaning in all calendar systems.
 583      * This is necessary to ensure interoperation between calendars.
 584      */
 585     INSTANT_SECONDS("InstantSeconds", SECONDS, FOREVER, ValueRange.of(Long.MIN_VALUE, Long.MAX_VALUE)),
 586     /**
 587      * The offset from UTC/Greenwich.
 588      * <p>
 589      * This represents the concept of the offset in seconds of local time from UTC/Greenwich.
 590      * <p>
 591      * A {@link ZoneOffset} represents the period of time that local time differs from UTC/Greenwich.
 592      * This is usually a fixed number of hours and minutes.
 593      * It is equivalent to the {@link ZoneOffset#getTotalSeconds() total amount} of the offset in seconds.
 594      * For example, during the winter Paris has an offset of {@code +01:00}, which is 3600 seconds.
 595      * <p>
 596      * This field is strictly defined to have the same meaning in all calendar systems.
 597      * This is necessary to ensure interoperation between calendars.
 598      */
 599     OFFSET_SECONDS("OffsetSeconds", SECONDS, FOREVER, ValueRange.of(-18 * 3600, 18 * 3600));
 600 
 601     private final String name;
 602     private final TemporalUnit baseUnit;
 603     private final TemporalUnit rangeUnit;
 604     private final ValueRange range;
 605     private final String displayNameKey;
 606 
 607     private ChronoField(String name, TemporalUnit baseUnit, TemporalUnit rangeUnit, ValueRange range) {
 608         this.name = name;
 609         this.baseUnit = baseUnit;
 610         this.rangeUnit = rangeUnit;
 611         this.range = range;
 612         this.displayNameKey = null;
 613     }
 614 
 615     private ChronoField(String name, TemporalUnit baseUnit, TemporalUnit rangeUnit,
 616             ValueRange range, String displayNameKey) {
 617         this.name = name;
 618         this.baseUnit = baseUnit;
 619         this.rangeUnit = rangeUnit;
 620         this.range = range;
 621         this.displayNameKey = displayNameKey;
 622     }
 623 
 624     @Override
 625     public String getDisplayName(Locale locale) {
 626         Objects.requireNonNull(locale, "locale");
 627         if (displayNameKey == null) {
 628             return name;
 629         }
 630 
 631         LocaleResources lr = LocaleProviderAdapter.getResourceBundleBased()
 632                                     .getLocaleResources(locale);
 633         ResourceBundle rb = lr.getJavaTimeFormatData();
 634         String key = "field." + displayNameKey;
 635         return rb.containsKey(key) ? rb.getString(key) : name;
 636     }
 637 
 638     @Override
 639     public TemporalUnit getBaseUnit() {
 640         return baseUnit;
 641     }
 642 
 643     @Override
 644     public TemporalUnit getRangeUnit() {
 645         return rangeUnit;
 646     }
 647 
 648     /**
 649      * Gets the range of valid values for the field.
 650      * <p>
 651      * All fields can be expressed as a {@code long} integer.
 652      * This method returns an object that describes the valid range for that value.
 653      * <p>
 654      * This method returns the range of the field in the ISO-8601 calendar system.
 655      * This range may be incorrect for other calendar systems.
 656      * Use {@link Chronology#range(ChronoField)} to access the correct range
 657      * for a different calendar system.
 658      * <p>
 659      * Note that the result only describes the minimum and maximum valid values
 660      * and it is important not to read too much into them. For example, there
 661      * could be values within the range that are invalid for the field.
 662      *
 663      * @return the range of valid values for the field, not null
 664      */
 665     @Override
 666     public ValueRange range() {
 667         return range;
 668     }
 669 
 670     //-----------------------------------------------------------------------
 671     /**
 672      * Checks if this field represents a component of a date.
 673      * <p>
 674      * Fields from day-of-week to era are date-based.
 675      *
 676      * @return true if it is a component of a date
 677      */
 678     @Override
 679     public boolean isDateBased() {
 680         return ordinal() >= DAY_OF_WEEK.ordinal() && ordinal() <= ERA.ordinal();
 681     }
 682 
 683     /**
 684      * Checks if this field represents a component of a time.
 685      * <p>
 686      * Fields from nano-of-second to am-pm-of-day are time-based.
 687      *
 688      * @return true if it is a component of a time
 689      */
 690     @Override
 691     public boolean isTimeBased() {
 692         return ordinal() < DAY_OF_WEEK.ordinal();
 693     }
 694 
 695     //-----------------------------------------------------------------------
 696     /**
 697      * Checks that the specified value is valid for this field.
 698      * <p>
 699      * This validates that the value is within the outer range of valid values
 700      * returned by {@link #range()}.
 701      * <p>
 702      * This method checks against the range of the field in the ISO-8601 calendar system.
 703      * This range may be incorrect for other calendar systems.
 704      * Use {@link Chronology#range(ChronoField)} to access the correct range
 705      * for a different calendar system.
 706      *
 707      * @param value  the value to check
 708      * @return the value that was passed in
 709      */
 710     public long checkValidValue(long value) {
 711         return range().checkValidValue(value, this);
 712     }
 713 
 714     /**
 715      * Checks that the specified value is valid and fits in an {@code int}.
 716      * <p>
 717      * This validates that the value is within the outer range of valid values
 718      * returned by {@link #range()}.
 719      * It also checks that all valid values are within the bounds of an {@code int}.
 720      * <p>
 721      * This method checks against the range of the field in the ISO-8601 calendar system.
 722      * This range may be incorrect for other calendar systems.
 723      * Use {@link Chronology#range(ChronoField)} to access the correct range
 724      * for a different calendar system.
 725      *
 726      * @param value  the value to check
 727      * @return the value that was passed in
 728      */
 729     public int checkValidIntValue(long value) {
 730         return range().checkValidIntValue(value, this);
 731     }
 732 
 733     //-----------------------------------------------------------------------
 734     @Override
 735     public boolean isSupportedBy(TemporalAccessor temporal) {
 736         return temporal.isSupported(this);
 737     }
 738 
 739     @Override
 740     public ValueRange rangeRefinedBy(TemporalAccessor temporal) {
 741         return temporal.range(this);
 742     }
 743 
 744     @Override
 745     public long getFrom(TemporalAccessor temporal) {
 746         return temporal.getLong(this);
 747     }
 748 
 749     @SuppressWarnings("unchecked")
 750     @Override
 751     public <R extends Temporal> R adjustInto(R temporal, long newValue) {
 752         return (R) temporal.with(this, newValue);
 753     }
 754 
 755     //-----------------------------------------------------------------------
 756     @Override
 757     public String toString() {
 758         return name;
 759     }
 760 
 761 }