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