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 /**
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.
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.
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>
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);
|
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 /**
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.
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.
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>
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.getJavaTimeFormatData();
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);
|