View Javadoc
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 }