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