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