Period.java 39.8 KB
Newer Older
S
sherman 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
/*
 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

/*
 * This file is available under and governed by the GNU General Public
 * License version 2 only, as published by the Free Software Foundation.
 * However, the following notice accompanied the original version of this
 * file:
 *
 * Copyright (c) 2008-2012, Stephen Colebourne & Michael Nascimento Santos
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *  * Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 *  * Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 *  * Neither the name of JSR-310 nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package java.time;

import static java.time.temporal.ChronoField.MONTH_OF_YEAR;
import static java.time.temporal.ChronoUnit.DAYS;
import static java.time.temporal.ChronoUnit.MONTHS;
import static java.time.temporal.ChronoUnit.YEARS;

S
sherman 已提交
69 70 71 72 73
import java.io.DataInput;
import java.io.DataOutput;
import java.io.IOException;
import java.io.InvalidObjectException;
import java.io.ObjectStreamException;
S
sherman 已提交
74
import java.io.Serializable;
S
sherman 已提交
75 76
import java.time.chrono.ChronoLocalDate;
import java.time.chrono.Chronology;
S
sherman 已提交
77 78 79
import java.time.format.DateTimeParseException;
import java.time.temporal.ChronoUnit;
import java.time.temporal.Temporal;
S
sherman 已提交
80
import java.time.temporal.TemporalAmount;
S
sherman 已提交
81
import java.time.temporal.TemporalUnit;
82
import java.time.temporal.UnsupportedTemporalTypeException;
S
sherman 已提交
83
import java.time.temporal.ValueRange;
S
sherman 已提交
84 85 86
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
S
sherman 已提交
87
import java.util.Objects;
S
sherman 已提交
88 89
import java.util.regex.Matcher;
import java.util.regex.Pattern;
S
sherman 已提交
90 91

/**
S
sherman 已提交
92
 * A date-based amount of time, such as '2 years, 3 months and 4 days'.
S
sherman 已提交
93
 * <p>
S
sherman 已提交
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
 * This class models a quantity or amount of time in terms of years, months and days.
 * See {@link Duration} for the time-based equivalent to this class.
 * <p>
 * Durations and period differ in their treatment of daylight savings time
 * when added to {@link ZonedDateTime}. A {@code Duration} will add an exact
 * number of seconds, thus a duration of one day is always exactly 24 hours.
 * By contrast, a {@code Period} will add a conceptual day, trying to maintain
 * the local time.
 * <p>
 * For example, consider adding a period of one day and a duration of one day to
 * 18:00 on the evening before a daylight savings gap. The {@code Period} will add
 * the conceptual day and result in a {@code ZonedDateTime} at 18:00 the following day.
 * By contrast, the {@code Duration} will add exactly 24 hours, resulting in a
 * {@code ZonedDateTime} at 19:00 the following day (assuming a one hour DST gap).
 * <p>
 * The supported units of a period are {@link ChronoUnit#YEARS YEARS},
 * {@link ChronoUnit#MONTHS MONTHS} and {@link ChronoUnit#DAYS DAYS}.
 * All three fields are always present, but may be set to zero.
 * <p>
 * The period may be used with any calendar system.
 * The meaning of a "year" or "month" is only applied when the object is added to a date.
S
sherman 已提交
115 116 117
 * <p>
 * The period is modeled as a directed amount of time, meaning that individual parts of the
 * period may be negative.
S
sherman 已提交
118 119 120
 * <p>
 * The months and years fields may be {@linkplain #normalized() normalized}.
 * The normalization assumes a 12 month year, so is not appropriate for all calendar systems.
S
sherman 已提交
121
 *
122
 * @implSpec
S
sherman 已提交
123 124 125 126 127
 * This class is immutable and thread-safe.
 *
 * @since 1.8
 */
