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) 2007-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;

    63 

    64 import static java.time.LocalTime.SECONDS_PER_DAY;

    65 import static java.time.temporal.ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH;

    66 import static java.time.temporal.ChronoField.ALIGNED_DAY_OF_WEEK_IN_YEAR;

    67 import static java.time.temporal.ChronoField.ALIGNED_WEEK_OF_MONTH;

    68 import static java.time.temporal.ChronoField.ALIGNED_WEEK_OF_YEAR;

    69 import static java.time.temporal.ChronoField.DAY_OF_MONTH;

    70 import static java.time.temporal.ChronoField.DAY_OF_YEAR;

    71 import static java.time.temporal.ChronoField.EPOCH_DAY;

    72 import static java.time.temporal.ChronoField.ERA;

    73 import static java.time.temporal.ChronoField.MONTH_OF_YEAR;

    74 import static java.time.temporal.ChronoField.PROLEPTIC_MONTH;

    75 import static java.time.temporal.ChronoField.YEAR;

    76 

    77 import java.io.DataInput;

    78 import java.io.DataOutput;

    79 import java.io.IOException;

    80 import java.io.InvalidObjectException;

    81 import java.io.ObjectInputStream;

    82 import java.io.Serializable;

    83 import java.time.chrono.ChronoLocalDate;

    84 import java.time.chrono.Era;

    85 import java.time.chrono.IsoChronology;

    86 import java.time.format.DateTimeFormatter;

    87 import java.time.format.DateTimeParseException;

    88 import java.time.temporal.ChronoField;

    89 import java.time.temporal.ChronoUnit;

    90 import java.time.temporal.Temporal;

    91 import java.time.temporal.TemporalAccessor;

    92 import java.time.temporal.TemporalAdjuster;

    93 import java.time.temporal.TemporalAmount;

    94 import java.time.temporal.TemporalField;

    95 import java.time.temporal.TemporalQueries;

    96 import java.time.temporal.TemporalQuery;

    97 import java.time.temporal.TemporalUnit;

    98 import java.time.temporal.UnsupportedTemporalTypeException;

    99 import java.time.temporal.ValueRange;

   100 import java.time.zone.ZoneOffsetTransition;

   101 import java.time.zone.ZoneRules;

   102 import java.util.Objects;

   103 

   104 /**

   105  * A date without a time-zone in the ISO-8601 calendar system,

   106  * such as {@code 2007-12-03}.

   107  * <p>

   108  * {@code LocalDate} is an immutable date-time object that represents a date,

   109  * often viewed as year-month-day. Other date fields, such as day-of-year,

   110  * day-of-week and week-of-year, can also be accessed.

   111  * For example, the value "2nd October 2007" can be stored in a {@code LocalDate}.

   112  * <p>

   113  * This class does not store or represent a time or time-zone.

   114  * Instead, it is a description of the date, as used for birthdays.

   115  * It cannot represent an instant on the time-line without additional information

   116  * such as an offset or time-zone.

   117  * <p>

   118  * The ISO-8601 calendar system is the modern civil calendar system used today

   119  * in most of the world. It is equivalent to the proleptic Gregorian calendar

   120  * system, in which today's rules for leap years are applied for all time.

   121  * For most applications written today, the ISO-8601 rules are entirely suitable.

   122  * However, any application that makes use of historical dates, and requires them

   123  * to be accurate will find the ISO-8601 approach unsuitable.

   124  *

   125  * <p>

   126  * This is a <a href="{@docRoot}/java/lang/doc-files/ValueBased.html">value-based</a>

   127  * class; use of identity-sensitive operations (including reference equality

   128  * ({@code ==}), identity hash code, or synchronization) on instances of

   129  * {@code LocalDate} may have unpredictable results and should be avoided.

   130  * The {@code equals} method should be used for comparisons.

   131  *

   132  * @implSpec

   133  * This class is immutable and thread-safe.

   134  *

   135  * @since 1.8

   136  */

   137 public final class LocalDate

   138         implements Temporal, TemporalAdjuster, ChronoLocalDate, Serializable {

   139 

   140     /**

   141      * The minimum supported {@code LocalDate}, '-999999999-01-01'.

   142      * This could be used by an application as a "far past" date.

   143      */

   144     public static final LocalDate MIN = LocalDate.of(Year.MIN_VALUE, 1, 1);

   145     /**

   146      * The maximum supported {@code LocalDate}, '+999999999-12-31'.

   147      * This could be used by an application as a "far future" date.

   148      */

   149     public static final LocalDate MAX = LocalDate.of(Year.MAX_VALUE, 12, 31);

   150 

   151     /**

   152      * Serialization version.

   153      */

   154     private static final long serialVersionUID = 2942565459149668126L;

   155     /**

   156      * The number of days in a 400 year cycle.

   157      */

   158     private static final int DAYS_PER_CYCLE = 146097;

   159     /**

   160      * The number of days from year zero to year 1970.

   161      * There are five 400 year cycles from year zero to 2000.

   162      * There are 7 leap years from 1970 to 2000.

   163      */

   164     static final long DAYS_0000_TO_1970 = (DAYS_PER_CYCLE * 5L) - (30L * 365L + 7L);

   165 

   166     /**

   167      * The year.

   168      */

   169     private final int year;

   170     /**

   171      * The month-of-year.

   172      */

   173     private final short month;

   174     /**

   175      * The day-of-month.

   176      */

   177     private final short day;

   178 

   179     //-----------------------------------------------------------------------

   180     /**

   181      * Obtains the current date from the system clock in the default time-zone.

   182      * <p>

   183      * This will query the {@link Clock#systemDefaultZone() system clock} in the default

   184      * time-zone to obtain the current date.

   185      * <p>

   186      * Using this method will prevent the ability to use an alternate clock for testing

   187      * because the clock is hard-coded.

   188      *

   189      * @return the current date using the system clock and default time-zone, not null

   190      */

   191     public static LocalDate now() {

   192         return now(Clock.systemDefaultZone());

   193     }

   194 

   195     /**

   196      * Obtains the current date from the system clock in the specified time-zone.

   197      * <p>

   198      * This will query the {@link Clock#system(ZoneId) system clock} to obtain the current date.

   199      * Specifying the time-zone avoids dependence on the default time-zone.

   200      * <p>

   201      * Using this method will prevent the ability to use an alternate clock for testing

   202      * because the clock is hard-coded.

   203      *

   204      * @param zone  the zone ID to use, not null

   205      * @return the current date using the system clock, not null

   206      */

   207     public static LocalDate now(ZoneId zone) {

   208         return now(Clock.system(zone));

   209     }

   210 

   211     /**

   212      * Obtains the current date from the specified clock.

   213      * <p>

   214      * This will query the specified clock to obtain the current date - today.

   215      * Using this method allows the use of an alternate clock for testing.

   216      * The alternate clock may be introduced using {@link Clock dependency injection}.

   217      *

   218      * @param clock  the clock to use, not null

   219      * @return the current date, not null

   220      */

   221     public static LocalDate now(Clock clock) {

   222         Objects.requireNonNull(clock, "clock");

   223         // inline to avoid creating object and Instant checks

   224         final Instant now = clock.instant();  // called once

   225         ZoneOffset offset = clock.getZone().getRules().getOffset(now);

   226         long epochSec = now.getEpochSecond() + offset.getTotalSeconds();  // overflow caught later

   227         long epochDay = Math.floorDiv(epochSec, SECONDS_PER_DAY);

   228         return LocalDate.ofEpochDay(epochDay);

   229     }

   230 

   231     //-----------------------------------------------------------------------

   232     /**

   233      * Obtains an instance of {@code LocalDate} from a year, month and day.

   234      * <p>

   235      * This returns a {@code LocalDate} with the specified year, month and day-of-month.

   236      * The day must be valid for the year and month, otherwise an exception will be thrown.

   237      *

   238      * @param year  the year to represent, from MIN_YEAR to MAX_YEAR

   239      * @param month  the month-of-year to represent, not null

   240      * @param dayOfMonth  the day-of-month to represent, from 1 to 31

   241      * @return the local date, not null

   242      * @throws DateTimeException if the value of any field is out of range,

   243      *  or if the day-of-month is invalid for the month-year

   244      */

   245     public static LocalDate of(int year, Month month, int dayOfMonth) {

   246         YEAR.checkValidValue(year);

   247         Objects.requireNonNull(month, "month");

   248         DAY_OF_MONTH.checkValidValue(dayOfMonth);

   249         return create(year, month.getValue(), dayOfMonth);

   250     }

   251 

   252     /**

   253      * Obtains an instance of {@code LocalDate} from a year, month and day.

   254      * <p>

   255      * This returns a {@code LocalDate} with the specified year, month and day-of-month.

   256      * The day must be valid for the year and month, otherwise an exception will be thrown.

   257      *

   258      * @param year  the year to represent, from MIN_YEAR to MAX_YEAR

   259      * @param month  the month-of-year to represent, from 1 (January) to 12 (December)

   260      * @param dayOfMonth  the day-of-month to represent, from 1 to 31

   261      * @return the local date, not null

   262      * @throws DateTimeException if the value of any field is out of range,

   263      *  or if the day-of-month is invalid for the month-year

   264      */

   265     public static LocalDate of(int year, int month, int dayOfMonth) {

   266         YEAR.checkValidValue(year);

   267         MONTH_OF_YEAR.checkValidValue(month);

   268         DAY_OF_MONTH.checkValidValue(dayOfMonth);

   269         return create(year, month, dayOfMonth);

   270     }

   271 

   272     //-----------------------------------------------------------------------

   273     /**

   274      * Obtains an instance of {@code LocalDate} from a year and day-of-year.

   275      * <p>

   276      * This returns a {@code LocalDate} with the specified year and day-of-year.

   277      * The day-of-year must be valid for the year, otherwise an exception will be thrown.

   278      *

   279      * @param year  the year to represent, from MIN_YEAR to MAX_YEAR

   280      * @param dayOfYear  the day-of-year to represent, from 1 to 366

   281      * @return the local date, not null

   282      * @throws DateTimeException if the value of any field is out of range,

   283      *  or if the day-of-year is invalid for the year

   284      */

   285     public static LocalDate ofYearDay(int year, int dayOfYear) {

   286         YEAR.checkValidValue(year);

   287         DAY_OF_YEAR.checkValidValue(dayOfYear);

   288         boolean leap = IsoChronology.INSTANCE.isLeapYear(year);

   289         if (dayOfYear == 366 && leap == false) {

   290             throw new DateTimeException("Invalid date 'DayOfYear 366' as '" + year + "' is not a leap year");

   291         }

   292         Month moy = Month.of((dayOfYear - 1) / 31 + 1);

   293         int monthEnd = moy.firstDayOfYear(leap) + moy.length(leap) - 1;

   294         if (dayOfYear > monthEnd) {

   295             moy = moy.plus(1);

   296         }

   297         int dom = dayOfYear - moy.firstDayOfYear(leap) + 1;

   298         return new LocalDate(year, moy.getValue(), dom);

   299     }

   300 

   301     //-----------------------------------------------------------------------

   302     /**

   303      * Obtains an instance of {@code LocalDate} from the epoch day count.

   304      * <p>

   305      * This returns a {@code LocalDate} with the specified epoch-day.

   306      * The {@link ChronoField#EPOCH_DAY EPOCH_DAY} is a simple incrementing count

   307      * of days where day 0 is 1970-01-01. Negative numbers represent earlier days.

   308      *

   309      * @param epochDay  the Epoch Day to convert, based on the epoch 1970-01-01

   310      * @return the local date, not null

   311      * @throws DateTimeException if the epoch day exceeds the supported date range

   312      */

   313     public static LocalDate ofEpochDay(long epochDay) {

   314         long zeroDay = epochDay + DAYS_0000_TO_1970;

   315         // find the march-based year

   316         zeroDay -= 60;  // adjust to 0000-03-01 so leap day is at end of four year cycle

   317         long adjust = 0;

   318         if (zeroDay < 0) {

   319             // adjust negative years to positive for calculation

   320             long adjustCycles = (zeroDay + 1) / DAYS_PER_CYCLE - 1;

   321             adjust = adjustCycles * 400;

   322             zeroDay += -adjustCycles * DAYS_PER_CYCLE;

   323         }

   324         long yearEst = (400 * zeroDay + 591) / DAYS_PER_CYCLE;

   325         long doyEst = zeroDay - (365 * yearEst + yearEst / 4 - yearEst / 100 + yearEst / 400);

   326         if (doyEst < 0) {

   327             // fix estimate

   328             yearEst--;

   329             doyEst = zeroDay - (365 * yearEst + yearEst / 4 - yearEst / 100 + yearEst / 400);

   330         }

   331         yearEst += adjust;  // reset any negative year

   332         int marchDoy0 = (int) doyEst;

   333 

   334         // convert march-based values back to january-based

   335         int marchMonth0 = (marchDoy0 * 5 + 2) / 153;

   336         int month = (marchMonth0 + 2) % 12 + 1;

   337         int dom = marchDoy0 - (marchMonth0 * 306 + 5) / 10 + 1;

   338         yearEst += marchMonth0 / 10;

   339 

   340         // check year now we are certain it is correct

   341         int year = YEAR.checkValidIntValue(yearEst);

   342         return new LocalDate(year, month, dom);

   343     }

   344 

   345     //-----------------------------------------------------------------------

   346     /**

   347      * Obtains an instance of {@code LocalDate} from a temporal object.

   348      * <p>

   349      * This obtains a local date based on the specified temporal.

   350      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,

   351      * which this factory converts to an instance of {@code LocalDate}.

   352      * <p>

   353      * The conversion uses the {@link TemporalQueries#localDate()} query, which relies

   354      * on extracting the {@link ChronoField#EPOCH_DAY EPOCH_DAY} field.

   355      * <p>

   356      * This method matches the signature of the functional interface {@link TemporalQuery}

   357      * allowing it to be used as a query via method reference, {@code LocalDate::from}.

   358      *

   359      * @param temporal  the temporal object to convert, not null

   360      * @return the local date, not null

   361      * @throws DateTimeException if unable to convert to a {@code LocalDate}

   362      */

   363     public static LocalDate from(TemporalAccessor temporal) {

   364         Objects.requireNonNull(temporal, "temporal");

   365         LocalDate date = temporal.query(TemporalQueries.localDate());

   366         if (date == null) {

   367             throw new DateTimeException("Unable to obtain LocalDate from TemporalAccessor: " +

   368                     temporal + " of type " + temporal.getClass().getName());

   369         }

   370         return date;

   371     }

   372 

   373     //-----------------------------------------------------------------------

   374     /**

   375      * Obtains an instance of {@code LocalDate} from a text string such as {@code 2007-12-03}.

   376      * <p>

   377      * The string must represent a valid date and is parsed using

   378      * {@link java.time.format.DateTimeFormatter#ISO_LOCAL_DATE}.

   379      *

   380      * @param text  the text to parse such as "2007-12-03", not null

   381      * @return the parsed local date, not null

   382      * @throws DateTimeParseException if the text cannot be parsed

   383      */

   384     public static LocalDate parse(CharSequence text) {

   385         return parse(text, DateTimeFormatter.ISO_LOCAL_DATE);

   386     }

   387 

   388     /**

   389      * Obtains an instance of {@code LocalDate} from a text string using a specific formatter.

   390      * <p>

   391      * The text is parsed using the formatter, returning a date.

   392      *

   393      * @param text  the text to parse, not null

   394      * @param formatter  the formatter to use, not null

   395      * @return the parsed local date, not null

   396      * @throws DateTimeParseException if the text cannot be parsed

   397      */

   398     public static LocalDate parse(CharSequence text, DateTimeFormatter formatter) {

   399         Objects.requireNonNull(formatter, "formatter");

   400         return formatter.parse(text, LocalDate::from);

   401     }

   402 

   403     //-----------------------------------------------------------------------

   404     /**

   405      * Creates a local date from the year, month and day fields.

   406      *

   407      * @param year  the year to represent, validated from MIN_YEAR to MAX_YEAR

   408      * @param month  the month-of-year to represent, from 1 to 12, validated

   409      * @param dayOfMonth  the day-of-month to represent, validated from 1 to 31

   410      * @return the local date, not null

   411      * @throws DateTimeException if the day-of-month is invalid for the month-year

   412      */

   413     private static LocalDate create(int year, int month, int dayOfMonth) {

   414         if (dayOfMonth > 28) {

   415             int dom = 31;

   416             switch (month) {

   417                 case 2:

   418                     dom = (IsoChronology.INSTANCE.isLeapYear(year) ? 29 : 28);

   419                     break;

   420                 case 4:

   421                 case 6:

   422                 case 9:

   423                 case 11:

   424                     dom = 30;

   425                     break;

   426             }

   427             if (dayOfMonth > dom) {

   428                 if (dayOfMonth == 29) {

   429                     throw new DateTimeException("Invalid date 'February 29' as '" + year + "' is not a leap year");

   430                 } else {

   431                     throw new DateTimeException("Invalid date '" + Month.of(month).name() + " " + dayOfMonth + "'");

   432                 }

   433             }

   434         }

   435         return new LocalDate(year, month, dayOfMonth);

   436     }

   437 

   438     /**

   439      * Resolves the date, resolving days past the end of month.

   440      *

   441      * @param year  the year to represent, validated from MIN_YEAR to MAX_YEAR

   442      * @param month  the month-of-year to represent, validated from 1 to 12

   443      * @param day  the day-of-month to represent, validated from 1 to 31

   444      * @return the resolved date, not null

   445      */

   446     private static LocalDate resolvePreviousValid(int year, int month, int day) {

   447         switch (month) {

   448             case 2:

   449                 day = Math.min(day, IsoChronology.INSTANCE.isLeapYear(year) ? 29 : 28);

   450                 break;

   451             case 4:

   452             case 6:

   453             case 9:

   454             case 11:

   455                 day = Math.min(day, 30);

   456                 break;

   457         }

   458         return new LocalDate(year, month, day);

   459     }

   460 

   461     /**

   462      * Constructor, previously validated.

   463      *

   464      * @param year  the year to represent, from MIN_YEAR to MAX_YEAR

   465      * @param month  the month-of-year to represent, not null

   466      * @param dayOfMonth  the day-of-month to represent, valid for year-month, from 1 to 31

   467      */

   468     private LocalDate(int year, int month, int dayOfMonth) {

   469         this.year = year;

   470         this.month = (short) month;

   471         this.day = (short) dayOfMonth;

   472     }

   473 

   474     //-----------------------------------------------------------------------

   475     /**

   476      * Checks if the specified field is supported.

   477      * <p>

   478      * This checks if this date can be queried for the specified field.

   479      * If false, then calling the {@link #range(TemporalField) range},

   480      * {@link #get(TemporalField) get} and {@link #with(TemporalField, long)}

   481      * methods will throw an exception.

   482      * <p>

   483      * If the field is a {@link ChronoField} then the query is implemented here.

   484      * The supported fields are:

   485      * <ul>

   486      * <li>{@code DAY_OF_WEEK}

   487      * <li>{@code ALIGNED_DAY_OF_WEEK_IN_MONTH}

   488      * <li>{@code ALIGNED_DAY_OF_WEEK_IN_YEAR}

   489      * <li>{@code DAY_OF_MONTH}

   490      * <li>{@code DAY_OF_YEAR}

   491      * <li>{@code EPOCH_DAY}

   492      * <li>{@code ALIGNED_WEEK_OF_MONTH}

   493      * <li>{@code ALIGNED_WEEK_OF_YEAR}

   494      * <li>{@code MONTH_OF_YEAR}

   495      * <li>{@code PROLEPTIC_MONTH}

   496      * <li>{@code YEAR_OF_ERA}

   497      * <li>{@code YEAR}

   498      * <li>{@code ERA}

   499      * </ul>

   500      * All other {@code ChronoField} instances will return false.

   501      * <p>

   502      * If the field is not a {@code ChronoField}, then the result of this method

   503      * is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)}

   504      * passing {@code this} as the argument.

   505      * Whether the field is supported is determined by the field.

   506      *

   507      * @param field  the field to check, null returns false

   508      * @return true if the field is supported on this date, false if not

   509      */

   510     @Override  // override for Javadoc

   511     public boolean isSupported(TemporalField field) {

   512         return ChronoLocalDate.super.isSupported(field);

   513     }

   514 

   515     /**

   516      * Checks if the specified unit is supported.

   517      * <p>

   518      * This checks if the specified unit can be added to, or subtracted from, this date.

   519      * If false, then calling the {@link #plus(long, TemporalUnit)} and

   520      * {@link #minus(long, TemporalUnit) minus} methods will throw an exception.

   521      * <p>

   522      * If the unit is a {@link ChronoUnit} then the query is implemented here.

   523      * The supported units are:

   524      * <ul>

   525      * <li>{@code DAYS}

   526      * <li>{@code WEEKS}

   527      * <li>{@code MONTHS}

   528      * <li>{@code YEARS}

   529      * <li>{@code DECADES}

   530      * <li>{@code CENTURIES}

   531      * <li>{@code MILLENNIA}

   532      * <li>{@code ERAS}

   533      * </ul>

   534      * All other {@code ChronoUnit} instances will return false.

   535      * <p>

   536      * If the unit is not a {@code ChronoUnit}, then the result of this method

   537      * is obtained by invoking {@code TemporalUnit.isSupportedBy(Temporal)}

   538      * passing {@code this} as the argument.

   539      * Whether the unit is supported is determined by the unit.

   540      *

   541      * @param unit  the unit to check, null returns false

   542      * @return true if the unit can be added/subtracted, false if not

   543      */

   544     @Override  // override for Javadoc

   545     public boolean isSupported(TemporalUnit unit) {

   546         return ChronoLocalDate.super.isSupported(unit);

   547     }

   548 

   549     //-----------------------------------------------------------------------

   550     /**

   551      * Gets the range of valid values for the specified field.

   552      * <p>

   553      * The range object expresses the minimum and maximum valid values for a field.

   554      * This date is used to enhance the accuracy of the returned range.

   555      * If it is not possible to return the range, because the field is not supported

   556      * or for some other reason, an exception is thrown.

   557      * <p>

   558      * If the field is a {@link ChronoField} then the query is implemented here.

   559      * The {@link #isSupported(TemporalField) supported fields} will return

   560      * appropriate range instances.

   561      * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

   562      * <p>

   563      * If the field is not a {@code ChronoField}, then the result of this method

   564      * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)}

   565      * passing {@code this} as the argument.

   566      * Whether the range can be obtained is determined by the field.

   567      *

   568      * @param field  the field to query the range for, not null

   569      * @return the range of valid values for the field, not null

   570      * @throws DateTimeException if the range for the field cannot be obtained

   571      * @throws UnsupportedTemporalTypeException if the field is not supported

   572      */

   573     @Override

   574     public ValueRange range(TemporalField field) {

   575         if (field instanceof ChronoField) {

   576             ChronoField f = (ChronoField) field;

   577             if (f.isDateBased()) {

   578                 switch (f) {

   579                     case DAY_OF_MONTH: return ValueRange.of(1, lengthOfMonth());

   580                     case DAY_OF_YEAR: return ValueRange.of(1, lengthOfYear());

   581                     case ALIGNED_WEEK_OF_MONTH: return ValueRange.of(1, getMonth() == Month.FEBRUARY && isLeapYear() == false ? 4 : 5);

   582                     case YEAR_OF_ERA:

   583                         return (getYear() <= 0 ? ValueRange.of(1, Year.MAX_VALUE + 1) : ValueRange.of(1, Year.MAX_VALUE));

   584                 }

   585                 return field.range();

   586             }

   587             throw new UnsupportedTemporalTypeException("Unsupported field: " + field);

   588         }

   589         return field.rangeRefinedBy(this);

   590     }

   591 

   592     /**

   593      * Gets the value of the specified field from this date as an {@code int}.

   594      * <p>

   595      * This queries this date for the value of the specified field.

   596      * The returned value will always be within the valid range of values for the field.

   597      * If it is not possible to return the value, because the field is not supported

   598      * or for some other reason, an exception is thrown.

   599      * <p>

   600      * If the field is a {@link ChronoField} then the query is implemented here.

   601      * The {@link #isSupported(TemporalField) supported fields} will return valid

   602      * values based on this date, except {@code EPOCH_DAY} and {@code PROLEPTIC_MONTH}

   603      * which are too large to fit in an {@code int} and throw an {@code UnsupportedTemporalTypeException}.

   604      * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

   605      * <p>

   606      * If the field is not a {@code ChronoField}, then the result of this method

   607      * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}

   608      * passing {@code this} as the argument. Whether the value can be obtained,

   609      * and what the value represents, is determined by the field.

   610      *

   611      * @param field  the field to get, not null

   612      * @return the value for the field

   613      * @throws DateTimeException if a value for the field cannot be obtained or

   614      *         the value is outside the range of valid values for the field

   615      * @throws UnsupportedTemporalTypeException if the field is not supported or

   616      *         the range of values exceeds an {@code int}

   617      * @throws ArithmeticException if numeric overflow occurs

   618      */

   619     @Override  // override for Javadoc and performance

   620     public int get(TemporalField field) {

   621         if (field instanceof ChronoField) {

   622             return get0(field);

   623         }

   624         return ChronoLocalDate.super.get(field);

   625     }

   626 

   627     /**

   628      * Gets the value of the specified field from this date as a {@code long}.

   629      * <p>

   630      * This queries this date for the value of the specified field.

   631      * If it is not possible to return the value, because the field is not supported

   632      * or for some other reason, an exception is thrown.

   633      * <p>

   634      * If the field is a {@link ChronoField} then the query is implemented here.

   635      * The {@link #isSupported(TemporalField) supported fields} will return valid

   636      * values based on this date.

   637      * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

   638      * <p>

   639      * If the field is not a {@code ChronoField}, then the result of this method

   640      * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}

   641      * passing {@code this} as the argument. Whether the value can be obtained,

   642      * and what the value represents, is determined by the field.

   643      *

   644      * @param field  the field to get, not null

   645      * @return the value for the field

   646      * @throws DateTimeException if a value for the field cannot be obtained

   647      * @throws UnsupportedTemporalTypeException if the field is not supported

   648      * @throws ArithmeticException if numeric overflow occurs

   649      */

   650     @Override

   651     public long getLong(TemporalField field) {

   652         if (field instanceof ChronoField) {

   653             if (field == EPOCH_DAY) {

   654                 return toEpochDay();

   655             }

   656             if (field == PROLEPTIC_MONTH) {

   657                 return getProlepticMonth();

   658             }

   659             return get0(field);

   660         }

   661         return field.getFrom(this);

   662     }

   663 

   664     private int get0(TemporalField field) {

   665         switch ((ChronoField) field) {

   666             case DAY_OF_WEEK: return getDayOfWeek().getValue();

   667             case ALIGNED_DAY_OF_WEEK_IN_MONTH: return ((day - 1) % 7) + 1;

   668             case ALIGNED_DAY_OF_WEEK_IN_YEAR: return ((getDayOfYear() - 1) % 7) + 1;

   669             case DAY_OF_MONTH: return day;

   670             case DAY_OF_YEAR: return getDayOfYear();

   671             case EPOCH_DAY: throw new UnsupportedTemporalTypeException("Invalid field 'EpochDay' for get() method, use getLong() instead");

   672             case ALIGNED_WEEK_OF_MONTH: return ((day - 1) / 7) + 1;

   673             case ALIGNED_WEEK_OF_YEAR: return ((getDayOfYear() - 1) / 7) + 1;

   674             case MONTH_OF_YEAR: return month;

   675             case PROLEPTIC_MONTH: throw new UnsupportedTemporalTypeException("Invalid field 'ProlepticMonth' for get() method, use getLong() instead");

   676             case YEAR_OF_ERA: return (year >= 1 ? year : 1 - year);

   677             case YEAR: return year;

   678             case ERA: return (year >= 1 ? 1 : 0);

   679         }

   680         throw new UnsupportedTemporalTypeException("Unsupported field: " + field);

   681     }

   682 

   683     private long getProlepticMonth() {

   684         return (year * 12L + month - 1);

   685     }

   686 

   687     //-----------------------------------------------------------------------

   688     /**

   689      * Gets the chronology of this date, which is the ISO calendar system.

   690      * <p>

   691      * The {@code Chronology} represents the calendar system in use.

   692      * The ISO-8601 calendar system is the modern civil calendar system used today

   693      * in most of the world. It is equivalent to the proleptic Gregorian calendar

   694      * system, in which today's rules for leap years are applied for all time.

   695      *

   696      * @return the ISO chronology, not null

   697      */

   698     @Override

   699     public IsoChronology getChronology() {

   700         return IsoChronology.INSTANCE;

   701     }

   702 

   703     /**

   704      * Gets the era applicable at this date.

   705      * <p>

   706      * The official ISO-8601 standard does not define eras, however {@code IsoChronology} does.

   707      * It defines two eras, 'CE' from year one onwards and 'BCE' from year zero backwards.

   708      * Since dates before the Julian-Gregorian cutover are not in line with history,

   709      * the cutover between 'BCE' and 'CE' is also not aligned with the commonly used

   710      * eras, often referred to using 'BC' and 'AD'.

   711      * <p>

   712      * Users of this class should typically ignore this method as it exists primarily

   713      * to fulfill the {@link ChronoLocalDate} contract where it is necessary to support

   714      * the Japanese calendar system.

   715      * <p>

   716      * The returned era will be a singleton capable of being compared with the constants

   717      * in {@link IsoChronology} using the {@code ==} operator.

   718      *

   719      * @return the {@code IsoChronology} era constant applicable at this date, not null

   720      */

   721     @Override // override for Javadoc

   722     public Era getEra() {

   723         return ChronoLocalDate.super.getEra();

   724     }

   725 

   726     /**

   727      * Gets the year field.

   728      * <p>

   729      * This method returns the primitive {@code int} value for the year.

   730      * <p>

   731      * The year returned by this method is proleptic as per {@code get(YEAR)}.

   732      * To obtain the year-of-era, use {@code get(YEAR_OF_ERA)}.

   733      *

   734      * @return the year, from MIN_YEAR to MAX_YEAR

   735      */

   736     public int getYear() {

   737         return year;

   738     }

   739 

   740     /**

   741      * Gets the month-of-year field from 1 to 12.

   742      * <p>

   743      * This method returns the month as an {@code int} from 1 to 12.

   744      * Application code is frequently clearer if the enum {@link Month}

   745      * is used by calling {@link #getMonth()}.

   746      *

   747      * @return the month-of-year, from 1 to 12

   748      * @see #getMonth()

   749      */

   750     public int getMonthValue() {

   751         return month;

   752     }

   753 

   754     /**

   755      * Gets the month-of-year field using the {@code Month} enum.

   756      * <p>

   757      * This method returns the enum {@link Month} for the month.

   758      * This avoids confusion as to what {@code int} values mean.

   759      * If you need access to the primitive {@code int} value then the enum

   760      * provides the {@link Month#getValue() int value}.

   761      *

   762      * @return the month-of-year, not null

   763      * @see #getMonthValue()

   764      */

   765     public Month getMonth() {

   766         return Month.of(month);

   767     }

   768 

   769     /**

   770      * Gets the day-of-month field.

   771      * <p>

   772      * This method returns the primitive {@code int} value for the day-of-month.

   773      *

   774      * @return the day-of-month, from 1 to 31

   775      */

   776     public int getDayOfMonth() {

   777         return day;

   778     }

   779 

   780     /**

   781      * Gets the day-of-year field.

   782      * <p>

   783      * This method returns the primitive {@code int} value for the day-of-year.

   784      *

   785      * @return the day-of-year, from 1 to 365, or 366 in a leap year

   786      */

   787     public int getDayOfYear() {

   788         return getMonth().firstDayOfYear(isLeapYear()) + day - 1;

   789     }

   790 

   791     /**

   792      * Gets the day-of-week field, which is an enum {@code DayOfWeek}.

   793      * <p>

   794      * This method returns the enum {@link DayOfWeek} for the day-of-week.

   795      * This avoids confusion as to what {@code int} values mean.

   796      * If you need access to the primitive {@code int} value then the enum

   797      * provides the {@link DayOfWeek#getValue() int value}.

   798      * <p>

   799      * Additional information can be obtained from the {@code DayOfWeek}.

   800      * This includes textual names of the values.

   801      *

   802      * @return the day-of-week, not null

   803      */

   804     public DayOfWeek getDayOfWeek() {

   805         int dow0 = (int)Math.floorMod(toEpochDay() + 3, 7);

   806         return DayOfWeek.of(dow0 + 1);

   807     }

   808 

   809     //-----------------------------------------------------------------------

   810     /**

   811      * Checks if the year is a leap year, according to the ISO proleptic

   812      * calendar system rules.

   813      * <p>

   814      * This method applies the current rules for leap years across the whole time-line.

   815      * In general, a year is a leap year if it is divisible by four without

   816      * remainder. However, years divisible by 100, are not leap years, with

   817      * the exception of years divisible by 400 which are.

   818      * <p>

   819      * For example, 1904 is a leap year it is divisible by 4.

   820      * 1900 was not a leap year as it is divisible by 100, however 2000 was a

   821      * leap year as it is divisible by 400.

   822      * <p>

   823      * The calculation is proleptic - applying the same rules into the far future and far past.

   824      * This is historically inaccurate, but is correct for the ISO-8601 standard.

   825      *

   826      * @return true if the year is leap, false otherwise

   827      */

   828     @Override // override for Javadoc and performance

   829     public boolean isLeapYear() {

   830         return IsoChronology.INSTANCE.isLeapYear(year);

   831     }

   832 

   833     /**

   834      * Returns the length of the month represented by this date.

   835      * <p>

   836      * This returns the length of the month in days.

   837      * For example, a date in January would return 31.

   838      *

   839      * @return the length of the month in days

   840      */

   841     @Override

   842     public int lengthOfMonth() {

   843         switch (month) {

   844             case 2:

   845                 return (isLeapYear() ? 29 : 28);

   846             case 4:

   847             case 6:

   848             case 9:

   849             case 11:

   850                 return 30;

   851             default:

   852                 return 31;

   853         }

   854     }

   855 

   856     /**

   857      * Returns the length of the year represented by this date.

   858      * <p>

   859      * This returns the length of the year in days, either 365 or 366.

   860      *

   861      * @return 366 if the year is leap, 365 otherwise

   862      */

   863     @Override // override for Javadoc and performance

   864     public int lengthOfYear() {

   865         return (isLeapYear() ? 366 : 365);

   866     }

   867 

   868     //-----------------------------------------------------------------------

   869     /**

   870      * Returns an adjusted copy of this date.

   871      * <p>

   872      * This returns a {@code LocalDate}, based on this one, with the date adjusted.

   873      * The adjustment takes place using the specified adjuster strategy object.

   874      * Read the documentation of the adjuster to understand what adjustment will be made.

   875      * <p>

   876      * A simple adjuster might simply set the one of the fields, such as the year field.

   877      * A more complex adjuster might set the date to the last day of the month.

   878      * <p>

   879      * A selection of common adjustments is provided in

   880      * {@link java.time.temporal.TemporalAdjusters TemporalAdjusters}.

   881      * These include finding the "last day of the month" and "next Wednesday".

   882      * Key date-time classes also implement the {@code TemporalAdjuster} interface,

   883      * such as {@link Month} and {@link java.time.MonthDay MonthDay}.

   884      * The adjuster is responsible for handling special cases, such as the varying

   885      * lengths of month and leap years.

   886      * <p>

   887      * For example this code returns a date on the last day of July:

   888      * <pre>

   889      *  import static java.time.Month.*;

   890      *  import static java.time.temporal.TemporalAdjusters.*;

   891      *

   892      *  result = localDate.with(JULY).with(lastDayOfMonth());

   893      * </pre>

   894      * <p>

   895      * The result of this method is obtained by invoking the

   896      * {@link TemporalAdjuster#adjustInto(Temporal)} method on the

   897      * specified adjuster passing {@code this} as the argument.

   898      * <p>

   899      * This instance is immutable and unaffected by this method call.

   900      *

   901      * @param adjuster the adjuster to use, not null

   902      * @return a {@code LocalDate} based on {@code this} with the adjustment made, not null

   903      * @throws DateTimeException if the adjustment cannot be made

   904      * @throws ArithmeticException if numeric overflow occurs

   905      */

   906     @Override

   907     public LocalDate with(TemporalAdjuster adjuster) {

   908         // optimizations

   909         if (adjuster instanceof LocalDate) {

   910             return (LocalDate) adjuster;

   911         }

   912         return (LocalDate) adjuster.adjustInto(this);

   913     }

   914 

   915     /**

   916      * Returns a copy of this date with the specified field set to a new value.

   917      * <p>

   918      * This returns a {@code LocalDate}, based on this one, with the value

   919      * for the specified field changed.

   920      * This can be used to change any supported field, such as the year, month or day-of-month.

   921      * If it is not possible to set the value, because the field is not supported or for

   922      * some other reason, an exception is thrown.

   923      * <p>

   924      * In some cases, changing the specified field can cause the resulting date to become invalid,

   925      * such as changing the month from 31st January to February would make the day-of-month invalid.

   926      * In cases like this, the field is responsible for resolving the date. Typically it will choose

   927      * the previous valid date, which would be the last valid day of February in this example.

   928      * <p>

   929      * If the field is a {@link ChronoField} then the adjustment is implemented here.

   930      * The supported fields behave as follows:

   931      * <ul>

   932      * <li>{@code DAY_OF_WEEK} -

   933      *  Returns a {@code LocalDate} with the specified day-of-week.

   934      *  The date is adjusted up to 6 days forward or backward within the boundary

   935      *  of a Monday to Sunday week.

   936      * <li>{@code ALIGNED_DAY_OF_WEEK_IN_MONTH} -

   937      *  Returns a {@code LocalDate} with the specified aligned-day-of-week.

   938      *  The date is adjusted to the specified month-based aligned-day-of-week.

   939      *  Aligned weeks are counted such that the first week of a given month starts

   940      *  on the first day of that month.

   941      *  This may cause the date to be moved up to 6 days into the following month.

   942      * <li>{@code ALIGNED_DAY_OF_WEEK_IN_YEAR} -

   943      *  Returns a {@code LocalDate} with the specified aligned-day-of-week.

   944      *  The date is adjusted to the specified year-based aligned-day-of-week.

   945      *  Aligned weeks are counted such that the first week of a given year starts

   946      *  on the first day of that year.

   947      *  This may cause the date to be moved up to 6 days into the following year.

   948      * <li>{@code DAY_OF_MONTH} -

   949      *  Returns a {@code LocalDate} with the specified day-of-month.

   950      *  The month and year will be unchanged. If the day-of-month is invalid for the

   951      *  year and month, then a {@code DateTimeException} is thrown.

   952      * <li>{@code DAY_OF_YEAR} -

   953      *  Returns a {@code LocalDate} with the specified day-of-year.

   954      *  The year will be unchanged. If the day-of-year is invalid for the

   955      *  year, then a {@code DateTimeException} is thrown.

   956      * <li>{@code EPOCH_DAY} -

   957      *  Returns a {@code LocalDate} with the specified epoch-day.

   958      *  This completely replaces the date and is equivalent to {@link #ofEpochDay(long)}.

   959      * <li>{@code ALIGNED_WEEK_OF_MONTH} -

   960      *  Returns a {@code LocalDate} with the specified aligned-week-of-month.

   961      *  Aligned weeks are counted such that the first week of a given month starts

   962      *  on the first day of that month.

   963      *  This adjustment moves the date in whole week chunks to match the specified week.

   964      *  The result will have the same day-of-week as this date.

   965      *  This may cause the date to be moved into the following month.

   966      * <li>{@code ALIGNED_WEEK_OF_YEAR} -

   967      *  Returns a {@code LocalDate} with the specified aligned-week-of-year.

   968      *  Aligned weeks are counted such that the first week of a given year starts

   969      *  on the first day of that year.

   970      *  This adjustment moves the date in whole week chunks to match the specified week.

   971      *  The result will have the same day-of-week as this date.

   972      *  This may cause the date to be moved into the following year.

   973      * <li>{@code MONTH_OF_YEAR} -

   974      *  Returns a {@code LocalDate} with the specified month-of-year.

   975      *  The year will be unchanged. The day-of-month will also be unchanged,

   976      *  unless it would be invalid for the new month and year. In that case, the

   977      *  day-of-month is adjusted to the maximum valid value for the new month and year.

   978      * <li>{@code PROLEPTIC_MONTH} -

   979      *  Returns a {@code LocalDate} with the specified proleptic-month.

   980      *  The day-of-month will be unchanged, unless it would be invalid for the new month

   981      *  and year. In that case, the day-of-month is adjusted to the maximum valid value

   982      *  for the new month and year.

   983      * <li>{@code YEAR_OF_ERA} -

   984      *  Returns a {@code LocalDate} with the specified year-of-era.

   985      *  The era and month will be unchanged. The day-of-month will also be unchanged,

   986      *  unless it would be invalid for the new month and year. In that case, the

   987      *  day-of-month is adjusted to the maximum valid value for the new month and year.

   988      * <li>{@code YEAR} -

   989      *  Returns a {@code LocalDate} with the specified year.

   990      *  The month will be unchanged. The day-of-month will also be unchanged,

   991      *  unless it would be invalid for the new month and year. In that case, the

   992      *  day-of-month is adjusted to the maximum valid value for the new month and year.

   993      * <li>{@code ERA} -

   994      *  Returns a {@code LocalDate} with the specified era.

   995      *  The year-of-era and month will be unchanged. The day-of-month will also be unchanged,

   996      *  unless it would be invalid for the new month and year. In that case, the

   997      *  day-of-month is adjusted to the maximum valid value for the new month and year.

   998      * </ul>

   999      * <p>

  1000      * In all cases, if the new value is outside the valid range of values for the field

  1001      * then a {@code DateTimeException} will be thrown.

  1002      * <p>

  1003      * All other {@code ChronoField} instances will throw an {@code UnsupportedTemporalTypeException}.

  1004      * <p>

  1005      * If the field is not a {@code ChronoField}, then the result of this method

  1006      * is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)}

  1007      * passing {@code this} as the argument. In this case, the field determines

  1008      * whether and how to adjust the instant.

  1009      * <p>

  1010      * This instance is immutable and unaffected by this method call.

  1011      *

  1012      * @param field  the field to set in the result, not null

  1013      * @param newValue  the new value of the field in the result

  1014      * @return a {@code LocalDate} based on {@code this} with the specified field set, not null

  1015      * @throws DateTimeException if the field cannot be set

  1016      * @throws UnsupportedTemporalTypeException if the field is not supported

  1017      * @throws ArithmeticException if numeric overflow occurs

  1018      */

  1019     @Override

  1020     public LocalDate with(TemporalField field, long newValue) {

  1021         if (field instanceof ChronoField) {

  1022             ChronoField f = (ChronoField) field;

  1023             f.checkValidValue(newValue);

  1024             switch (f) {

  1025                 case DAY_OF_WEEK: return plusDays(newValue - getDayOfWeek().getValue());

  1026                 case ALIGNED_DAY_OF_WEEK_IN_MONTH: return plusDays(newValue - getLong(ALIGNED_DAY_OF_WEEK_IN_MONTH));

  1027                 case ALIGNED_DAY_OF_WEEK_IN_YEAR: return plusDays(newValue - getLong(ALIGNED_DAY_OF_WEEK_IN_YEAR));

  1028                 case DAY_OF_MONTH: return withDayOfMonth((int) newValue);

  1029                 case DAY_OF_YEAR: return withDayOfYear((int) newValue);

  1030                 case EPOCH_DAY: return LocalDate.ofEpochDay(newValue);

  1031                 case ALIGNED_WEEK_OF_MONTH: return plusWeeks(newValue - getLong(ALIGNED_WEEK_OF_MONTH));

  1032                 case ALIGNED_WEEK_OF_YEAR: return plusWeeks(newValue - getLong(ALIGNED_WEEK_OF_YEAR));

  1033                 case MONTH_OF_YEAR: return withMonth((int) newValue);

  1034                 case PROLEPTIC_MONTH: return plusMonths(newValue - getProlepticMonth());

  1035                 case YEAR_OF_ERA: return withYear((int) (year >= 1 ? newValue : 1 - newValue));

  1036                 case YEAR: return withYear((int) newValue);

  1037                 case ERA: return (getLong(ERA) == newValue ? this : withYear(1 - year));

  1038             }

  1039             throw new UnsupportedTemporalTypeException("Unsupported field: " + field);

  1040         }

  1041         return field.adjustInto(this, newValue);

  1042     }

  1043 

  1044     //-----------------------------------------------------------------------

  1045     /**

  1046      * Returns a copy of this {@code LocalDate} with the year altered.

  1047      * <p>

  1048      * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.

  1049      * <p>

  1050      * This instance is immutable and unaffected by this method call.

  1051      *

  1052      * @param year  the year to set in the result, from MIN_YEAR to MAX_YEAR

  1053      * @return a {@code LocalDate} based on this date with the requested year, not null

  1054      * @throws DateTimeException if the year value is invalid

  1055      */

  1056     public LocalDate withYear(int year) {

  1057         if (this.year == year) {

  1058             return this;

  1059         }

  1060         YEAR.checkValidValue(year);

  1061         return resolvePreviousValid(year, month, day);

  1062     }

  1063 

  1064     /**

  1065      * Returns a copy of this {@code LocalDate} with the month-of-year altered.

  1066      * <p>

  1067      * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.

  1068      * <p>

  1069      * This instance is immutable and unaffected by this method call.

  1070      *

  1071      * @param month  the month-of-year to set in the result, from 1 (January) to 12 (December)

  1072      * @return a {@code LocalDate} based on this date with the requested month, not null

  1073      * @throws DateTimeException if the month-of-year value is invalid

  1074      */

  1075     public LocalDate withMonth(int month) {

  1076         if (this.month == month) {

  1077             return this;

  1078         }

  1079         MONTH_OF_YEAR.checkValidValue(month);

  1080         return resolvePreviousValid(year, month, day);

  1081     }

  1082 

  1083     /**

  1084      * Returns a copy of this {@code LocalDate} with the day-of-month altered.

  1085      * <p>

  1086      * If the resulting date is invalid, an exception is thrown.

  1087      * <p>

  1088      * This instance is immutable and unaffected by this method call.

  1089      *

  1090      * @param dayOfMonth  the day-of-month to set in the result, from 1 to 28-31

  1091      * @return a {@code LocalDate} based on this date with the requested day, not null

  1092      * @throws DateTimeException if the day-of-month value is invalid,

  1093      *  or if the day-of-month is invalid for the month-year

  1094      */

  1095     public LocalDate withDayOfMonth(int dayOfMonth) {

  1096         if (this.day == dayOfMonth) {

  1097             return this;

  1098         }

  1099         return of(year, month, dayOfMonth);

  1100     }

  1101 

  1102     /**

  1103      * Returns a copy of this {@code LocalDate} with the day-of-year altered.

  1104      * <p>

  1105      * If the resulting date is invalid, an exception is thrown.

  1106      * <p>

  1107      * This instance is immutable and unaffected by this method call.

  1108      *

  1109      * @param dayOfYear  the day-of-year to set in the result, from 1 to 365-366

  1110      * @return a {@code LocalDate} based on this date with the requested day, not null

  1111      * @throws DateTimeException if the day-of-year value is invalid,

  1112      *  or if the day-of-year is invalid for the year

  1113      */

  1114     public LocalDate withDayOfYear(int dayOfYear) {

  1115         if (this.getDayOfYear() == dayOfYear) {

  1116             return this;

  1117         }

  1118         return ofYearDay(year, dayOfYear);

  1119     }

  1120 

  1121     //-----------------------------------------------------------------------

  1122     /**

  1123      * Returns a copy of this date with the specified amount added.

  1124      * <p>

  1125      * This returns a {@code LocalDate}, based on this one, with the specified amount added.

  1126      * The amount is typically {@link Period} but may be any other type implementing

  1127      * the {@link TemporalAmount} interface.

  1128      * <p>

  1129      * The calculation is delegated to the amount object by calling

  1130      * {@link TemporalAmount#addTo(Temporal)}. The amount implementation is free

  1131      * to implement the addition in any way it wishes, however it typically

  1132      * calls back to {@link #plus(long, TemporalUnit)}. Consult the documentation

  1133      * of the amount implementation to determine if it can be successfully added.

  1134      * <p>