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