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






 629     public String toString() {
 630         return getName();
 631     }
 632 
 633 }
--- EOF ---