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