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.ZoneOffset;
  76 import java.time.format.DateTimeBuilder;

  77 
  78 /**
  79  * A standard set of fields.
  80  * <p>
  81  * This set of fields provide field-based access to manipulate a date, time or date-time.
  82  * The standard set of fields can be extended by implementing {@link TemporalField}.
  83  * <p>
  84  * These fields are intended to be applicable in multiple calendar systems.
  85  * For example, most non-ISO calendar systems define dates as a year, month and day,
  86  * just with slightly different rules.
  87  * The documentation of each field explains how it operates.
  88  *
  89  * <h3>Specification for implementors</h3>
  90  * This is a final, immutable and thread-safe enum.
  91  *
  92  * @since 1.8
  93  */
  94 public enum ChronoField implements TemporalField {
  95 
  96     /**
  97      * The nano-of-second.
  98      * <p>
  99      * This counts the nanosecond within the second, from 0 to 999,999,999.
 100      * This field has the same meaning for all calendar systems.
 101      * <p>
 102      * This field is used to represent the nano-of-second handling any fraction of the second.
 103      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 104      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 105      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 106      * <p>
 107      * When this field is used for setting a value, it should set as much precision as the
 108      * object stores, using integer division to remove excess precision.
 109      * For example, if the {@code TemporalAccessor} stores time to millisecond precision,
 110      * then the nano-of-second must be divided by 1,000,000 before replacing the milli-of-second.
 111      */
 112     NANO_OF_SECOND("NanoOfSecond", NANOS, SECONDS, ValueRange.of(0, 999_999_999)),
 113     /**
 114      * The nano-of-day.
 115      * <p>
 116      * This counts the nanosecond within the day, from 0 to (24 * 60 * 60 * 1,000,000,000) - 1.
 117      * This field has the same meaning for all calendar systems.
 118      * <p>
 119      * This field is used to represent the nano-of-day handling any fraction of the second.
 120      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 121      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 122      */
 123     NANO_OF_DAY("NanoOfDay", NANOS, DAYS, ValueRange.of(0, 86400L * 1000_000_000L - 1)),
 124     /**
 125      * The micro-of-second.
 126      * <p>
 127      * This counts the microsecond within the second, from 0 to 999,999.
 128      * This field has the same meaning for all calendar systems.
 129      * <p>
 130      * This field is used to represent the micro-of-second 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_MINUTE}, {@link #SECOND_OF_DAY} or
 133      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 134      * <p>
 135      * When this field is used for setting a value, it should behave in the same way as
 136      * setting {@link #NANO_OF_SECOND} with the value multiplied by 1,000.
 137      */
 138     MICRO_OF_SECOND("MicroOfSecond", MICROS, SECONDS, ValueRange.of(0, 999_999)),
 139     /**
 140      * The micro-of-day.
 141      * <p>
 142      * This counts the microsecond within the day, from 0 to (24 * 60 * 60 * 1,000,000) - 1.
 143      * This field has the same meaning for all calendar systems.
 144      * <p>
 145      * This field is used to represent the micro-of-day handling any fraction of the second.
 146      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 147      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 148      * <p>
 149      * When this field is used for setting a value, it should behave in the same way as
 150      * setting {@link #NANO_OF_DAY} with the value multiplied by 1,000.
 151      */
 152     MICRO_OF_DAY("MicroOfDay", MICROS, DAYS, ValueRange.of(0, 86400L * 1000_000L - 1)),
 153     /**
 154      * The milli-of-second.
 155      * <p>
 156      * This counts the millisecond within the second, from 0 to 999.
 157      * This field has the same meaning for all calendar systems.
 158      * <p>
 159      * This field is used to represent the milli-of-second handling any fraction of the second.
 160      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 161      * they can return a value for {@link #SECOND_OF_MINUTE}, {@link #SECOND_OF_DAY} or
 162      * {@link #INSTANT_SECONDS} filling unknown precision with zero.
 163      * <p>
 164      * When this field is used for setting a value, it should behave in the same way as
 165      * setting {@link #NANO_OF_SECOND} with the value multiplied by 1,000,000.
 166      */
 167     MILLI_OF_SECOND("MilliOfSecond", MILLIS, SECONDS, ValueRange.of(0, 999)),
 168     /**
 169      * The milli-of-day.
 170      * <p>
 171      * This counts the millisecond within the day, from 0 to (24 * 60 * 60 * 1,000) - 1.
 172      * This field has the same meaning for all calendar systems.
 173      * <p>
 174      * This field is used to represent the milli-of-day handling any fraction of the second.
 175      * Implementations of {@code TemporalAccessor} should provide a value for this field if
 176      * they can return a value for {@link #SECOND_OF_DAY} filling unknown precision with zero.
 177      * <p>
 178      * When this field is used for setting a value, it should behave in the same way as
 179      * setting {@link #NANO_OF_DAY} with the value multiplied by 1,000,000.
 180      */
 181     MILLI_OF_DAY("MilliOfDay", MILLIS, DAYS, ValueRange.of(0, 86400L * 1000L - 1)),
 182     /**
 183      * The second-of-minute.
 184      * <p>
 185      * This counts the second within the minute, from 0 to 59.
 186      * This field has the same meaning for all calendar systems.
 187      */
 188     SECOND_OF_MINUTE("SecondOfMinute", SECONDS, MINUTES, ValueRange.of(0, 59)),
 189     /**
 190      * The second-of-day.
 191      * <p>
 192      * This counts the second within the day, from 0 to (24 * 60 * 60) - 1.
 193      * This field has the same meaning for all calendar systems.
 194      */
 195     SECOND_OF_DAY("SecondOfDay", SECONDS, DAYS, ValueRange.of(0, 86400L - 1)),
 196     /**
 197      * The minute-of-hour.
 198      * <p>
 199      * This counts the minute within the hour, from 0 to 59.
 200      * This field has the same meaning for all calendar systems.
 201      */
 202     MINUTE_OF_HOUR("MinuteOfHour", MINUTES, HOURS, ValueRange.of(0, 59)),
 203     /**
 204      * The minute-of-day.
 205      * <p>
 206      * This counts the minute within the day, from 0 to (24 * 60) - 1.
 207      * This field has the same meaning for all calendar systems.
 208      */
 209     MINUTE_OF_DAY("MinuteOfDay", MINUTES, DAYS, ValueRange.of(0, (24 * 60) - 1)),
 210     /**
 211      * The hour-of-am-pm.
 212      * <p>
 213      * This counts the hour within the AM/PM, from 0 to 11.
 214      * This is the hour that would be observed on a standard 12-hour digital clock.
 215      * This field has the same meaning for all calendar systems.
 216      */
 217     HOUR_OF_AMPM("HourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(0, 11)),
 218     /**
 219      * The clock-hour-of-am-pm.
 220      * <p>
 221      * This counts the hour within the AM/PM, from 1 to 12.
 222      * This is the hour that would be observed on a standard 12-hour analog wall clock.
 223      * This field has the same meaning for all calendar systems.
 224      */
 225     CLOCK_HOUR_OF_AMPM("ClockHourOfAmPm", HOURS, HALF_DAYS, ValueRange.of(1, 12)),
 226     /**
 227      * The hour-of-day.
 228      * <p>
 229      * This counts the hour within the day, from 0 to 23.
 230      * This is the hour that would be observed on a standard 24-hour digital clock.
 231      * This field has the same meaning for all calendar systems.
 232      */
 233     HOUR_OF_DAY("HourOfDay", HOURS, DAYS, ValueRange.of(0, 23)),
 234     /**
 235      * The clock-hour-of-day.
 236      * <p>
 237      * This counts the hour within the AM/PM, from 1 to 24.
 238      * This is the hour that would be observed on a 24-hour analog wall clock.
 239      * This field has the same meaning for all calendar systems.
 240      */
 241     CLOCK_HOUR_OF_DAY("ClockHourOfDay", HOURS, DAYS, ValueRange.of(1, 24)),
 242     /**
 243      * The am-pm-of-day.
 244      * <p>
 245      * This counts the AM/PM within the day, from 0 (AM) to 1 (PM).
 246      * This field has the same meaning for all calendar systems.
 247      */
 248     AMPM_OF_DAY("AmPmOfDay", HALF_DAYS, DAYS, ValueRange.of(0, 1)),
 249     /**
 250      * The day-of-week, such as Tuesday.
 251      * <p>
 252      * This represents the standard concept of the day of the week.
 253      * In the default ISO calendar system, this has values from Monday (1) to Sunday (7).
 254      * The {@link DayOfWeek} class can be used to interpret the result.
 255      * <p>
 256      * Most non-ISO calendar systems also define a seven day week that aligns with ISO.
 257      * Those calendar systems must also use the same numbering system, from Monday (1) to
 258      * Sunday (7), which allows {@code DayOfWeek} to be used.
 259      * <p>
 260      * Calendar systems that do not have a standard seven day week should implement this field
 261      * if they have a similar concept of named or numbered days within a period similar
 262      * to a week. It is recommended that the numbering starts from 1.
 263      */
 264     DAY_OF_WEEK("DayOfWeek", DAYS, WEEKS, ValueRange.of(1, 7)),
 265     /**
 266      * The aligned day-of-week within a month.
 267      * <p>
 268      * This represents concept of the count of days within the period of a week
 269      * where the weeks are aligned to the start of the month.
 270      * This field is typically used with {@link #ALIGNED_WEEK_OF_MONTH}.
 271      * <p>
 272      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 273      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 274      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 275      * as the value of this field.
 276      * As such, day-of-month 1 to 7 will have aligned-day-of-week values from 1 to 7.
 277      * And day-of-month 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 278      * <p>
 279      * Calendar systems that do not have a seven day week should typically implement this
 280      * field in the same way, but using the alternate week length.
 281      */
 282     ALIGNED_DAY_OF_WEEK_IN_MONTH("AlignedDayOfWeekInMonth", DAYS, WEEKS, ValueRange.of(1, 7)),
 283     /**
 284      * The aligned day-of-week within a year.
 285      * <p>
 286      * This represents concept of the count of days within the period of a week
 287      * where the weeks are aligned to the start of the year.
 288      * This field is typically used with {@link #ALIGNED_WEEK_OF_YEAR}.
 289      * <p>
 290      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 291      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 292      * Within each of these aligned-weeks, the days are numbered from 1 to 7 and returned
 293      * as the value of this field.
 294      * As such, day-of-year 1 to 7 will have aligned-day-of-week values from 1 to 7.
 295      * And day-of-year 8 to 14 will repeat this with aligned-day-of-week values from 1 to 7.
 296      * <p>
 297      * Calendar systems that do not have a seven day week should typically implement this
 298      * field in the same way, but using the alternate week length.
 299      */
 300     ALIGNED_DAY_OF_WEEK_IN_YEAR("AlignedDayOfWeekInYear", DAYS, WEEKS, ValueRange.of(1, 7)),
 301     /**
 302      * The day-of-month.
 303      * <p>
 304      * This represents the concept of the day within the month.
 305      * In the default ISO calendar system, this has values from 1 to 31 in most months.
 306      * April, June, September, November have days from 1 to 30, while February has days
 307      * from 1 to 28, or 29 in a leap year.
 308      * <p>
 309      * Non-ISO calendar systems should implement this field using the most recognized
 310      * day-of-month values for users of the calendar system.
 311      * Normally, this is a count of days from 1 to the length of the month.
 312      */
 313     DAY_OF_MONTH("DayOfMonth", DAYS, MONTHS, ValueRange.of(1, 28, 31)),
 314     /**
 315      * The day-of-year.
 316      * <p>
 317      * This represents the concept of the day within the year.
 318      * In the default ISO calendar system, this has values from 1 to 365 in standard
 319      * years and 1 to 366 in leap years.
 320      * <p>
 321      * Non-ISO calendar systems should implement this field using the most recognized
 322      * day-of-year values for users of the calendar system.
 323      * Normally, this is a count of days from 1 to the length of the year.
 324      */
 325     DAY_OF_YEAR("DayOfYear", DAYS, YEARS, ValueRange.of(1, 365, 366)),
 326     /**
 327      * The epoch-day, based on the Java epoch of 1970-01-01 (ISO).
 328      * <p>
 329      * This field is the sequential count of days where 1970-01-01 (ISO) is zero.
 330      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 331      * <p>
 332      * This field is strictly defined to have the same meaning in all calendar systems.
 333      * This is necessary to ensure interoperation between calendars.
 334      */
 335     EPOCH_DAY("EpochDay", DAYS, FOREVER, ValueRange.of((long) (Year.MIN_VALUE * 365.25), (long) (Year.MAX_VALUE * 365.25))),
 336     /**
 337      * The aligned week within a month.
 338      * <p>
 339      * This represents concept of the count of weeks within the period of a month
 340      * where the weeks are aligned to the start of the month.
 341      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_MONTH}.
 342      * <p>
 343      * For example, in a calendar systems with a seven day week, the first aligned-week-of-month
 344      * starts on day-of-month 1, the second aligned-week starts on day-of-month 8, and so on.
 345      * Thus, day-of-month values 1 to 7 are in aligned-week 1, while day-of-month values
 346      * 8 to 14 are in aligned-week 2, and so on.
 347      * <p>
 348      * Calendar systems that do not have a seven day week should typically implement this
 349      * field in the same way, but using the alternate week length.
 350      */
 351     ALIGNED_WEEK_OF_MONTH("AlignedWeekOfMonth", WEEKS, MONTHS, ValueRange.of(1, 4, 5)),
 352     /**
 353      * The aligned week within a year.
 354      * <p>
 355      * This represents concept of the count of weeks within the period of a year
 356      * where the weeks are aligned to the start of the year.
 357      * This field is typically used with {@link #ALIGNED_DAY_OF_WEEK_IN_YEAR}.
 358      * <p>
 359      * For example, in a calendar systems with a seven day week, the first aligned-week-of-year
 360      * starts on day-of-year 1, the second aligned-week starts on day-of-year 8, and so on.
 361      * Thus, day-of-year values 1 to 7 are in aligned-week 1, while day-of-year values
 362      * 8 to 14 are in aligned-week 2, and so on.
 363      * <p>
 364      * Calendar systems that do not have a seven day week should typically implement this
 365      * field in the same way, but using the alternate week length.
 366      */
 367     ALIGNED_WEEK_OF_YEAR("AlignedWeekOfYear", WEEKS, YEARS, ValueRange.of(1, 53)),
 368     /**
 369      * The month-of-year, such as March.
 370      * <p>
 371      * This represents the concept of the month within the year.
 372      * In the default ISO calendar system, this has values from January (1) to December (12).
 373      * <p>
 374      * Non-ISO calendar systems should implement this field using the most recognized
 375      * month-of-year values for users of the calendar system.
 376      * Normally, this is a count of months starting from 1.
 377      */
 378     MONTH_OF_YEAR("MonthOfYear", MONTHS, YEARS, ValueRange.of(1, 12)),
 379     /**
 380      * The epoch-month based on the Java epoch of 1970-01-01.
 381      * <p>
 382      * This field is the sequential count of months where January 1970 (ISO) is zero.
 383      * Note that this uses the <i>local</i> time-line, ignoring offset and time-zone.
 384      * <p>
 385      * Non-ISO calendar systems should also implement this field to represent a sequential
 386      * count of months. It is recommended to define zero as the month of 1970-01-01 (ISO).
 387      */
 388     EPOCH_MONTH("EpochMonth", MONTHS, FOREVER, ValueRange.of((Year.MIN_VALUE - 1970L) * 12, (Year.MAX_VALUE - 1970L) * 12L - 1L)),
 389     /**
 390      * The year within the era.
 391      * <p>
 392      * This represents the concept of the year within the era.
 393      * This field is typically used with {@link #ERA}.
 394      * <p>
 395      * The standard mental model for a date is based on three concepts - year, month and day.
 396      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 397      * Note that there is no reference to eras.
 398      * The full model for a date requires four concepts - era, year, month and day. These map onto
 399      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 400      * Whether this field or {@code YEAR} is used depends on which mental model is being used.
 401      * See {@link ChronoLocalDate} for more discussion on this topic.
 402      * <p>
 403      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 404      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 405      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 406      * <p>
 407      * For example, subtracting a year each time yield the following:<br>
 408      * - year-proleptic 2  = 'CE' year-of-era 2<br>
 409      * - year-proleptic 1  = 'CE' year-of-era 1<br>
 410      * - year-proleptic 0  = 'BCE' year-of-era 1<br>
 411      * - year-proleptic -1 = 'BCE' year-of-era 2<br>
 412      * <p>
 413      * Note that the ISO-8601 standard does not actually define eras.
 414      * Note also that the ISO eras do not align with the well-known AD/BC eras due to the
 415      * change between the Julian and Gregorian calendar systems.
 416      * <p>
 417      * Non-ISO calendar systems should implement this field using the most recognized
 418      * year-of-era value for users of the calendar system.
 419      * Since most calendar systems have only two eras, the year-of-era numbering approach
 420      * will typically be the same as that used by the ISO calendar system.
 421      * The year-of-era value should typically always be positive, however this is not required.
 422      */
 423     YEAR_OF_ERA("YearOfEra", YEARS, FOREVER, ValueRange.of(1, Year.MAX_VALUE, Year.MAX_VALUE + 1)),
 424     /**
 425      * The proleptic year, such as 2012.
 426      * <p>
 427      * This represents the concept of the year, counting sequentially and using negative numbers.
 428      * The proleptic year is not interpreted in terms of the era.
 429      * See {@link #YEAR_OF_ERA} for an example showing the mapping from proleptic year to year-of-era.
 430      * <p>
 431      * The standard mental model for a date is based on three concepts - year, month and day.
 432      * These map onto the {@code YEAR}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 433      * Note that there is no reference to eras.
 434      * The full model for a date requires four concepts - era, year, month and day. These map onto
 435      * the {@code ERA}, {@code YEAR_OF_ERA}, {@code MONTH_OF_YEAR} and {@code DAY_OF_MONTH} fields.
 436      * Whether this field or {@code YEAR_OF_ERA} is used depends on which mental model is being used.
 437      * See {@link ChronoLocalDate} for more discussion on this topic.
 438      * <p>
 439      * Non-ISO calendar systems should implement this field as follows.
 440      * If the calendar system has only two eras, before and after a fixed date, then the
 441      * proleptic-year value must be the same as the year-of-era value for the later era,
 442      * and increasingly negative for the earlier era.
 443      * If the calendar system has more than two eras, then the proleptic-year value may be
 444      * defined with any appropriate value, although defining it to be the same as ISO may be
 445      * the best option.
 446      */
 447     YEAR("Year", YEARS, FOREVER, ValueRange.of(Year.MIN_VALUE, Year.MAX_VALUE)),
 448     /**
 449      * The era.
 450      * <p>
 451      * This represents the concept of the era, which is the largest division of the time-line.
 452      * This field is typically used with {@link #YEAR_OF_ERA}.
 453      * <p>
 454      * In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
 455      * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
 456      * The era 'BCE' is the previous era, and the year-of-era runs backwards.
 457      * See {@link #YEAR_OF_ERA} for a full example.
 458      * <p>
 459      * Non-ISO calendar systems should implement this field to define eras.
 460      * The value of the era that was active on 1970-01-01 (ISO) must be assigned the value 1.
 461      * Earlier eras must have sequentially smaller values.
 462      * Later eras must have sequentially larger values,
 463      */
 464     ERA("Era", ERAS, FOREVER, ValueRange.of(0, 1)),
 465     /**
 466      * The instant epoch-seconds.
 467      * <p>
 468      * This represents the concept of the sequential count of seconds where
 469      * 1970-01-01T00:00Z (ISO) is zero.
 470      * This field may be used with {@link #NANO_OF_DAY} to represent the fraction of the day.
 471      * <p>
 472      * An {@link Instant} represents an instantaneous point on the time-line.
 473      * On their own they have no elements which allow a local date-time to be obtained.
 474      * Only when paired with an offset or time-zone can the local date or time be found.
 475      * This field allows the seconds part of the instant to be queried.
 476      * <p>
 477      * This field is strictly defined to have the same meaning in all calendar systems.
 478      * This is necessary to ensure interoperation between calendars.
 479      */
 480     INSTANT_SECONDS("InstantSeconds", SECONDS, FOREVER, ValueRange.of(Long.MIN_VALUE, Long.MAX_VALUE)),
 481     /**
 482      * The offset from UTC/Greenwich.
 483      * <p>
 484      * This represents the concept of the offset in seconds of local time from UTC/Greenwich.
 485      * <p>
 486      * A {@link ZoneOffset} represents the period of time that local time differs from UTC/Greenwich.
 487      * This is usually a fixed number of hours and minutes.
 488      * It is equivalent to the {@link ZoneOffset#getTotalSeconds() total amount} of the offset in seconds.
 489      * For example, during the winter Paris has an offset of {@code +01:00}, which is 3600 seconds.
 490      * <p>
 491      * This field is strictly defined to have the same meaning in all calendar systems.
 492      * This is necessary to ensure interoperation between calendars.
 493      */
 494     OFFSET_SECONDS("OffsetSeconds", SECONDS, FOREVER, ValueRange.of(-18 * 3600, 18 * 3600));
 495 
 496     private final String name;
 497     private final TemporalUnit baseUnit;
 498     private final TemporalUnit rangeUnit;
 499     private final ValueRange range;
 500 
 501     private ChronoField(String name, TemporalUnit baseUnit, TemporalUnit rangeUnit, ValueRange range) {
 502         this.name = name;
 503         this.baseUnit = baseUnit;
 504         this.rangeUnit = rangeUnit;
 505         this.range = range;
 506     }
 507 
 508     //-----------------------------------------------------------------------
 509     @Override
 510     public String getName() {
 511         return name;
 512     }
 513 
 514     @Override
 515     public TemporalUnit getBaseUnit() {
 516         return baseUnit;
 517     }
 518 
 519     @Override
 520     public TemporalUnit getRangeUnit() {
 521         return rangeUnit;
 522     }
 523 

















 524     @Override
 525     public ValueRange range() {
 526         return range;
 527     }
 528 
 529     //-----------------------------------------------------------------------
 530     /**
 531      * Checks if this field represents a component of a date.
 532      *
 533      * @return true if it is a component of a date
 534      */
 535     public boolean isDateField() {
 536         return ordinal() >= DAY_OF_WEEK.ordinal() && ordinal() <= ERA.ordinal();
 537     }
 538 
 539     /**
 540      * Checks if this field represents a component of a time.
 541      *
 542      * @return true if it is a component of a time
 543      */
 544     public boolean isTimeField() {
 545         return ordinal() < DAY_OF_WEEK.ordinal();
 546     }
 547 
 548     //-----------------------------------------------------------------------
 549     /**
 550      * Checks that the specified value is valid for this field.
 551      * <p>
 552      * This validates that the value is within the outer range of valid values
 553      * returned by {@link #range()}.





 554      *
 555      * @param value  the value to check
 556      * @return the value that was passed in
 557      */
 558     public long checkValidValue(long value) {
 559         return range().checkValidValue(value, this);
 560     }
 561 
 562     /**
 563      * Checks that the specified value is valid and fits in an {@code int}.
 564      * <p>
 565      * This validates that the value is within the outer range of valid values
 566      * returned by {@link #range()}.
 567      * It also checks that all valid values are within the bounds of an {@code int}.





 568      *
 569      * @param value  the value to check
 570      * @return the value that was passed in
 571      */
 572     public int checkValidIntValue(long value) {
 573         return range().checkValidIntValue(value, this);
 574     }
 575 
 576     //-----------------------------------------------------------------------
 577     @Override
 578     public boolean doIsSupported(TemporalAccessor temporal) {
 579         return temporal.isSupported(this);
 580     }
 581 
 582     @Override
 583     public ValueRange doRange(TemporalAccessor temporal) {
 584         return temporal.range(this);
 585     }
 586 
 587     @Override
 588     public long doGet(TemporalAccessor temporal) {
 589         return temporal.getLong(this);
 590     }
 591 
 592     @SuppressWarnings("unchecked")
 593     @Override
 594     public <R extends Temporal> R doWith(R temporal, long newValue) {
 595         return (R) temporal.with(this, newValue);
 596     }
 597 
 598     //-----------------------------------------------------------------------
 599     @Override
 600     public boolean resolve(DateTimeBuilder builder, long value) {
 601         return false;  // resolve implemented in builder
 602     }
 603 
 604     //-----------------------------------------------------------------------
 605     @Override
 606     public String toString() {
 607         return getName();
 608     }
 609 
 610 }
--- EOF ---