1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * This file is available under and governed by the GNU General Public
  28  * License version 2 only, as published by the Free Software Foundation.
  29  * However, the following notice accompanied the original version of this
  30  * file:
  31  *
  32  * Copyright (c) 2011-2012, Stephen Colebourne & Michael Nascimento Santos
  33  *
  34  * All rights reserved.
  35  *
  36  * Redistribution and use in source and binary forms, with or without
  37  * modification, are permitted provided that the following conditions are met:
  38  *
  39  *  * Redistributions of source code must retain the above copyright notice,
  40  *    this list of conditions and the following disclaimer.
  41  *
  42  *  * Redistributions in binary form must reproduce the above copyright notice,
  43  *    this list of conditions and the following disclaimer in the documentation
  44  *    and/or other materials provided with the distribution.
  45  *
  46  *  * Neither the name of JSR-310 nor the names of its contributors
  47  *    may be used to endorse or promote products derived from this software
  48  *    without specific prior written permission.
  49  *
  50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  61  */
  62 package java.time.temporal;
  63 
  64 import static java.time.temporal.ChronoField.DAY_OF_MONTH;
  65 import static java.time.temporal.ChronoField.DAY_OF_WEEK;
  66 import static java.time.temporal.ChronoField.DAY_OF_YEAR;
  67 import static java.time.temporal.ChronoField.EPOCH_DAY;
  68 import static java.time.temporal.ChronoField.MONTH_OF_YEAR;
  69 import static java.time.temporal.ChronoField.YEAR;
  70 import static java.time.temporal.ChronoUnit.DAYS;
  71 import static java.time.temporal.ChronoUnit.FOREVER;
  72 import static java.time.temporal.ChronoUnit.MONTHS;
  73 import static java.time.temporal.ChronoUnit.WEEKS;
  74 import static java.time.temporal.ChronoUnit.YEARS;
  75 
  76 import java.io.InvalidObjectException;
  77 import java.io.Serializable;
  78 import java.time.DayOfWeek;
  79 import java.time.chrono.ChronoLocalDate;
  80 import java.time.chrono.Chronology;
  81 import java.util.Collections;
  82 import java.util.HashMap;
  83 import java.util.Locale;
  84 import java.util.Map;
  85 import java.util.Objects;
  86 import java.util.ResourceBundle;
  87 import java.util.concurrent.ConcurrentHashMap;
  88 import java.util.concurrent.ConcurrentMap;
  89 import sun.util.locale.provider.CalendarDataUtility;
  90 import sun.util.locale.provider.LocaleProviderAdapter;
  91 import sun.util.locale.provider.LocaleResources;
  92 
  93 /**
  94  * Localized definitions of the day-of-week, week-of-month and week-of-year fields.
  95  * <p>
  96  * A standard week is seven days long, but cultures have different definitions for some
  97  * other aspects of a week. This class represents the definition of the week, for the
  98  * purpose of providing {@link TemporalField} instances.
  99  * <p>
 100  * WeekFields provides five fields,
 101  * {@link #dayOfWeek()}, {@link #weekOfMonth()}, {@link #weekOfYear()},
 102  * {@link #weekOfWeekBasedYear()}, and {@link #weekBasedYear()}
 103  * that provide access to the values from any {@linkplain Temporal temporal object}.
 104  * <p>
 105  * The computations for day-of-week, week-of-month, and week-of-year are based
 106  * on the  {@linkplain ChronoField#YEAR proleptic-year},
 107  * {@linkplain ChronoField#MONTH_OF_YEAR month-of-year},
 108  * {@linkplain ChronoField#DAY_OF_MONTH day-of-month}, and
 109  * {@linkplain ChronoField#DAY_OF_WEEK ISO day-of-week} which are based on the
 110  * {@linkplain ChronoField#EPOCH_DAY epoch-day} and the chronology.
 111  * The values may not be aligned with the {@linkplain ChronoField#YEAR_OF_ERA year-of-Era}
 112  * depending on the Chronology.
 113  * <p>A week is defined by:
 114  * <ul>
 115  * <li>The first day-of-week.
 116  * For example, the ISO-8601 standard considers Monday to be the first day-of-week.
 117  * <li>The minimal number of days in the first week.
 118  * For example, the ISO-8601 standard counts the first week as needing at least 4 days.
 119  * </ul><p>
 120  * Together these two values allow a year or month to be divided into weeks.
 121  * <p>
 122  * <h3>Week of Month</h3>
 123  * One field is used: week-of-month.
 124  * The calculation ensures that weeks never overlap a month boundary.
 125  * The month is divided into periods where each period starts on the defined first day-of-week.
 126  * The earliest period is referred to as week 0 if it has less than the minimal number of days
 127  * and week 1 if it has at least the minimal number of days.
 128  * <p>
 129  * <table cellpadding="0" cellspacing="3" border="0" style="text-align: left; width: 50%;">
 130  * <caption>Examples of WeekFields</caption>
 131  * <tr><th>Date</th><td>Day-of-week</td>
 132  *  <td>First day: Monday<br>Minimal days: 4</td><td>First day: Monday<br>Minimal days: 5</td></tr>
 133  * <tr><th>2008-12-31</th><td>Wednesday</td>
 134  *  <td>Week 5 of December 2008</td><td>Week 5 of December 2008</td></tr>
 135  * <tr><th>2009-01-01</th><td>Thursday</td>
 136  *  <td>Week 1 of January 2009</td><td>Week 0 of January 2009</td></tr>
 137  * <tr><th>2009-01-04</th><td>Sunday</td>
 138  *  <td>Week 1 of January 2009</td><td>Week 0 of January 2009</td></tr>
 139  * <tr><th>2009-01-05</th><td>Monday</td>
 140  *  <td>Week 2 of January 2009</td><td>Week 1 of January 2009</td></tr>
 141  * </table>
 142  *
 143  * <h3>Week of Year</h3>
 144  * One field is used: week-of-year.
 145  * The calculation ensures that weeks never overlap a year boundary.
 146  * The year is divided into periods where each period starts on the defined first day-of-week.
 147  * The earliest period is referred to as week 0 if it has less than the minimal number of days
 148  * and week 1 if it has at least the minimal number of days.
 149  *
 150  * <h3>Week Based Year</h3>
 151  * Two fields are used for week-based-year, one for the
 152  * {@link #weekOfWeekBasedYear() week-of-week-based-year} and one for
 153  * {@link #weekBasedYear() week-based-year}.  In a week-based-year, each week
 154  * belongs to only a single year.  Week 1 of a year is the first week that
 155  * starts on the first day-of-week and has at least the minimum number of days.
 156  * The first and last weeks of a year may contain days from the
 157  * previous calendar year or next calendar year respectively.
 158  *
 159  * <table cellpadding="0" cellspacing="3" border="0" style="text-align: left; width: 50%;">
 160  * <caption>Examples of WeekFields for week-based-year</caption>
 161  * <tr><th>Date</th><td>Day-of-week</td>
 162  *  <td>First day: Monday<br>Minimal days: 4</td><td>First day: Monday<br>Minimal days: 5</td></tr>
 163  * <tr><th>2008-12-31</th><td>Wednesday</td>
 164  *  <td>Week 1 of 2009</td><td>Week 53 of 2008</td></tr>
 165  * <tr><th>2009-01-01</th><td>Thursday</td>
 166  *  <td>Week 1 of 2009</td><td>Week 53 of 2008</td></tr>
 167  * <tr><th>2009-01-04</th><td>Sunday</td>
 168  *  <td>Week 1 of 2009</td><td>Week 53 of 2008</td></tr>
 169  * <tr><th>2009-01-05</th><td>Monday</td>
 170  *  <td>Week 2 of 2009</td><td>Week 1 of 2009</td></tr>
 171  * </table>
 172  * <h3>Specification for implementors</h3>
 173  * This class is immutable and thread-safe.
 174  *
 175  * @since 1.8
 176  */
 177 public final class WeekFields implements Serializable {
 178     // implementation notes
 179     // querying week-of-month or week-of-year should return the week value bound within the month/year
 180     // however, setting the week value should be lenient (use plus/minus weeks)
 181     // allow week-of-month outer range [0 to 6]
 182     // allow week-of-year outer range [0 to 54]
 183     // this is because callers shouldn't be expected to know the details of validity
 184 
 185     /**
 186      * The cache of rules by firstDayOfWeek plus minimalDays.
 187      * Initialized first to be available for definition of ISO, etc.
 188      */
 189     private static final ConcurrentMap<String, WeekFields> CACHE = new ConcurrentHashMap<>(4, 0.75f, 2);
 190 
 191     /**
 192      * The ISO-8601 definition, where a week starts on Monday and the first week
 193      * has a minimum of 4 days.
 194      * <p>
 195      * The ISO-8601 standard defines a calendar system based on weeks.
 196      * It uses the week-based-year and week-of-week-based-year concepts to split
 197      * up the passage of days instead of the standard year/month/day.
 198      * <p>
 199      * Note that the first week may start in the previous calendar year.
 200      * Note also that the first few days of a calendar year may be in the
 201      * week-based-year corresponding to the previous calendar year.
 202      * <p>
 203      * This field is an immutable and thread-safe singleton.
 204      */
 205     public static final WeekFields ISO = new WeekFields(DayOfWeek.MONDAY, 4);
 206 
 207     /**
 208      * The common definition of a week that starts on Sunday and the first week
 209      * has a minimum of 1 day.
 210      * <p>
 211      * Defined as starting on Sunday and with a minimum of 1 day in the month.
 212      * This week definition is in use in the US and other European countries.
 213      * <p>
 214      * This field is an immutable and thread-safe singleton.
 215      */
 216     public static final WeekFields SUNDAY_START = WeekFields.of(DayOfWeek.SUNDAY, 1);
 217 
 218     /**
 219      * The unit that represents week-based-years for the purpose of addition and subtraction.
 220      * <p>
 221      * This allows a number of week-based-years to be added to, or subtracted from, a date.
 222      * The unit is equal to either 52 or 53 weeks.
 223      * The estimated duration of a week-based-year is the same as that of a standard ISO
 224      * year at {@code 365.2425 Days}.
 225      * <p>
 226      * The rules for addition add the number of week-based-years to the existing value
 227      * for the week-based-year field retaining the week-of-week-based-year
 228      * and day-of-week, unless the week number it too large for the target year.
 229      * In that case, the week is set to the last week of the year
 230      * with the same day-of-week.
 231      * <p>
 232      * This field is an immutable and thread-safe singleton.
 233      */
 234     public static final TemporalUnit WEEK_BASED_YEARS = IsoFields.WEEK_BASED_YEARS;
 235 
 236     /**
 237      * Serialization version.
 238      */
 239     private static final long serialVersionUID = -1177360819670808121L;
 240 
 241     /**
 242      * The first day-of-week.
 243      */
 244     private final DayOfWeek firstDayOfWeek;
 245     /**
 246      * The minimal number of days in the first week.
 247      */
 248     private final int minimalDays;
 249 
 250     /**
 251      * The field used to access the computed DayOfWeek.
 252      */
 253     private transient final TemporalField dayOfWeek = ComputedDayOfField.ofDayOfWeekField(this);
 254 
 255     /**
 256      * The field used to access the computed WeekOfMonth.
 257      */
 258     private transient final TemporalField weekOfMonth = ComputedDayOfField.ofWeekOfMonthField(this);
 259 
 260     /**
 261      * The field used to access the computed WeekOfYear.
 262      */
 263     private transient final TemporalField weekOfYear = ComputedDayOfField.ofWeekOfYearField(this);
 264 
 265     /**
 266      * The field that represents the week-of-week-based-year.
 267      * <p>
 268      * This field allows the week of the week-based-year value to be queried and set.
 269      * <p>
 270      * This unit is an immutable and thread-safe singleton.
 271      */
 272     private transient final TemporalField weekOfWeekBasedYear = ComputedDayOfField.ofWeekOfWeekBasedYearField(this);
 273 
 274     /**
 275      * The field that represents the week-based-year.
 276      * <p>
 277      * This field allows the week-based-year value to be queried and set.
 278      * <p>
 279      * This unit is an immutable and thread-safe singleton.
 280      */
 281     private transient final TemporalField weekBasedYear = ComputedDayOfField.ofWeekBasedYearField(this);
 282 
 283     /**
 284      * Obtains an instance of {@code WeekFields} appropriate for a locale.
 285      * <p>
 286      * This will look up appropriate values from the provider of localization data.
 287      *
 288      * @param locale  the locale to use, not null
 289      * @return the week-definition, not null
 290      */
 291     public static WeekFields of(Locale locale) {
 292         Objects.requireNonNull(locale, "locale");
 293         locale = new Locale(locale.getLanguage(), locale.getCountry());  // elminate variants
 294 
 295         int calDow = CalendarDataUtility.retrieveFirstDayOfWeek(locale);
 296         DayOfWeek dow = DayOfWeek.SUNDAY.plus(calDow - 1);
 297         int minDays = CalendarDataUtility.retrieveMinimalDaysInFirstWeek(locale);
 298         return WeekFields.of(dow, minDays);
 299     }
 300 
 301     /**
 302      * Obtains an instance of {@code WeekFields} from the first day-of-week and minimal days.
 303      * <p>
 304      * The first day-of-week defines the ISO {@code DayOfWeek} that is day 1 of the week.
 305      * The minimal number of days in the first week defines how many days must be present
 306      * in a month or year, starting from the first day-of-week, before the week is counted
 307      * as the first week. A value of 1 will count the first day of the month or year as part
 308      * of the first week, whereas a value of 7 will require the whole seven days to be in
 309      * the new month or year.
 310      * <p>
 311      * WeekFields instances are singletons; for each unique combination
 312      * of {@code firstDayOfWeek} and {@code minimalDaysInFirstWeek} the
 313      * the same instance will be returned.
 314      *
 315      * @param firstDayOfWeek  the first day of the week, not null
 316      * @param minimalDaysInFirstWeek  the minimal number of days in the first week, from 1 to 7
 317      * @return the week-definition, not null
 318      * @throws IllegalArgumentException if the minimal days value is less than one
 319      *      or greater than 7
 320      */
 321     public static WeekFields of(DayOfWeek firstDayOfWeek, int minimalDaysInFirstWeek) {
 322         String key = firstDayOfWeek.toString() + minimalDaysInFirstWeek;
 323         WeekFields rules = CACHE.get(key);
 324         if (rules == null) {
 325             rules = new WeekFields(firstDayOfWeek, minimalDaysInFirstWeek);
 326             CACHE.putIfAbsent(key, rules);
 327             rules = CACHE.get(key);
 328         }
 329         return rules;
 330     }
 331 
 332     //-----------------------------------------------------------------------
 333     /**
 334      * Creates an instance of the definition.
 335      *
 336      * @param firstDayOfWeek  the first day of the week, not null
 337      * @param minimalDaysInFirstWeek  the minimal number of days in the first week, from 1 to 7
 338      * @throws IllegalArgumentException if the minimal days value is invalid
 339      */
 340     private WeekFields(DayOfWeek firstDayOfWeek, int minimalDaysInFirstWeek) {
 341         Objects.requireNonNull(firstDayOfWeek, "firstDayOfWeek");
 342         if (minimalDaysInFirstWeek < 1 || minimalDaysInFirstWeek > 7) {
 343             throw new IllegalArgumentException("Minimal number of days is invalid");
 344         }
 345         this.firstDayOfWeek = firstDayOfWeek;
 346         this.minimalDays = minimalDaysInFirstWeek;
 347     }
 348 
 349     //-----------------------------------------------------------------------
 350     /**
 351      * Return the singleton WeekFields associated with the
 352      * {@code firstDayOfWeek} and {@code minimalDays}.
 353      * @return the singleton WeekFields for the firstDayOfWeek and minimalDays.
 354      * @throws InvalidObjectException if the serialized object has invalid
 355      *     values for firstDayOfWeek or minimalDays.
 356      */
 357     private Object readResolve() throws InvalidObjectException {
 358         try {
 359             return WeekFields.of(firstDayOfWeek, minimalDays);
 360         } catch (IllegalArgumentException iae) {
 361             throw new InvalidObjectException("Invalid serialized WeekFields: "
 362                     + iae.getMessage());
 363         }
 364     }
 365 
 366     //-----------------------------------------------------------------------
 367     /**
 368      * Gets the first day-of-week.
 369      * <p>
 370      * The first day-of-week varies by culture.
 371      * For example, the US uses Sunday, while France and the ISO-8601 standard use Monday.
 372      * This method returns the first day using the standard {@code DayOfWeek} enum.
 373      *
 374      * @return the first day-of-week, not null
 375      */
 376     public DayOfWeek getFirstDayOfWeek() {
 377         return firstDayOfWeek;
 378     }
 379 
 380     /**
 381      * Gets the minimal number of days in the first week.
 382      * <p>
 383      * The number of days considered to define the first week of a month or year
 384      * varies by culture.
 385      * For example, the ISO-8601 requires 4 days (more than half a week) to
 386      * be present before counting the first week.
 387      *
 388      * @return the minimal number of days in the first week of a month or year, from 1 to 7
 389      */
 390     public int getMinimalDaysInFirstWeek() {
 391         return minimalDays;
 392     }
 393 
 394     //-----------------------------------------------------------------------
 395     /**
 396      * Returns a field to access the day of week,
 397      * computed based on this WeekFields.
 398      * <p>
 399      * The days of week are numbered from 1 to 7.
 400      * Day number 1 is the {@link #getFirstDayOfWeek() first day-of-week}.
 401      *
 402      * @return the field for day-of-week using this week definition, not null
 403      */
 404     public TemporalField dayOfWeek() {
 405         return dayOfWeek;
 406     }
 407 
 408     /**
 409      * Returns a field to access the week of month,
 410      * computed based on this WeekFields.
 411      * <p>
 412      * This represents the concept of the count of weeks within the month where weeks
 413      * start on a fixed day-of-week, such as Monday.
 414      * This field is typically used with {@link WeekFields#dayOfWeek()}.
 415      * <p>
 416      * Week one (1) is the week starting on the {@link WeekFields#getFirstDayOfWeek}
 417      * where there are at least {@link WeekFields#getMinimalDaysInFirstWeek()} days in the month.
 418      * Thus, week one may start up to {@code minDays} days before the start of the month.
 419      * If the first week starts after the start of the month then the period before is week zero (0).
 420      * <p>
 421      * For example:<br>
 422      * - if the 1st day of the month is a Monday, week one starts on the 1st and there is no week zero<br>
 423      * - if the 2nd day of the month is a Monday, week one starts on the 2nd and the 1st is in week zero<br>
 424      * - if the 4th day of the month is a Monday, week one starts on the 4th and the 1st to 3rd is in week zero<br>
 425      * - if the 5th day of the month is a Monday, week two starts on the 5th and the 1st to 4th is in week one<br>
 426      * <p>
 427      * This field can be used with any calendar system.
 428      * @return a TemporalField to access the WeekOfMonth, not null
 429      */
 430     public TemporalField weekOfMonth() {
 431         return weekOfMonth;
 432     }
 433 
 434     /**
 435      * Returns a field to access the week of year,
 436      * computed based on this WeekFields.
 437      * <p>
 438      * This represents the concept of the count of weeks within the year where weeks
 439      * start on a fixed day-of-week, such as Monday.
 440      * This field is typically used with {@link WeekFields#dayOfWeek()}.
 441      * <p>
 442      * Week one(1) is the week starting on the {@link WeekFields#getFirstDayOfWeek}
 443      * where there are at least {@link WeekFields#getMinimalDaysInFirstWeek()} days in the year.
 444      * Thus, week one may start up to {@code minDays} days before the start of the year.
 445      * If the first week starts after the start of the year then the period before is week zero (0).
 446      * <p>
 447      * For example:<br>
 448      * - if the 1st day of the year is a Monday, week one starts on the 1st and there is no week zero<br>
 449      * - if the 2nd day of the year is a Monday, week one starts on the 2nd and the 1st is in week zero<br>
 450      * - if the 4th day of the year is a Monday, week one starts on the 4th and the 1st to 3rd is in week zero<br>
 451      * - if the 5th day of the year is a Monday, week two starts on the 5th and the 1st to 4th is in week one<br>
 452      * <p>
 453      * This field can be used with any calendar system.
 454      * @return a TemporalField to access the WeekOfYear, not null
 455      */
 456     public TemporalField weekOfYear() {
 457         return weekOfYear;
 458     }
 459 
 460     /**
 461      * Returns a field to access the week of a week-based-year,
 462      * computed based on this WeekFields.
 463      * <p>
 464      * This represents the concept of the count of weeks within the year where weeks
 465      * start on a fixed day-of-week, such as Monday and each week belongs to exactly one year.
 466      * This field is typically used with {@link WeekFields#dayOfWeek()} and
 467      * {@link WeekFields#weekBasedYear()}.
 468      * <p>
 469      * Week one(1) is the week starting on the {@link WeekFields#getFirstDayOfWeek}
 470      * where there are at least {@link WeekFields#getMinimalDaysInFirstWeek()} days in the year.
 471      * If the first week starts after the start of the year then the period before
 472      * is in the last week of the previous year.
 473      * <p>
 474      * For example:<br>
 475      * - if the 1st day of the year is a Monday, week one starts on the 1st<br>
 476      * - if the 2nd day of the year is a Monday, week one starts on the 2nd and
 477      *   the 1st is in the last week of the previous year<br>
 478      * - if the 4th day of the year is a Monday, week one starts on the 4th and
 479      *   the 1st to 3rd is in the last week of the previous year<br>
 480      * - if the 5th day of the year is a Monday, week two starts on the 5th and
 481      *   the 1st to 4th is in week one<br>
 482      * <p>
 483      * This field can be used with any calendar system.
 484      * @return a TemporalField to access the week of week-based-year, not null
 485      */
 486     public TemporalField weekOfWeekBasedYear() {
 487         return weekOfWeekBasedYear;
 488     }
 489 
 490     /**
 491      * Returns a field to access the year of a week-based-year,
 492      * computed based on this WeekFields.
 493      * <p>
 494      * This represents the concept of the year where weeks start on a fixed day-of-week,
 495      * such as Monday and each week belongs to exactly one year.
 496      * This field is typically used with {@link WeekFields#dayOfWeek()} and
 497      * {@link WeekFields#weekOfWeekBasedYear()}.
 498      * <p>
 499      * Week one(1) is the week starting on the {@link WeekFields#getFirstDayOfWeek}
 500      * where there are at least {@link WeekFields#getMinimalDaysInFirstWeek()} days in the year.
 501      * Thus, week one may start before the start of the year.
 502      * If the first week starts after the start of the year then the period before
 503      * is in the last week of the previous year.
 504      * <p>
 505      * This field can be used with any calendar system.
 506      * @return a TemporalField to access the year of week-based-year, not null
 507      */
 508     public TemporalField weekBasedYear() {
 509         return weekBasedYear;
 510     }
 511 
 512     /**
 513      * Checks if this WeekFields is equal to the specified object.
 514      * <p>
 515      * The comparison is based on the entire state of the rules, which is
 516      * the first day-of-week and minimal days.
 517      *
 518      * @param object  the other rules to compare to, null returns false
 519      * @return true if this is equal to the specified rules
 520      */
 521     @Override
 522     public boolean equals(Object object) {
 523         if (this == object) {
 524             return true;
 525         }
 526         if (object instanceof WeekFields) {
 527             return hashCode() == object.hashCode();
 528         }
 529         return false;
 530     }
 531 
 532     /**
 533      * A hash code for these rules.
 534      *
 535      * @return a suitable hash code
 536      */
 537     @Override
 538     public int hashCode() {
 539         return firstDayOfWeek.ordinal() * 7 + minimalDays;
 540     }
 541 
 542     //-----------------------------------------------------------------------
 543     /**
 544      * A string representation of this definition.
 545      *
 546      * @return the string representation, not null
 547      */
 548     @Override
 549     public String toString() {
 550         return "WeekFields[" + firstDayOfWeek + ',' + minimalDays + ']';
 551     }
 552 
 553     //-----------------------------------------------------------------------
 554     /**
 555      * Field type that computes DayOfWeek, WeekOfMonth, and WeekOfYear
 556      * based on a WeekFields.
 557      * A separate Field instance is required for each different WeekFields;
 558      * combination of start of week and minimum number of days.
 559      * Constructors are provided to create fields for DayOfWeek, WeekOfMonth,
 560      * and WeekOfYear.
 561      */
 562     static class ComputedDayOfField implements TemporalField {
 563 
 564         /**
 565          * Returns a field to access the day of week,
 566          * computed based on a WeekFields.
 567          * <p>
 568          * The WeekDefintion of the first day of the week is used with
 569          * the ISO DAY_OF_WEEK field to compute week boundaries.
 570          */
 571         static ComputedDayOfField ofDayOfWeekField(WeekFields weekDef) {
 572             return new ComputedDayOfField("DayOfWeek", weekDef, DAYS, WEEKS, DAY_OF_WEEK_RANGE);
 573         }
 574 
 575         /**
 576          * Returns a field to access the week of month,
 577          * computed based on a WeekFields.
 578          * @see WeekFields#weekOfMonth()
 579          */
 580         static ComputedDayOfField ofWeekOfMonthField(WeekFields weekDef) {
 581             return new ComputedDayOfField("WeekOfMonth", weekDef, WEEKS, MONTHS, WEEK_OF_MONTH_RANGE);
 582         }
 583 
 584         /**
 585          * Returns a field to access the week of year,
 586          * computed based on a WeekFields.
 587          * @see WeekFields#weekOfYear()
 588          */
 589         static ComputedDayOfField ofWeekOfYearField(WeekFields weekDef) {
 590             return new ComputedDayOfField("WeekOfYear", weekDef, WEEKS, YEARS, WEEK_OF_YEAR_RANGE);
 591         }
 592 
 593         /**
 594          * Returns a field to access the week of week-based-year,
 595          * computed based on a WeekFields.
 596          * @see WeekFields#weekOfWeekBasedYear()
 597          */
 598         static ComputedDayOfField ofWeekOfWeekBasedYearField(WeekFields weekDef) {
 599             return new ComputedDayOfField("WeekOfWeekBasedYear", weekDef, WEEKS, IsoFields.WEEK_BASED_YEARS, WEEK_OF_YEAR_RANGE);
 600         }
 601 
 602         /**
 603          * Returns a field to access the week of week-based-year,
 604          * computed based on a WeekFields.
 605          * @see WeekFields#weekBasedYear()
 606          */
 607         static ComputedDayOfField ofWeekBasedYearField(WeekFields weekDef) {
 608             return new ComputedDayOfField("WeekBasedYear", weekDef, IsoFields.WEEK_BASED_YEARS, FOREVER, ChronoField.YEAR.range());
 609         }
 610 
 611         /**
 612          * Return a new week-based-year date of the Chronology, year, week-of-year,
 613          * and dow of week.
 614          * @param chrono The chronology of the new date
 615          * @param yowby the year of the week-based-year
 616          * @param wowby the week of the week-based-year
 617          * @param dow the day of the week
 618          * @return a ChronoLocalDate for the requested year, week of year, and day of week
 619          */
 620         private ChronoLocalDate<?> ofWeekBasedYear(Chronology chrono,
 621                 int yowby, int wowby, int dow) {
 622             ChronoLocalDate<?> date = chrono.date(yowby, 1, 1);
 623             int ldow = localizedDayOfWeek(date);
 624             int offset = startOfWeekOffset(1, ldow);
 625 
 626             // Clamp the week of year to keep it in the same year
 627             int yearLen = date.lengthOfYear();
 628             int newYearWeek = computeWeek(offset, yearLen + weekDef.getMinimalDaysInFirstWeek());
 629             wowby = Math.min(wowby, newYearWeek - 1);
 630 
 631             int days = -offset + (dow - 1) + (wowby - 1) * 7;
 632             return date.plus(days, DAYS);
 633         }
 634 
 635         private final String name;
 636         private final WeekFields weekDef;
 637         private final TemporalUnit baseUnit;
 638         private final TemporalUnit rangeUnit;
 639         private final ValueRange range;
 640 
 641         private ComputedDayOfField(String name, WeekFields weekDef, TemporalUnit baseUnit, TemporalUnit rangeUnit, ValueRange range) {
 642             this.name = name;
 643             this.weekDef = weekDef;
 644             this.baseUnit = baseUnit;
 645             this.rangeUnit = rangeUnit;
 646             this.range = range;
 647         }
 648 
 649         private static final ValueRange DAY_OF_WEEK_RANGE = ValueRange.of(1, 7);
 650         private static final ValueRange WEEK_OF_MONTH_RANGE = ValueRange.of(0, 1, 4, 6);
 651         private static final ValueRange WEEK_OF_YEAR_RANGE = ValueRange.of(0, 1, 52, 54);
 652 
 653         @Override
 654         public long getFrom(TemporalAccessor temporal) {
 655             if (rangeUnit == WEEKS) {  // day-of-week
 656                 return localizedDayOfWeek(temporal);
 657             } else if (rangeUnit == MONTHS) {  // week-of-month
 658                 return localizedWeekOfMonth(temporal);
 659             } else if (rangeUnit == YEARS) {  // week-of-year
 660                 return localizedWeekOfYear(temporal);
 661             } else if (rangeUnit == WEEK_BASED_YEARS) {
 662                 return localizedWeekOfWeekBasedYear(temporal);
 663             } else if (rangeUnit == FOREVER) {
 664                 return localizedWeekBasedYear(temporal);
 665             } else {
 666                 throw new IllegalStateException("unreachable, rangeUnit: " + rangeUnit + ", this: " + this);
 667             }
 668         }
 669 
 670         private int localizedDayOfWeek(TemporalAccessor temporal) {
 671             int sow = weekDef.getFirstDayOfWeek().getValue();
 672             int isoDow = temporal.get(DAY_OF_WEEK);
 673             return Math.floorMod(isoDow - sow, 7) + 1;
 674         }
 675 
 676         private long localizedWeekOfMonth(TemporalAccessor temporal) {
 677             int dow = localizedDayOfWeek(temporal);
 678             int dom = temporal.get(DAY_OF_MONTH);
 679             int offset = startOfWeekOffset(dom, dow);
 680             return computeWeek(offset, dom);
 681         }
 682 
 683         private long localizedWeekOfYear(TemporalAccessor temporal) {
 684             int dow = localizedDayOfWeek(temporal);
 685             int doy = temporal.get(DAY_OF_YEAR);
 686             int offset = startOfWeekOffset(doy, dow);
 687             return computeWeek(offset, doy);
 688         }
 689 
 690         /**
 691          * Returns the year of week-based-year for the temporal.
 692          * The year can be the previous year, the current year, or the next year.
 693          * @param temporal a date of any chronology, not null
 694          * @return the year of week-based-year for the date
 695          */
 696         private int localizedWeekBasedYear(TemporalAccessor temporal) {
 697             int dow = localizedDayOfWeek(temporal);
 698             int year = temporal.get(YEAR);
 699             int doy = temporal.get(DAY_OF_YEAR);
 700             int offset = startOfWeekOffset(doy, dow);
 701             int week = computeWeek(offset, doy);
 702             if (week == 0) {
 703                 // Day is in end of week of previous year; return the previous year
 704                 return year - 1;
 705             } else {
 706                 // If getting close to end of year, use higher precision logic
 707                 // Check if date of year is in partial week associated with next year
 708                 ValueRange dayRange = temporal.range(DAY_OF_YEAR);
 709                 int yearLen = (int)dayRange.getMaximum();
 710                 int newYearWeek = computeWeek(offset, yearLen + weekDef.getMinimalDaysInFirstWeek());
 711                 if (week >= newYearWeek) {
 712                     return year + 1;
 713                 }
 714             }
 715             return year;
 716         }
 717 
 718         /**
 719          * Returns the week of week-based-year for the temporal.
 720          * The week can be part of the previous year, the current year,
 721          * or the next year depending on the week start and minimum number
 722          * of days.
 723          * @param temporal  a date of any chronology
 724          * @return the week of the year
 725          * @see #localizedWeekBasedYear(java.time.temporal.TemporalAccessor)
 726          */
 727         private int localizedWeekOfWeekBasedYear(TemporalAccessor temporal) {
 728             int dow = localizedDayOfWeek(temporal);
 729             int doy = temporal.get(DAY_OF_YEAR);
 730             int offset = startOfWeekOffset(doy, dow);
 731             int week = computeWeek(offset, doy);
 732             if (week == 0) {
 733                 // Day is in end of week of previous year
 734                 // Recompute from the last day of the previous year
 735                 ChronoLocalDate date = Chronology.from(temporal).date(temporal);
 736                 date = date.minus(doy, DAYS);   // Back down into previous year
 737                 return localizedWeekOfWeekBasedYear(date);
 738             } else if (week > 50) {
 739                 // If getting close to end of year, use higher precision logic
 740                 // Check if date of year is in partial week associated with next year
 741                 ValueRange dayRange = temporal.range(DAY_OF_YEAR);
 742                 int yearLen = (int)dayRange.getMaximum();
 743                 int newYearWeek = computeWeek(offset, yearLen + weekDef.getMinimalDaysInFirstWeek());
 744                 if (week >= newYearWeek) {
 745                     // Overlaps with week of following year; reduce to week in following year
 746                     week = week - newYearWeek + 1;
 747                 }
 748             }
 749             return week;
 750         }
 751 
 752         /**
 753          * Returns an offset to align week start with a day of month or day of year.
 754          *
 755          * @param day  the day; 1 through infinity
 756          * @param dow  the day of the week of that day; 1 through 7
 757          * @return  an offset in days to align a day with the start of the first 'full' week
 758          */
 759         private int startOfWeekOffset(int day, int dow) {
 760             // offset of first day corresponding to the day of week in first 7 days (zero origin)
 761             int weekStart = Math.floorMod(day - dow, 7);
 762             int offset = -weekStart;
 763             if (weekStart + 1 > weekDef.getMinimalDaysInFirstWeek()) {
 764                 // The previous week has the minimum days in the current month to be a 'week'
 765                 offset = 7 - weekStart;
 766             }
 767             return offset;
 768         }
 769 
 770         /**
 771          * Returns the week number computed from the reference day and reference dayOfWeek.
 772          *
 773          * @param offset the offset to align a date with the start of week
 774          *     from {@link #startOfWeekOffset}.
 775          * @param day  the day for which to compute the week number
 776          * @return the week number where zero is used for a partial week and 1 for the first full week
 777          */
 778         private int computeWeek(int offset, int day) {
 779             return ((7 + offset + (day - 1)) / 7);
 780         }
 781 
 782         @SuppressWarnings("unchecked")
 783         @Override
 784         public <R extends Temporal> R adjustInto(R temporal, long newValue) {
 785             // Check the new value and get the old value of the field
 786             int newVal = range.checkValidIntValue(newValue, this);  // lenient check range
 787             int currentVal = temporal.get(this);
 788             if (newVal == currentVal) {
 789                 return temporal;
 790             }
 791 
 792             if (rangeUnit == FOREVER) {     // replace year of WeekBasedYear
 793                 // Create a new date object with the same chronology,
 794                 // the desired year and the same week and dow.
 795                 int idow = temporal.get(weekDef.dayOfWeek);
 796                 int wowby = temporal.get(weekDef.weekOfWeekBasedYear);
 797                 return (R) ofWeekBasedYear(Chronology.from(temporal), (int)newValue, wowby, idow);
 798             } else {
 799                 // Compute the difference and add that using the base unit of the field
 800                 return (R) temporal.plus(newVal - currentVal, baseUnit);
 801             }
 802         }
 803 
 804         @Override
 805         public Map<TemporalField, Long> resolve(TemporalAccessor temporal, long value) {
 806             int newValue = range.checkValidIntValue(value, this);
 807             int sow = weekDef.getFirstDayOfWeek().getValue();
 808             if (rangeUnit == WEEKS) {  // day-of-week
 809                 int isoDow = Math.floorMod((sow - 1) + (newValue - 1), 7) + 1;
 810                 return Collections.<TemporalField, Long>singletonMap(DAY_OF_WEEK, (long) isoDow);
 811             }
 812             if (temporal.isSupported(DAY_OF_WEEK) == false) {
 813                 return null;
 814             }
 815             Chronology chrono = Chronology.from(temporal);  // defaults to ISO
 816             int dow = localizedDayOfWeek(temporal);
 817             if (temporal.isSupported(YEAR)) {
 818                 int year = temporal.get(YEAR);
 819                 if (rangeUnit == MONTHS) {  // week-of-month
 820                     if (temporal.isSupported(MONTH_OF_YEAR) == false) {
 821                         return null;
 822                     }
 823                     int month = temporal.get(ChronoField.MONTH_OF_YEAR);
 824                 @SuppressWarnings("rawtypes")
 825                     ChronoLocalDate date = chrono.date(year, month, 1);
 826                     int dateDow = localizedDayOfWeek(date);
 827                     long weeks = newValue - localizedWeekOfMonth(date);
 828                     int days = dow - dateDow;
 829                     date = date.plus(weeks * 7 + days, DAYS);
 830                     Map<TemporalField, Long> result = new HashMap<>(4, 1.0f);
 831                     result.put(EPOCH_DAY, date.toEpochDay());
 832                     result.put(YEAR, null);
 833                     result.put(MONTH_OF_YEAR, null);
 834                     result.put(DAY_OF_WEEK, null);
 835                     return result;
 836                 } else if (rangeUnit == YEARS) {  // week-of-year
 837                 @SuppressWarnings("rawtypes")
 838                     ChronoLocalDate date = chrono.date(year, 1, 1);
 839                     int dateDow = localizedDayOfWeek(date);
 840                     long weeks = newValue - localizedWeekOfYear(date);
 841                     int days = dow - dateDow;
 842                     date = date.plus(weeks * 7 + days, DAYS);
 843                     Map<TemporalField, Long> result = new HashMap<>(4, 1.0f);
 844                     result.put(EPOCH_DAY, date.toEpochDay());
 845                     result.put(YEAR, null);
 846                     result.put(DAY_OF_WEEK, null);
 847                     return result;
 848                 }
 849             } else if (rangeUnit == WEEK_BASED_YEARS || rangeUnit == FOREVER) {
 850                 if (temporal.isSupported(weekDef.weekBasedYear) &&
 851                     temporal.isSupported(weekDef.weekOfWeekBasedYear)) {
 852                     // week-of-week-based-year and year-of-week-based-year
 853                     int yowby = temporal.get(weekDef.weekBasedYear);
 854                     int wowby = temporal.get(weekDef.weekOfWeekBasedYear);
 855                     ChronoLocalDate<?> date = ofWeekBasedYear(Chronology.from(temporal), yowby, wowby, dow);
 856 
 857                     Map<TemporalField, Long> result = new HashMap<>(4, 1.0f);
 858                     result.put(EPOCH_DAY, date.toEpochDay());
 859                     result.put(DAY_OF_WEEK, null);
 860                     result.put(weekDef.weekOfWeekBasedYear, null);
 861                     result.put(weekDef.weekBasedYear, null);
 862                     return result;
 863                 }
 864             }
 865             return null;
 866         }
 867 
 868         //-----------------------------------------------------------------------
 869         @Override
 870         public String getName() {
 871             return name;
 872         }
 873 
 874         @Override
 875         public String getDisplayName(Locale locale) {
 876             Objects.requireNonNull(locale, "locale");
 877             if (rangeUnit == YEARS) {  // only have values for week-of-year
 878                 LocaleResources lr = LocaleProviderAdapter.getResourceBundleBased()
 879                         .getLocaleResources(locale);
 880                 ResourceBundle rb = lr.getJavaTimeFormatData();
 881                 return rb.containsKey("field.week") ? rb.getString("field.week") : getName();
 882             }
 883             return getName();
 884         }
 885 
 886         @Override
 887         public TemporalUnit getBaseUnit() {
 888             return baseUnit;
 889         }
 890 
 891         @Override
 892         public TemporalUnit getRangeUnit() {
 893             return rangeUnit;
 894         }
 895 
 896         @Override
 897         public boolean isDateBased() {
 898             return true;
 899         }
 900 
 901         @Override
 902         public ValueRange range() {
 903             return range;
 904         }
 905 
 906         //-----------------------------------------------------------------------
 907         @Override
 908         public boolean isSupportedBy(TemporalAccessor temporal) {
 909             if (temporal.isSupported(DAY_OF_WEEK)) {
 910                 if (rangeUnit == WEEKS) {  // day-of-week
 911                     return true;
 912                 } else if (rangeUnit == MONTHS) {  // week-of-month
 913                     return temporal.isSupported(DAY_OF_MONTH);
 914                 } else if (rangeUnit == YEARS) {  // week-of-year
 915                     return temporal.isSupported(DAY_OF_YEAR);
 916                 } else if (rangeUnit == WEEK_BASED_YEARS) {
 917                     return temporal.isSupported(DAY_OF_YEAR);
 918                 } else if (rangeUnit == FOREVER) {
 919                     return temporal.isSupported(YEAR);
 920                 }
 921             }
 922             return false;
 923         }
 924 
 925         @Override
 926         public ValueRange rangeRefinedBy(TemporalAccessor temporal) {
 927             if (rangeUnit == ChronoUnit.WEEKS) {  // day-of-week
 928                 return range;
 929             } else if (rangeUnit == MONTHS) {  // week-of-month
 930                 return rangeByWeek(temporal, DAY_OF_MONTH);
 931             } else if (rangeUnit == YEARS) {  // week-of-year
 932                 return rangeByWeek(temporal, DAY_OF_YEAR);
 933             } else if (rangeUnit == WEEK_BASED_YEARS) {
 934                 return rangeWeekOfWeekBasedYear(temporal);
 935             } else if (rangeUnit == FOREVER) {
 936                 return YEAR.range();
 937             } else {
 938                 throw new IllegalStateException("unreachable, rangeUnit: " + rangeUnit + ", this: " + this);
 939             }
 940         }
 941 
 942         /**
 943          * Map the field range to a week range
 944          * @param temporal the temporal
 945          * @param field the field to get the range of
 946          * @return the ValueRange with the range adjusted to weeks.
 947          */
 948         private ValueRange rangeByWeek(TemporalAccessor temporal, TemporalField field) {
 949             int dow = localizedDayOfWeek(temporal);
 950             int offset = startOfWeekOffset(temporal.get(field), dow);
 951             ValueRange fieldRange = temporal.range(field);
 952             return ValueRange.of(computeWeek(offset, (int) fieldRange.getMinimum()),
 953                     computeWeek(offset, (int) fieldRange.getMaximum()));
 954         }
 955 
 956         /**
 957          * Map the field range to a week range of a week year.
 958          * @param temporal  the temporal
 959          * @param field  the field to get the range of
 960          * @return the ValueRange with the range adjusted to weeks.
 961          */
 962         private ValueRange rangeWeekOfWeekBasedYear(TemporalAccessor temporal) {
 963             if (!temporal.isSupported(DAY_OF_YEAR)) {
 964                 return WEEK_OF_YEAR_RANGE;
 965             }
 966             int dow = localizedDayOfWeek(temporal);
 967             int doy = temporal.get(DAY_OF_YEAR);
 968             int offset = startOfWeekOffset(doy, dow);
 969             int week = computeWeek(offset, doy);
 970             if (week == 0) {
 971                 // Day is in end of week of previous year
 972                 // Recompute from the last day of the previous year
 973                 ChronoLocalDate date = Chronology.from(temporal).date(temporal);
 974                 date = date.minus(doy + 7, DAYS);   // Back down into previous year
 975                 return rangeWeekOfWeekBasedYear(date);
 976             }
 977             // Check if day of year is in partial week associated with next year
 978             ValueRange dayRange = temporal.range(DAY_OF_YEAR);
 979             int yearLen = (int)dayRange.getMaximum();
 980             int newYearWeek = computeWeek(offset, yearLen + weekDef.getMinimalDaysInFirstWeek());
 981 
 982             if (week >= newYearWeek) {
 983                 // Overlaps with weeks of following year; recompute from a week in following year
 984                 ChronoLocalDate date = Chronology.from(temporal).date(temporal);
 985                 date = date.plus(yearLen - doy + 1 + 7, ChronoUnit.DAYS);
 986                 return rangeWeekOfWeekBasedYear(date);
 987             }
 988             return ValueRange.of(1, newYearWeek-1);
 989         }
 990 
 991         //-----------------------------------------------------------------------
 992         @Override
 993         public String toString() {
 994             return getName() + "[" + weekDef.toString() + "]";
 995         }
 996     }
 997 }