public final class Period
S
sherman 已提交
128
        implements TemporalAmount, Serializable {
S
sherman 已提交
129 130 131 132

    /**
     * A constant for a period of zero.
     */
S
sherman 已提交
133
    public static final Period ZERO = new Period(0, 0, 0);
S
sherman 已提交
134 135 136
    /**
     * Serialization version.
     */
S
sherman 已提交
137 138 139 140 141
    private static final long serialVersionUID = -3587258372562876L;
    /**
     * The pattern for parsing.
     */
    private final static Pattern PATTERN =
142
            Pattern.compile("([-+]?)P(?:([-+]?[0-9]+)Y)?(?:([-+]?[0-9]+)M)?(?:([-+]?[0-9]+)W)?(?:([-+]?[0-9]+)D)?", Pattern.CASE_INSENSITIVE);
S
sherman 已提交
143 144 145 146 147
    /**
     * The set of supported units.
     */
    private final static List<TemporalUnit> SUPPORTED_UNITS =
            Collections.unmodifiableList(Arrays.<TemporalUnit>asList(YEARS, MONTHS, DAYS));
S
sherman 已提交
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163

    /**
     * The number of years.
     */
    private final int years;
    /**
     * The number of months.
     */
    private final int months;
    /**
     * The number of days.
     */
    private final int days;

    //-----------------------------------------------------------------------
    /**
S
sherman 已提交
164
     * Obtains a {@code Period} representing a number of years.
S
sherman 已提交
165
     * <p>
S
sherman 已提交
166 167
     * The resulting period will have the specified years.
     * The months and days units will be zero.
S
sherman 已提交
168
     *
S
sherman 已提交
169 170
     * @param years  the number of years, positive or negative
     * @return the period of years, not null
S
sherman 已提交
171
     */
S
sherman 已提交
172 173
    public static Period ofYears(int years) {
        return create(years, 0, 0);
S
sherman 已提交
174 175 176
    }

    /**
S
sherman 已提交
177
     * Obtains a {@code Period} representing a number of months.
S
sherman 已提交
178
     * <p>
S
sherman 已提交
179 180
     * The resulting period will have the specified months.
     * The years and days units will be zero.
S
sherman 已提交
181
     *
S
sherman 已提交
182 183
     * @param months  the number of months, positive or negative
     * @return the period of months, not null
S
sherman 已提交
184
     */
S
sherman 已提交
185 186
    public static Period ofMonths(int months) {
        return create(0, months, 0);
S
sherman 已提交
187 188
    }

189 190 191 192 193 194 195 196 197 198 199 200 201 202
    /**
     * Obtains a {@code Period} representing a number of weeks.
     * <p>
     * The resulting period will be day-based, with the amount of days
     * equal to the number of weeks multiplied by 7.
     * The years and months units will be zero.
     *
     * @param weeks  the number of weeks, positive or negative
     * @return the period, with the input weeks converted to days, not null
     */
    public static Period ofWeeks(int weeks) {
        return create(0, 0, Math.multiplyExact(weeks, 7));
    }

S
sherman 已提交
203
    /**
S
sherman 已提交
204
     * Obtains a {@code Period} representing a number of days.
S
sherman 已提交
205
     * <p>
S
sherman 已提交
206 207
     * The resulting period will have the specified days.
     * The years and months units will be zero.
S
sherman 已提交
208
     *
S
sherman 已提交
209 210
     * @param days  the number of days, positive or negative
     * @return the period of days, not null
S
sherman 已提交
211
     */
S
sherman 已提交
212 213
    public static Period ofDays(int days) {
        return create(0, 0, days);
S
sherman 已提交
214 215 216 217
    }

    //-----------------------------------------------------------------------
    /**
S
sherman 已提交
218
     * Obtains a {@code Period} representing a number of years, months and days.
S
sherman 已提交
219
     * <p>
S
sherman 已提交
220
     * This creates an instance based on years, months and days.
S
sherman 已提交
221
     *
S
sherman 已提交
222 223 224 225
     * @param years  the amount of years, may be negative
     * @param months  the amount of months, may be negative
     * @param days  the amount of days, may be negative
     * @return the period of years, months and days, not null
S
sherman 已提交
226
     */
S
sherman 已提交
227 228
    public static Period of(int years, int months, int days) {
        return create(years, months, days);
S
sherman 已提交
229 230 231 232
    }

    //-----------------------------------------------------------------------
    /**
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
     * Obtains an instance of {@code Period} from a temporal amount.
     * <p>
     * This obtains a period based on the specified amount.
     * A {@code TemporalAmount} represents an  amount of time, which may be
     * date-based or time-based, which this factory extracts to a period.
     * <p>
     * The conversion loops around the set of units from the amount and uses
     * the {@link ChronoUnit#YEARS YEARS}, {@link ChronoUnit#MONTHS MONTHS}
     * and {@link ChronoUnit#DAYS DAYS} units to create a period.
     * If any other units are found then an exception is thrown.
     *
     * @param amount  the temporal amount to convert, not null
     * @return the equivalent period, not null
     * @throws DateTimeException if unable to convert to a {@code Period}
     * @throws ArithmeticException if the amount of years, months or days exceeds an int
     */
    public static Period from(TemporalAmount amount) {
        Objects.requireNonNull(amount, "amount");
        int years = 0;
        int months = 0;
        int days = 0;
        for (TemporalUnit unit : amount.getUnits()) {
            long unitAmount = amount.get(unit);
            if (unit == ChronoUnit.YEARS) {
                years = Math.toIntExact(unitAmount);
            } else if (unit == ChronoUnit.MONTHS) {
                months = Math.toIntExact(unitAmount);
            } else if (unit == ChronoUnit.DAYS) {
                days = Math.toIntExact(unitAmount);
            } else {
                throw new DateTimeException("Unit must be Years, Months or Days, but was " + unit);
            }
        }
        return create(years, months, days);
S
sherman 已提交
267 268 269 270
    }

    //-----------------------------------------------------------------------
    /**
S
sherman 已提交
271
     * Obtains a {@code Period} from a text string such as {@code PnYnMnD}.
S
sherman 已提交
272 273
     * <p>
     * This will parse the string produced by {@code toString()} which is
274
     * based on the ISO-8601 period formats {@code PnYnMnD} and {@code PnW}.
S
sherman 已提交
275 276 277 278
     * <p>
     * The string starts with an optional sign, denoted by the ASCII negative
     * or positive symbol. If negative, the whole period is negated.
     * The ASCII letter "P" is next in upper or lower case.
279 280 281 282
     * There are then four sections, each consisting of a number and a suffix.
     * At least one of the four sections must be present.
     * The sections have suffixes in ASCII of "Y", "M", "W" and "D" for
     * years, months, weeks and days, accepted in upper or lower case.
S
sherman 已提交
283 284 285 286 287 288
     * The suffixes must occur in order.
     * The number part of each section must consist of ASCII digits.
     * The number may be prefixed by the ASCII negative or positive symbol.
     * The number must parse to an {@code int}.
     * <p>
     * The leading plus/minus sign, and negative values for other units are
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
     * not part of the ISO-8601 standard. In addition, ISO-8601 does not
     * permit mixing between the {@code PnYnMnD} and {@code PnW} formats.
     * Any week-based input is multiplied by 7 and treated as a number of days.
     * <p>
     * For example, the following are valid inputs:
     * <pre>
     *   "P2Y"             -- Period.ofYears(2)
     *   "P3M"             -- Period.ofMonths(3)
     *   "P4W"             -- Period.ofWeeks(4)
     *   "P5D"             -- Period.ofDays(5)
     *   "P1Y2M3D"         -- Period.of(1, 2, 3)
     *   "P1Y2M3W4D"       -- Period.of(1, 2, 25)
     *   "P-1Y2M"          -- Period.of(-1, 2, 0)
     *   "-P1Y2M"          -- Period.of(-1, -2, 0)
     * </pre>
S
sherman 已提交
304 305 306 307 308
     *
     * @param text  the text to parse, not null
     * @return the parsed period, not null
     * @throws DateTimeParseException if the text cannot be parsed to a period
     */
S
sherman 已提交
309
    public static Period parse(CharSequence text) {
S
sherman 已提交
310
        Objects.requireNonNull(text, "text");
S
sherman 已提交
311 312 313 314 315
        Matcher matcher = PATTERN.matcher(text);
        if (matcher.matches()) {
            int negate = ("-".equals(matcher.group(1)) ? -1 : 1);
            String yearMatch = matcher.group(2);
            String monthMatch = matcher.group(3);
316 317 318
            String weekMatch = matcher.group(4);
            String dayMatch = matcher.group(5);
            if (yearMatch != null || monthMatch != null || dayMatch != null || weekMatch != null) {
S
sherman 已提交
319
                try {
320 321 322 323 324 325
                    int years = parseNumber(text, yearMatch, negate);
                    int months = parseNumber(text, monthMatch, negate);
                    int weeks = parseNumber(text, weekMatch, negate);
                    int days = parseNumber(text, dayMatch, negate);
                    days = Math.addExact(days, Math.multiplyExact(weeks, 7));
                    return create(years, months, days);
S
sherman 已提交
326
                } catch (NumberFormatException ex) {
327
                    throw new DateTimeParseException("Text cannot be parsed to a Period", text, 0, ex);
S
sherman 已提交
328 329 330 331 332 333 334 335 336 337 338 339 340 341
                }
            }
        }
        throw new DateTimeParseException("Text cannot be parsed to a Period", text, 0);
    }

    private static int parseNumber(CharSequence text, String str, int negate) {
        if (str == null) {
            return 0;
        }
        int val = Integer.parseInt(str);
        try {
            return Math.multiplyExact(val, negate);
        } catch (ArithmeticException ex) {
342
            throw new DateTimeParseException("Text cannot be parsed to a Period", text, 0, ex);
S
sherman 已提交
343
        }
S
sherman 已提交
344 345
    }

346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363
    //-----------------------------------------------------------------------
    /**
     * Obtains a {@code Period} consisting of the number of years, months,
     * and days between two dates.
     * <p>
     * The start date is included, but the end date is not.
     * The period is calculated by removing complete months, then calculating
     * the remaining number of days, adjusting to ensure that both have the same sign.
     * The number of months is then split into years and months based on a 12 month year.
     * A month is considered if the end day-of-month is greater than or equal to the start day-of-month.
     * For example, from {@code 2010-01-15} to {@code 2011-03-18} is one year, two months and three days.
     * <p>
     * The result of this method can be a negative period if the end is before the start.
     * The negative sign will be the same in each of year, month and day.
     *
     * @param startDate  the start date, inclusive, not null
     * @param endDate  the end date, exclusive, not null
     * @return the period between this date and the end date, not null
364
     * @see ChronoLocalDate#until(ChronoLocalDate)
365 366
     */
    public static Period between(LocalDate startDate, LocalDate endDate) {
367
        return startDate.until(endDate);
368 369
    }

S
sherman 已提交
370 371 372 373 374 375 376 377
    //-----------------------------------------------------------------------
    /**
     * Creates an instance.
     *
     * @param years  the amount
     * @param months  the amount
     * @param days  the amount
     */
S
sherman 已提交
378 379
    private static Period create(int years, int months, int days) {
        if ((years | months | days) == 0) {
S
sherman 已提交
380 381
            return ZERO;
        }
S
sherman 已提交
382
        return new Period(years, months, days);
S
sherman 已提交
383 384 385 386 387 388 389 390 391
    }

    /**
     * Constructor.
     *
     * @param years  the amount
     * @param months  the amount
     * @param days  the amount
     */
S
sherman 已提交
392
    private Period(int years, int months, int days) {
S
sherman 已提交
393 394 395 396 397
        this.years = years;
        this.months = months;
        this.days = days;
    }

S
sherman 已提交
398
    //-----------------------------------------------------------------------
S
sherman 已提交
399
    /**
S
sherman 已提交
400 401 402 403 404 405
     * Gets the value of the requested unit.
     * <p>
     * This returns a value for each of the three supported units,
     * {@link ChronoUnit#YEARS YEARS}, {@link ChronoUnit#MONTHS MONTHS} and
     * {@link ChronoUnit#DAYS DAYS}.
     * All other units throw an exception.
S
sherman 已提交
406
     *
S
sherman 已提交
407 408 409
     * @param unit the {@code TemporalUnit} for which to return the value
     * @return the long value of the unit
     * @throws DateTimeException if the unit is not supported
410
     * @throws UnsupportedTemporalTypeException if the unit is not supported
S
sherman 已提交
411
     */
S
sherman 已提交
412 413 414 415 416 417 418 419 420
    @Override
    public long get(TemporalUnit unit) {
        if (unit == ChronoUnit.YEARS) {
            return getYears();
        } else if (unit == ChronoUnit.MONTHS) {
            return getMonths();
        } else if (unit == ChronoUnit.DAYS) {
            return getDays();
        } else {
421
            throw new UnsupportedTemporalTypeException("Unsupported unit: " + unit);
S
sherman 已提交
422
        }
S
sherman 已提交
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439
    }

    /**
     * Gets the set of units supported by this period.
     * <p>
     * The supported units are {@link ChronoUnit#YEARS YEARS},
     * {@link ChronoUnit#MONTHS MONTHS} and {@link ChronoUnit#DAYS DAYS}.
     * They are returned in the order years, months, days.
     * <p>
     * This set can be used in conjunction with {@link #get(TemporalUnit)}
     * to access the entire state of the period.
     *
     * @return a list containing the years, months and days units, not null
     */
    @Override
    public List<TemporalUnit> getUnits() {
        return SUPPORTED_UNITS;
S
sherman 已提交
440 441 442 443
    }

    //-----------------------------------------------------------------------
    /**
S
sherman 已提交
444 445 446
     * Checks if all three units of this period are zero.
     * <p>
     * A zero period has the value zero for the years, months and days units.
S
sherman 已提交
447 448 449 450 451 452 453 454
     *
     * @return true if this period is zero-length
     */
    public boolean isZero() {
        return (this == ZERO);
    }

    /**
S
sherman 已提交
455
     * Checks if any of the three units of this period are negative.
S
sherman 已提交
456
     * <p>
S
sherman 已提交
457
     * This checks whether the years, months or days units are less than zero.
S
sherman 已提交
458
     *
S
sherman 已提交
459
     * @return true if any unit of this period is negative
S
sherman 已提交
460
     */
S
sherman 已提交
461 462
    public boolean isNegative() {
        return years < 0 || months < 0 || days < 0;
S
sherman 已提交
463 464 465 466 467
    }

    //-----------------------------------------------------------------------
    /**
     * Gets the amount of years of this period.
S
sherman 已提交
468 469 470 471 472 473
     * <p>
     * This returns the years unit.
     * <p>
     * The months unit is not normalized with the years unit.
     * This means that a period of "15 months" is different to a period
     * of "1 year and 3 months".
S
sherman 已提交
474
     *
S
sherman 已提交
475
     * @return the amount of years of this period, may be negative
S
sherman 已提交
476 477 478 479 480 481 482
     */
    public int getYears() {
        return years;
    }

    /**
     * Gets the amount of months of this period.
S
sherman 已提交
483 484 485 486 487 488
     * <p>
     * This returns the months unit.
     * <p>
     * The months unit is not normalized with the years unit.
     * This means that a period of "15 months" is different to a period
     * of "1 year and 3 months".
S
sherman 已提交
489
     *
S
sherman 已提交
490
     * @return the amount of months of this period, may be negative
S
sherman 已提交
491 492 493 494 495 496 497
     */
    public int getMonths() {
        return months;
    }

    /**
     * Gets the amount of days of this period.
S
sherman 已提交
498 499
     * <p>
     * This returns the days unit.
S
sherman 已提交
500
     *
S
sherman 已提交
501
     * @return the amount of days of this period, may be negative
S
sherman 已提交
502 503 504 505 506 507 508 509 510
     */
    public int getDays() {
        return days;
    }

    //-----------------------------------------------------------------------
    /**
     * Returns a copy of this period with the specified amount of years.
     * <p>
S
sherman 已提交
511 512 513 514 515 516
     * This sets the amount of the years unit in a copy of this period.
     * The months and days units are unaffected.
     * <p>
     * The months unit is not normalized with the years unit.
     * This means that a period of "15 months" is different to a period
     * of "1 year and 3 months".
S
sherman 已提交
517 518 519
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
520
     * @param years  the years to represent, may be negative
S
sherman 已提交
521 522 523 524 525 526
     * @return a {@code Period} based on this period with the requested years, not null
     */
    public Period withYears(int years) {
        if (years == this.years) {
            return this;
        }
S
sherman 已提交
527
        return create(years, months, days);
S
sherman 已提交
528 529 530 531 532
    }

    /**
     * Returns a copy of this period with the specified amount of months.
     * <p>
S
sherman 已提交
533 534 535 536 537 538
     * This sets the amount of the months unit in a copy of this period.
     * The years and days units are unaffected.
     * <p>
     * The months unit is not normalized with the years unit.
     * This means that a period of "15 months" is different to a period
     * of "1 year and 3 months".
S
sherman 已提交
539 540 541
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
542
     * @param months  the months to represent, may be negative
S
sherman 已提交
543 544 545 546 547 548
     * @return a {@code Period} based on this period with the requested months, not null
     */
    public Period withMonths(int months) {
        if (months == this.months) {
            return this;
        }
S
sherman 已提交
549
        return create(years, months, days);
S
sherman 已提交
550 551 552 553 554
    }

    /**
     * Returns a copy of this period with the specified amount of days.
     * <p>
S
sherman 已提交
555 556
     * This sets the amount of the days unit in a copy of this period.
     * The years and months units are unaffected.
S
sherman 已提交
557 558 559
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
560
     * @param days  the days to represent, may be negative
S
sherman 已提交
561 562 563 564 565 566
     * @return a {@code Period} based on this period with the requested days, not null
     */
    public Period withDays(int days) {
        if (days == this.days) {
            return this;
        }
S
sherman 已提交
567
        return create(years, months, days);
S
sherman 已提交
568 569 570 571 572 573
    }

    //-----------------------------------------------------------------------
    /**
     * Returns a copy of this period with the specified period added.
     * <p>
574
     * This operates separately on the years, months and days.
S
sherman 已提交
575
     * <p>
S
sherman 已提交
576 577 578
     * For example, "1 year, 6 months and 3 days" plus "2 years, 2 months and 2 days"
     * returns "3 years, 8 months and 5 days".
     * <p>
S
sherman 已提交
579 580
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
581
     * @param amountToAdd  the period to add, not null
S
sherman 已提交
582 583 584
     * @return a {@code Period} based on this period with the requested period added, not null
     * @throws ArithmeticException if numeric overflow occurs
     */
S
sherman 已提交
585
    public Period plus(Period amountToAdd) {
S
sherman 已提交
586
        return create(
S
sherman 已提交
587 588 589
                Math.addExact(years, amountToAdd.years),
                Math.addExact(months, amountToAdd.months),
                Math.addExact(days, amountToAdd.days));
S
sherman 已提交
590 591 592
    }

    /**
S
sherman 已提交
593
     * Returns a copy of this period with the specified years added.
S
sherman 已提交
594
     * <p>
S
sherman 已提交
595 596 597
     * This adds the amount to the years unit in a copy of this period.
     * The months and days units are unaffected.
     * For example, "1 year, 6 months and 3 days" plus 2 years returns "3 years, 6 months and 3 days".
S
sherman 已提交
598 599 600
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
601 602
     * @param yearsToAdd  the years to add, positive or negative
     * @return a {@code Period} based on this period with the specified years added, not null
S
sherman 已提交
603 604
     * @throws ArithmeticException if numeric overflow occurs
     */
S
sherman 已提交
605 606 607
    public Period plusYears(long yearsToAdd) {
        if (yearsToAdd == 0) {
            return this;
S
sherman 已提交
608
        }
S
sherman 已提交
609
        return create(Math.toIntExact(Math.addExact(years, yearsToAdd)), months, days);
S
sherman 已提交
610 611
    }

S
sherman 已提交
612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629
    /**
     * Returns a copy of this period with the specified months added.
     * <p>
     * This adds the amount to the months unit in a copy of this period.
     * The years and days units are unaffected.
     * For example, "1 year, 6 months and 3 days" plus 2 months returns "1 year, 8 months and 3 days".
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param monthsToAdd  the months to add, positive or negative
     * @return a {@code Period} based on this period with the specified months added, not null
     * @throws ArithmeticException if numeric overflow occurs
     */
    public Period plusMonths(long monthsToAdd) {
        if (monthsToAdd == 0) {
            return this;
        }
        return create(years, Math.toIntExact(Math.addExact(months, monthsToAdd)), days);
S
sherman 已提交
630 631
    }

S
sherman 已提交
632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649
    /**
     * Returns a copy of this period with the specified days added.
     * <p>
     * This adds the amount to the days unit in a copy of this period.
     * The years and months units are unaffected.
     * For example, "1 year, 6 months and 3 days" plus 2 days returns "1 year, 6 months and 5 days".
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param daysToAdd  the days to add, positive or negative
     * @return a {@code Period} based on this period with the specified days added, not null
     * @throws ArithmeticException if numeric overflow occurs
     */
    public Period plusDays(long daysToAdd) {
        if (daysToAdd == 0) {
            return this;
        }
        return create(years, months, Math.toIntExact(Math.addExact(days, daysToAdd)));
S
sherman 已提交
650 651 652 653 654 655
    }

    //-----------------------------------------------------------------------
    /**
     * Returns a copy of this period with the specified period subtracted.
     * <p>
656
     * This operates separately on the years, months and days.
S
sherman 已提交
657
     * <p>
S
sherman 已提交
658 659 660
     * For example, "1 year, 6 months and 3 days" minus "2 years, 2 months and 2 days"
     * returns "-1 years, 4 months and 1 day".
     * <p>
S
sherman 已提交
661 662
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
663
     * @param amountToSubtract  the period to subtract, not null
S
sherman 已提交
664 665 666
     * @return a {@code Period} based on this period with the requested period subtracted, not null
     * @throws ArithmeticException if numeric overflow occurs
     */
S
sherman 已提交
667
    public Period minus(Period amountToSubtract) {
S
sherman 已提交
668
        return create(
S
sherman 已提交
669 670 671
                Math.subtractExact(years, amountToSubtract.years),
                Math.subtractExact(months, amountToSubtract.months),
                Math.subtractExact(days, amountToSubtract.days));
S
sherman 已提交
672 673 674
    }

    /**
S
sherman 已提交
675
     * Returns a copy of this period with the specified years subtracted.
S
sherman 已提交
676
     * <p>
S
sherman 已提交
677 678 679
     * This subtracts the amount from the years unit in a copy of this period.
     * The months and days units are unaffected.
     * For example, "1 year, 6 months and 3 days" minus 2 years returns "-1 years, 6 months and 3 days".
S
sherman 已提交
680 681 682
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
683 684
     * @param yearsToSubtract  the years to subtract, positive or negative
     * @return a {@code Period} based on this period with the specified years subtracted, not null
S
sherman 已提交
685 686
     * @throws ArithmeticException if numeric overflow occurs
     */
S
sherman 已提交
687 688
    public Period minusYears(long yearsToSubtract) {
        return (yearsToSubtract == Long.MIN_VALUE ? plusYears(Long.MAX_VALUE).plusYears(1) : plusYears(-yearsToSubtract));
S
sherman 已提交
689 690
    }

S
sherman 已提交
691 692 693 694 695 696 697 698 699 700 701 702 703 704 705
    /**
     * Returns a copy of this period with the specified months subtracted.
     * <p>
     * This subtracts the amount from the months unit in a copy of this period.
     * The years and days units are unaffected.
     * For example, "1 year, 6 months and 3 days" minus 2 months returns "1 year, 4 months and 3 days".
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param monthsToSubtract  the years to subtract, positive or negative
     * @return a {@code Period} based on this period with the specified months subtracted, not null
     * @throws ArithmeticException if numeric overflow occurs
     */
    public Period minusMonths(long monthsToSubtract) {
        return (monthsToSubtract == Long.MIN_VALUE ? plusMonths(Long.MAX_VALUE).plusMonths(1) : plusMonths(-monthsToSubtract));
S
sherman 已提交
706 707
    }

S
sherman 已提交
708 709 710 711 712 713 714 715 716 717 718 719 720 721 722
    /**
     * Returns a copy of this period with the specified days subtracted.
     * <p>
     * This subtracts the amount from the days unit in a copy of this period.
     * The years and months units are unaffected.
     * For example, "1 year, 6 months and 3 days" minus 2 days returns "1 year, 6 months and 1 day".
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param daysToSubtract  the months to subtract, positive or negative
     * @return a {@code Period} based on this period with the specified days subtracted, not null
     * @throws ArithmeticException if numeric overflow occurs
     */
    public Period minusDays(long daysToSubtract) {
        return (daysToSubtract == Long.MIN_VALUE ? plusDays(Long.MAX_VALUE).plusDays(1) : plusDays(-daysToSubtract));
S
sherman 已提交
723 724 725 726 727 728 729
    }

    //-----------------------------------------------------------------------
    /**
     * Returns a new instance with each element in this period multiplied
     * by the specified scalar.
     * <p>
S
sherman 已提交
730 731 732 733 734
     * This returns a period with each of the years, months and days units
     * individually multiplied.
     * For example, a period of "2 years, -3 months and 4 days" multiplied by
     * 3 will return "6 years, -9 months and 12 days".
     * No normalization is performed.
S
sherman 已提交
735 736 737 738 739 740 741 742 743 744 745 746
     *
     * @param scalar  the scalar to multiply by, not null
     * @return a {@code Period} based on this period with the amounts multiplied by the scalar, not null
     * @throws ArithmeticException if numeric overflow occurs
     */
    public Period multipliedBy(int scalar) {
        if (this == ZERO || scalar == 1) {
            return this;
        }
        return create(
                Math.multiplyExact(years, scalar),
                Math.multiplyExact(months, scalar),
S
sherman 已提交
747
                Math.multiplyExact(days, scalar));
S
sherman 已提交
748 749 750 751
    }

    /**
     * Returns a new instance with each amount in this period negated.
S
sherman 已提交
752 753 754 755 756 757
     * <p>
     * This returns a period with each of the years, months and days units
     * individually negated.
     * For example, a period of "2 years, -3 months and 4 days" will be
     * negated to "-2 years, 3 months and -4 days".
     * No normalization is performed.
S
sherman 已提交
758 759
     *
     * @return a {@code Period} based on this period with the amounts negated, not null
S
sherman 已提交
760 761
     * @throws ArithmeticException if numeric overflow occurs, which only happens if
     *  one of the units has the value {@code Long.MIN_VALUE}
S
sherman 已提交
762 763 764 765 766 767 768
     */
    public Period negated() {
        return multipliedBy(-1);
    }

    //-----------------------------------------------------------------------
    /**
S
sherman 已提交
769 770
     * Returns a copy of this period with the years and months normalized
     * using a 12 month year.
S
sherman 已提交
771
     * <p>
S
sherman 已提交
772
     * This normalizes the years and months units, leaving the days unit unchanged.
S
sherman 已提交
773
     * The months unit is adjusted to have an absolute value less than 11,
S
sherman 已提交
774 775
     * with the years unit being adjusted to compensate. For example, a period of
     * "1 Year and 15 months" will be normalized to "2 years and 3 months".
S
sherman 已提交
776 777
     * <p>
     * The sign of the years and months units will be the same after normalization.
S
sherman 已提交
778 779
     * For example, a period of "1 year and -25 months" will be normalized to
     * "-1 year and -1 month".
S
sherman 已提交
780
     * <p>
S
sherman 已提交
781
     * This normalization uses a 12 month year which is not valid for all calendar systems.
S
sherman 已提交
782 783 784
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
785
     * @return a {@code Period} based on this period with excess months normalized to years, not null
S
sherman 已提交
786 787
     * @throws ArithmeticException if numeric overflow occurs
     */
S
sherman 已提交
788 789
    public Period normalized() {
        long totalMonths = toTotalMonths();
S
sherman 已提交
790 791 792 793 794
        long splitYears = totalMonths / 12;
        int splitMonths = (int) (totalMonths % 12);  // no overflow
        if (splitYears == years && splitMonths == months) {
            return this;
        }
S
sherman 已提交
795
        return create(Math.toIntExact(splitYears), splitMonths, days);
S
sherman 已提交
796 797 798
    }

    /**
S
sherman 已提交
799
     * Gets the total number of months in this period using a 12 month year.
S
sherman 已提交
800
     * <p>
S
sherman 已提交
801 802 803 804
     * This returns the total number of months in the period by multiplying the
     * number of years by 12 and adding the number of months.
     * <p>
     * This uses a 12 month year which is not valid for all calendar systems.
S
sherman 已提交
805 806 807
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
S
sherman 已提交
808
     * @return the total number of months in the period, may be negative
S
sherman 已提交
809
     */
S
sherman 已提交
810 811
    public long toTotalMonths() {
        return years * 12L + months;  // no overflow
S
sherman 已提交
812 813 814 815 816 817 818 819 820 821
    }

    //-------------------------------------------------------------------------
    /**
     * Adds this period to the specified temporal object.
     * <p>
     * This returns a temporal object of the same observable type as the input
     * with this period added.
     * <p>
     * In most cases, it is clearer to reverse the calling pattern by using
S
sherman 已提交
822
     * {@link Temporal#plus(TemporalAmount)}.
S
sherman 已提交
823 824 825 826 827 828
     * <pre>
     *   // these two lines are equivalent, but the second approach is recommended
     *   dateTime = thisPeriod.addTo(dateTime);
     *   dateTime = dateTime.plus(thisPeriod);
     * </pre>
     * <p>
S
sherman 已提交
829
     * The calculation will add the years, then months, then days.
S
sherman 已提交
830 831 832 833 834 835 836 837 838 839 840 841 842 843 844
     * Only non-zero amounts will be added.
     * If the date-time has a calendar system with a fixed number of months in a
     * year, then the years and months will be combined before being added.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param temporal  the temporal object to adjust, not null
     * @return an object of the same type with the adjustment made, not null
     * @throws DateTimeException if unable to add
     * @throws ArithmeticException if numeric overflow occurs
     */
    @Override
    public Temporal addTo(Temporal temporal) {
        Objects.requireNonNull(temporal, "temporal");
        if ((years | months) != 0) {
S
sherman 已提交
845 846 847
            long monthRange = monthRange(temporal);
            if (monthRange >= 0) {
                temporal = temporal.plus(years * monthRange + months, MONTHS);
S
sherman 已提交
848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869
            } else {
                if (years != 0) {
                    temporal = temporal.plus(years, YEARS);
                }
                if (months != 0) {
                    temporal = temporal.plus(months, MONTHS);
                }
            }
        }
        if (days != 0) {
            temporal = temporal.plus(days, DAYS);
        }
        return temporal;
    }

    /**
     * Subtracts this period from the specified temporal object.
     * <p>
     * This returns a temporal object of the same observable type as the input
     * with this period subtracted.
     * <p>
     * In most cases, it is clearer to reverse the calling pattern by using
S
sherman 已提交
870
     * {@link Temporal#minus(TemporalAmount)}.
S
sherman 已提交
871 872 873 874 875 876
     * <pre>
     *   // these two lines are equivalent, but the second approach is recommended
     *   dateTime = thisPeriod.subtractFrom(dateTime);
     *   dateTime = dateTime.minus(thisPeriod);
     * </pre>
     * <p>
S
sherman 已提交
877
     * The calculation will subtract the years, then months, then days.
S
sherman 已提交
878 879 880 881 882 883 884 885 886 887 888 889 890 891 892
     * Only non-zero amounts will be subtracted.
     * If the date-time has a calendar system with a fixed number of months in a
     * year, then the years and months will be combined before being subtracted.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param temporal  the temporal object to adjust, not null
     * @return an object of the same type with the adjustment made, not null
     * @throws DateTimeException if unable to subtract
     * @throws ArithmeticException if numeric overflow occurs
     */
    @Override
    public Temporal subtractFrom(Temporal temporal) {
        Objects.requireNonNull(temporal, "temporal");
        if ((years | months) != 0) {
S
sherman 已提交
893 894 895
            long monthRange = monthRange(temporal);
            if (monthRange >= 0) {
                temporal = temporal.minus(years * monthRange + months, MONTHS);
S
sherman 已提交
896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911
            } else {
                if (years != 0) {
                    temporal = temporal.minus(years, YEARS);
                }
                if (months != 0) {
                    temporal = temporal.minus(months, MONTHS);
                }
            }
        }
        if (days != 0) {
            temporal = temporal.minus(days, DAYS);
        }
        return temporal;
    }

    /**
S
sherman 已提交
912
     * Calculates the range of months based on the temporal.
S
sherman 已提交
913
     *
S
sherman 已提交
914 915
     * @param temporal  the temporal, not null
     * @return the month range, negative if not fixed range
S
sherman 已提交
916
     */
S
sherman 已提交
917
    private long monthRange(Temporal temporal) {
918 919 920 921 922
        if (temporal.isSupported(MONTH_OF_YEAR)) {
            ValueRange startRange = Chronology.from(temporal).range(MONTH_OF_YEAR);
            if (startRange.isFixed() && startRange.isIntValue()) {
                return startRange.getMaximum() - startRange.getMinimum() + 1;
            }
S
sherman 已提交
923
        }
S
sherman 已提交
924
        return -1;
S
sherman 已提交
925 926 927 928 929 930 931
    }

    //-----------------------------------------------------------------------
    /**
     * Checks if this period is equal to another period.
     * <p>
     * The comparison is based on the amounts held in the period.
S
sherman 已提交
932 933 934
     * To be equal, the years, months and days units must be individually equal.
     * Note that this means that a period of "15 Months" is not equal to a period
     * of "1 Year and 3 Months".
S
sherman 已提交
935 936 937 938 939 940 941 942 943 944 945
     *
     * @param obj  the object to check, null returns false
     * @return true if this is equal to the other period
     */
    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (obj instanceof Period) {
            Period other = (Period) obj;
S
sherman 已提交
946 947 948
            return years == other.years &&
                    months == other.months &&
                    days == other.days;
S
sherman 已提交
949 950 951 952 953 954 955 956 957 958 959
        }
        return false;
    }

    /**
     * A hash code for this period.
     *
     * @return a suitable hash code
     */
    @Override
    public int hashCode() {
S
sherman 已提交
960
        return years + Integer.rotateLeft(months, 8) + Integer.rotateLeft(days, 16);
S
sherman 已提交
961 962 963 964
    }

    //-----------------------------------------------------------------------
    /**
S
sherman 已提交
965
     * Outputs this period as a {@code String}, such as {@code P6Y3M1D}.
S
sherman 已提交
966 967
     * <p>
     * The output will be in the ISO-8601 period format.
S
sherman 已提交
968
     * A zero period will be represented as zero days, 'P0D'.
S
sherman 已提交
969 970 971 972 973 974
     *
     * @return a string representation of this period, not null
     */
    @Override
    public String toString() {
        if (this == ZERO) {
S
sherman 已提交
975
            return "P0D";
S
sherman 已提交
976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991
        } else {
            StringBuilder buf = new StringBuilder();
            buf.append('P');
            if (years != 0) {
                buf.append(years).append('Y');
            }
            if (months != 0) {
                buf.append(months).append('M');
            }
            if (days != 0) {
                buf.append(days).append('D');
            }
            return buf.toString();
        }
    }

S
sherman 已提交
992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030
    //-----------------------------------------------------------------------
    /**
     * Writes the object using a
     * <a href="../../serialized-form.html#java.time.Ser">dedicated serialized form</a>.
     * <pre>
     *  out.writeByte(14);  // identifies this as a Period
     *  out.writeInt(years);
     *  out.writeInt(months);
     *  out.writeInt(seconds);
     * </pre>
     *
     * @return the instance of {@code Ser}, not null
     */
    private Object writeReplace() {
        return new Ser(Ser.PERIOD_TYPE, this);
    }

    /**
     * Defend against malicious streams.
     * @return never
     * @throws java.io.InvalidObjectException always
     */
    private Object readResolve() throws ObjectStreamException {
        throw new InvalidObjectException("Deserialization via serialization delegate");
    }

    void writeExternal(DataOutput out) throws IOException {
        out.writeInt(years);
        out.writeInt(months);
        out.writeInt(days);
    }

    static Period readExternal(DataInput in) throws IOException {
        int years = in.readInt();
        int months = in.readInt();
        int days = in.readInt();
        return Period.of(years, months, days);
    }

S
sherman 已提交
1031
}