1 /*
   2  * Copyright (c) 2012, 2013, 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      */
 274     HOUR_OF_AMPM("HourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(0, 11)),
 275     /**
 276      * The clock-hour-of-am-pm.
 277      * <p>
 278      * This counts the hour within the AM/PM, from 1 to 12.
 279      * This is the hour that would be observed on a standard 12-hour analog wall clock.
 280      * This field has the same meaning for all calendar systems.
 281      * <p>
 282      * When parsing this field it behaves equivalent to the following:
 283      * The value is validated from 1 to 12 in strict mode and from
 284      * 0 to 12 in smart mode. In lenient mode the value is not validated.
 285      * The field is converted to an {@code HOUR_OF_AMPM} with the same value,
 286      * unless the value is 12, in which case it is converted to 0.
 287      */
 288     CLOCK_HOUR_OF_AMPM("ClockHourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(1, 12)),
 289     /**
 290      * The hour-of-day.
 291      * <p>
 292      * This counts the hour within the day, from 0 to 23.
 293      * This is the hour that would be observed on a standard 24-hour digital clock.
 294      * This field has the same meaning for all calendar systems.
 295      * <p>
 296      * When parsing this field it behaves equivalent to the following:
 297      * The value is validated in strict and smart mode but not in lenient mode.
 298      * The field is combined with {@code MINUTE_OF_HOUR}, {@code SECOND_OF_MINUTE} and
 299      * {@code NANO_OF_SECOND} to produce a {@code LocalTime}.
 300      * In lenient mode, any excess days are added to the parsed date, or
 301      * made available via {@link java.time.format.DateTimeFormatter#parsedExcessDays()}.
 302      */
 303     HOUR_OF_DAY("HourOfDay", HOURS, DAYS, ValueRange.of(0, 23), "hour"),
 304     /**
 305      * The clock-hour-of-day.
 306      * <p>
 307      * This counts the hour within the AM/PM, from 1 to 24.
 308      * This is the hour that would be observed on a 24-hour analog wall clock.
 309      * This field has the same meaning for all calendar systems.
 310      * <p>
 311      * When parsing this field it behaves equivalent to the following:
 312      * The value is validated from 1 to 24 in strict mode and from
 313      * 0 to 24 in smart mode. In lenient mode the value is not validated.
 314      * The field is converted to an {@code HOUR_OF_DAY} with the same value,
 315      * unless the value is 24, in which case it is converted to 0.
 316      */
 317     CLOCK_HOUR_OF_DAY("ClockHourOfDay", HOURS, DAYS, ValueRange.of(1, 24)),
 318     /**
 319      * The am-pm-of-day.
 320      * <p>
 321      * This counts the AM/PM within the day, from 0 (AM) to 1 (PM).
 322      * This field has the same meaning for all calendar systems.
 323      * <p>
 324      * When parsing this field it behaves equivalent to the following:
 325      * The value is validated from 0 to 1 in strict and smart mode.
 326      * In lenient mode the value is not validated. It is combined with
 327      * {@code HOUR_OF_AMPM} to form {@code HOUR_OF_DAY} by multiplying
 328      * the {AMPM_OF_DAY} value by 12.
 329      */
 330     AMPM_OF_DAY("AmPmOfDay", HALF_DAYS, DAYS, ValueRange.of(0, 1), "dayperiod"),
 331     /**
 332      * The day-of-week, such as Tuesday.
 333      * <p>
 334      * This represents the standard concept of the day of the week.
 335      * In the default ISO calendar system, this has values from Monday (1) to Sunday (7).
 336      * The {@link DayOfWeek} class can be used to interpret the result.
 337      * <p>
 338      * Most non-ISO calendar systems also define a seven day week that aligns with ISO.
 339      * Those calendar systems must also use the same numbering system, from Monday (1) to
 340      * Sunday (7), which allows {@code DayOfWeek} to be used.
 341      * <p>
 342      * Calendar systems that do not have a standard seven day week should implement this field
 343      * if they have a similar concept of named or numbered days within a period similar
 344      * to a week. It is recommended that the numbering starts from 1.
 345      */
 346     DAY_OF_WEEK("DayOfWeek", DAYS, WEEKS, ValueRange.of(1, 7), "weekday"),
 347     /**
 348      * The aligned day-of-week within a month.
 349      * <p>
 350      * This represents concept of the count of days within the period of a week
 351      * where the weeks are aligned to the start of the month.
 352      * This field is typically used with {@link #ALIGNED_WEEK_OF_MONTH}.
 353      * <p>
 354      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 355      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 356      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 357      * as the value of this field.
 358      * As such, day-of-month 1 to 7 will have aligned-day-of-week values from 1 to 7.
 359      * And day-of-month 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 360      * <p>
 361      * Calendar systems that do not have a seven day week should typically implement this
 362      * field in the same way, but using the alternate week length.
 363      */
 364     ALIGNED_DAY_OF_WEEK_IN_MONTH("AlignedDayOfWeekInMonth", DAYS, WEEKS, ValueRange.of(1, 7)),
 365     /**
 366      * The aligned day-of-week within a year.
 367      * <p>
 368      * This represents concept of the count of days within the period of a week
 369      * where the weeks are aligned to the start of the year.
 370      * This field is typically used with {@link #ALIGNED_WEEK_OF_YEAR}.
 371      * <p>
 372      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 373      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 374      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 375      * as the value of this field.
 376      * As such, day-of-year 1 to 7 will have aligned-day-of-week values from 1 to 7.
 377      * And day-of-year 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 378      * <p>
 379      * Calendar systems that do not have a seven day week should typically implement this
 380      * field in the same way, but using the alternate week length.
 381      */
 382     ALIGNED_DAY_OF_WEEK_IN_YEAR("AlignedDayOfWeekInYear", DAYS, WEEKS, ValueRange.of(1, 7)),
 383     /**
 384      * The day-of-month.
 385      * <p>
 386      * This represents the concept of the day within the month.
 387      * In the default ISO calendar system, this has values from 1 to 31 in most months.
 388      * April, June, September, November have days from 1 to 30, while February has days
 389      * from 1 to 28, or 29 in a leap year.
 390      * <p>
 391      * Non-ISO calendar systems should implement this field using the most recognized
 392      * day-of-month values for users of the calendar system.
 393      * Normally, this is a count of days from 1 to the length of the month.
 394      */
 395     DAY_OF_MONTH("DayOfMonth", DAYS, MONTHS, ValueRange.of(1, 28, 31), "day"),
 396     /**
 397      * The day-of-year.
 398      * <p>
 399      * This represents the concept of the day within the year.
 400      * In the default ISO calendar system, this has values from 1 to 365 in standard
 401      * years and 1 to 366 in leap years.
 402      * <p>
 403      * Non-ISO calendar systems should implement this field using the most recognized
 404      * day-of-year values for users of the calendar system.
 405      * Normally, this is a count of days from 1 to the length of the year.
 406      * <p>
 407      * Note that a non-ISO calendar system may have year numbering system that changes
 408      * at a different point to the natural reset in the month numbering. An example
 409      * of this is the Japanese calendar system where a change of era, which resets
 410      * the year number to 1, can happen on any date. The era and year reset also cause
 411      * the day-of-year to be reset to 1, but not the month-of-year or day-of-month.
 412      */
 413     DAY_OF_YEAR("DayOfYear", DAYS, YEARS, ValueRange.of(1, 365, 366)),
 414     /**
 415      * The epoch-day, based on the Java epoch of 1970-01-01 (ISO).
 416      * <p>
 417      * This field is the sequential count of days where 1970-01-01 (ISO) is zero.
 418      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 419      * <p>
 420      * This field is strictly defined to have the same meaning in all calendar systems.
 421      * This is necessary to ensure interoperation between calendars.
 422      */
 423     EPOCH_DAY("EpochDay", DAYS, FOREVER, ValueRange.of((long) (Year.MIN_VALUE * 365.25), (long) (Year.MAX_VALUE * 365.25))),
 424     /**
 425      * The aligned week within a month.
 426      * <p>
 427      * This represents concept of the count of weeks within the period of a month
 428      * where the weeks are aligned to the start of the month.
 429      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_MONTH}.
 430      * <p>
 431      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 432      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 433      * Thus, day-of-month values 1 to 7 are in aligned-week 1, while day-of-month values
 434      * 8 to 14 are in aligned-week 2, and so on.
 435      * <p>
 436      * Calendar systems that do not have a seven day week should typically implement this
 437      * field in the same way, but using the alternate week length.
 438      */
 439     ALIGNED_WEEK_OF_MONTH("AlignedWeekOfMonth", WEEKS, MONTHS, ValueRange.of(1, 4, 5)),
 440     /**
 441      * The aligned week within a year.
 442      * <p>
 443      * This represents concept of the count of weeks within the period of a year
 444      * where the weeks are aligned to the start of the year.
 445      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_YEAR}.
 446      * <p>
 447      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 448      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 449      * Thus, day-of-year values 1 to 7 are in aligned-week 1, while day-of-year values
 450      * 8 to 14 are in aligned-week 2, and so on.
 451      * <p>
 452      * Calendar systems that do not have a seven day week should typically implement this
 453      * field in the same way, but using the alternate week length.
 454      */
 455     ALIGNED_WEEK_OF_YEAR("AlignedWeekOfYear", WEEKS, YEARS, ValueRange.of(1, 53)),
 456     /**
 457      * The month-of-year, such as March.
 458      * <p>
 459      * This represents the concept of the month within the year.
 460      * In the default ISO calendar system, this has values from January (1) to December (12).
 461      * <p>
 462      * Non-ISO calendar systems should implement this field using the most recognized
 463      * month-of-year values for users of the calendar system.
 464      * Normally, this is a count of months starting from 1.
 465      */
 466     MONTH_OF_YEAR("MonthOfYear", MONTHS, YEARS, ValueRange.of(1, 12), "month"),
 467     /**
 468      * The proleptic-month based, counting months sequentially from year 0.
 469      * <p>
 470      * This field is the sequential count of months where the first month
 471      * in proleptic-year zero has the value zero.
 472      * Later months have increasingly larger values.
 473      * Earlier months have increasingly small values.
 474      * There are no gaps or breaks in the sequence of months.
 475      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 476      * <p>
 477      * In the default ISO calendar system, June 2012 would have the value
 478      * {@code (2012 * 12 + 6 - 1)}. This field is primarily for internal use.
 479      * <p>
 480      * Non-ISO calendar systems must implement this field as per the definition above.
 481      * It is just a simple zero-based count of elapsed months from the start of proleptic-year 0.
 482      * All calendar systems with a full proleptic-year definition will have a year zero.
 483      * If the calendar system has a minimum year that excludes year zero, then one must
 484      * be extrapolated in order for this method to be defined.
 485      */
 486     PROLEPTIC_MONTH("ProlepticMonth", MONTHS, FOREVER, ValueRange.of(Year.MIN_VALUE * 12L, Year.MAX_VALUE * 12L + 11)),
 487     /**
 488      * The year within the era.
 489      * <p>
 490      * This represents the concept of the year within the era.
 491      * This field is typically used with {@link #ERA}.
 492      * <p>
 493      * The standard mental model for a date is based on three concepts - year, month and day.
 494      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 495      * Note that there is no reference to eras.
 496      * The full model for a date requires four concepts - era, year, month and day. These map onto
 497      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 498      * Whether this field or {@code YEAR} is used depends on which mental model is being used.
 499      * See {@link ChronoLocalDate} for more discussion on this topic.
 500      * <p>
 501      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 502      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 503      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 504      * <p>
 505      * For example, subtracting a year each time yield the following:<br>
 506      * - year-proleptic 2  = 'CE' year-of-era 2<br>
 507      * - year-proleptic 1  = 'CE' year-of-era 1<br>
 508      * - year-proleptic 0  = 'BCE' year-of-era 1<br>
 509      * - year-proleptic -1 = 'BCE' year-of-era 2<br>
 510      * <p>
 511      * Note that the ISO-8601 standard does not actually define eras.
 512      * Note also that the ISO eras do not align with the well-known AD/BC eras due to the
 513      * change between the Julian and Gregorian calendar systems.
 514      * <p>
 515      * Non-ISO calendar systems should implement this field using the most recognized
 516      * year-of-era value for users of the calendar system.
 517      * Since most calendar systems have only two eras, the year-of-era numbering approach
 518      * will typically be the same as that used by the ISO calendar system.
 519      * The year-of-era value should typically always be positive, however this is not required.
 520      */
 521     YEAR_OF_ERA("YearOfEra", YEARS, FOREVER, ValueRange.of(1, Year.MAX_VALUE, Year.MAX_VALUE + 1)),
 522     /**
 523      * The proleptic year, such as 2012.
 524      * <p>
 525      * This represents the concept of the year, counting sequentially and using negative numbers.
 526      * The proleptic year is not interpreted in terms of the era.
 527      * See {@link #YEAR_OF_ERA} for an example showing the mapping from proleptic year to year-of-era.
 528      * <p>
 529      * The standard mental model for a date is based on three concepts - year, month and day.
 530      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 531      * Note that there is no reference to eras.
 532      * The full model for a date requires four concepts - era, year, month and day. These map onto
 533      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 534      * Whether this field or {@code YEAR_OF_ERA} is used depends on which mental model is being used.
 535      * See {@link ChronoLocalDate} for more discussion on this topic.
 536      * <p>
 537      * Non-ISO calendar systems should implement this field as follows.
 538      * If the calendar system has only two eras, before and after a fixed date, then the
 539      * proleptic-year value must be the same as the year-of-era value for the later era,
 540      * and increasingly negative for the earlier era.
 541      * If the calendar system has more than two eras, then the proleptic-year value may be
 542      * defined with any appropriate value, although defining it to be the same as ISO may be
 543      * the best option.
 544      */
 545     YEAR("Year", YEARS, FOREVER, ValueRange.of(Year.MIN_VALUE, Year.MAX_VALUE), "year"),
 546     /**
 547      * The era.
 548      * <p>
 549      * This represents the concept of the era, which is the largest division of the time-line.
 550      * This field is typically used with {@link #YEAR_OF_ERA}.
 551      * <p>
 552      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 553      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 554      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 555      * See {@link #YEAR_OF_ERA} for a full example.
 556      * <p>
 557      * Non-ISO calendar systems should implement this field to define eras.
 558      * The value of the era that was active on 1970-01-01 (ISO) must be assigned the value 1.
 559      * Earlier eras must have sequentially smaller values.
 560      * Later eras must have sequentially larger values,
 561      */
 562     ERA("Era", ERAS, FOREVER, ValueRange.of(0, 1), "era"),
 563     /**
 564      * The instant epoch-seconds.
 565      * <p>
 566      * This represents the concept of the sequential count of seconds where
 567      * 1970-01-01T00:00Z (ISO) is zero.
 568      * This field may be used with {@link #NANO_OF_SECOND} to represent the fraction of the second.
 569      * <p>
 570      * An {@link Instant} represents an instantaneous point on the time-line.
 571      * On their own, an instant has insufficient information to allow a local date-time to be obtained.
 572      * Only when paired with an offset or time-zone can the local date or time be calculated.
 573      * <p>
 574      * This field is strictly defined to have the same meaning in all calendar systems.
 575      * This is necessary to ensure interoperation between calendars.
 576      */
 577     INSTANT_SECONDS("InstantSeconds", SECONDS, FOREVER, ValueRange.of(Long.MIN_VALUE, Long.MAX_VALUE)),
 578     /**
 579      * The offset from UTC/Greenwich.
 580      * <p>
 581      * This represents the concept of the offset in seconds of local time from UTC/Greenwich.
 582      * <p>
 583      * A {@link ZoneOffset} represents the period of time that local time differs from UTC/Greenwich.
 584      * This is usually a fixed number of hours and minutes.
 585      * It is equivalent to the {@link ZoneOffset#getTotalSeconds() total amount} of the offset in seconds.
 586      * For example, during the winter Paris has an offset of {@code +01:00}, which is 3600 seconds.
 587      * <p>
 588      * This field is strictly defined to have the same meaning in all calendar systems.
 589      * This is necessary to ensure interoperation between calendars.
 590      */
 591     OFFSET_SECONDS("OffsetSeconds", SECONDS, FOREVER, ValueRange.of(-18 * 3600, 18 * 3600));
 592 
 593     private final String name;
 594     private final TemporalUnit baseUnit;
 595     private final TemporalUnit rangeUnit;
 596     private final ValueRange range;
 597     private final String displayNameKey;
 598 
 599     private ChronoField(String name, TemporalUnit baseUnit, TemporalUnit rangeUnit, ValueRange range) {
 600         this.name = name;
 601         this.baseUnit = baseUnit;
 602         this.rangeUnit = rangeUnit;
 603         this.range = range;
 604         this.displayNameKey = null;
 605     }
 606 
 607     private ChronoField(String name, TemporalUnit baseUnit, TemporalUnit rangeUnit,
 608             ValueRange range, String displayNameKey) {
 609         this.name = name;
 610         this.baseUnit = baseUnit;
 611         this.rangeUnit = rangeUnit;
 612         this.range = range;
 613         this.displayNameKey = displayNameKey;
 614     }
 615 
 616     @Override
 617     public String getDisplayName(Locale locale) {
 618         Objects.requireNonNull(locale, "locale");
 619         if (displayNameKey == null) {
 620             return name;
 621         }
 622 
 623         LocaleResources lr = LocaleProviderAdapter.getResourceBundleBased()
 624                                     .getLocaleResources(locale);
 625         ResourceBundle rb = lr.getJavaTimeFormatData();
 626         String key = "field." + displayNameKey;
 627         return rb.containsKey(key) ? rb.getString(key) : name;
 628     }
 629 
 630     @Override
 631     public TemporalUnit getBaseUnit() {
 632         return baseUnit;
 633     }
 634 
 635     @Override
 636     public TemporalUnit getRangeUnit() {
 637         return rangeUnit;
 638     }
 639 
 640     /**
 641      * Gets the range of valid values for the field.
 642      * <p>
 643      * All fields can be expressed as a {@code long} integer.
 644      * This method returns an object that describes the valid range for that value.
 645      * <p>
 646      * This method returns the range of the field in the ISO-8601 calendar system.
 647      * This range may be incorrect for other calendar systems.
 648      * Use {@link Chronology#range(ChronoField)} to access the correct range
 649      * for a different calendar system.
 650      * <p>
 651      * Note that the result only describes the minimum and maximum valid values
 652      * and it is important not to read too much into them. For example, there
 653      * could be values within the range that are invalid for the field.
 654      *
 655      * @return the range of valid values for the field, not null
 656      */
 657     @Override
 658     public ValueRange range() {
 659         return range;
 660     }
 661 
 662     //-----------------------------------------------------------------------
 663     /**
 664      * Checks if this field represents a component of a date.
 665      * <p>
 666      * Fields from day-of-week to era are date-based.
 667      *
 668      * @return true if it is a component of a date
 669      */
 670     @Override
 671     public boolean isDateBased() {
 672         return ordinal() >= DAY_OF_WEEK.ordinal() && ordinal() <= ERA.ordinal();
 673     }
 674 
 675     /**
 676      * Checks if this field represents a component of a time.
 677      * <p>
 678      * Fields from nano-of-second to am-pm-of-day are time-based.
 679      *
 680      * @return true if it is a component of a time
 681      */
 682     @Override
 683     public boolean isTimeBased() {
 684         return ordinal() < DAY_OF_WEEK.ordinal();
 685     }
 686 
 687     //-----------------------------------------------------------------------
 688     /**
 689      * Checks that the specified value is valid for this field.
 690      * <p>
 691      * This validates that the value is within the outer range of valid values
 692      * returned by {@link #range()}.
 693      * <p>
 694      * This method checks against the range of the field in the ISO-8601 calendar system.
 695      * This range may be incorrect for other calendar systems.
 696      * Use {@link Chronology#range(ChronoField)} to access the correct range
 697      * for a different calendar system.
 698      *
 699      * @param value  the value to check
 700      * @return the value that was passed in
 701      */
 702     public long checkValidValue(long value) {
 703         return range().checkValidValue(value, this);
 704     }
 705 
 706     /**
 707      * Checks that the specified value is valid and fits in an {@code int}.
 708      * <p>
 709      * This validates that the value is within the outer range of valid values
 710      * returned by {@link #range()}.
 711      * It also checks that all valid values are within the bounds of an {@code int}.
 712      * <p>
 713      * This method checks against the range of the field in the ISO-8601 calendar system.
 714      * This range may be incorrect for other calendar systems.
 715      * Use {@link Chronology#range(ChronoField)} to access the correct range
 716      * for a different calendar system.
 717      *
 718      * @param value  the value to check
 719      * @return the value that was passed in
 720      */
 721     public int checkValidIntValue(long value) {
 722         return range().checkValidIntValue(value, this);
 723     }
 724 
 725     //-----------------------------------------------------------------------
 726     @Override
 727     public boolean isSupportedBy(TemporalAccessor temporal) {
 728         return temporal.isSupported(this);
 729     }
 730 
 731     @Override
 732     public ValueRange rangeRefinedBy(TemporalAccessor temporal) {
 733         return temporal.range(this);
 734     }
 735 
 736     @Override
 737     public long getFrom(TemporalAccessor temporal) {
 738         return temporal.getLong(this);
 739     }
 740 
 741     @SuppressWarnings("unchecked")
 742     @Override
 743     public <R extends Temporal> R adjustInto(R temporal, long newValue) {
 744         return (R) temporal.with(this, newValue);
 745     }
 746 
 747     //-----------------------------------------------------------------------
 748     @Override
 749     public String toString() {
 750         return name;
 751     }
 752 
 753 }