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