java/time/Period.java

101  * By contrast, a {@code Period} will add a conceptual day, trying to maintain
105  * 18:00 on the evening before a daylight savings gap. The {@code Period} will add
125  * {@code Period} may have unpredictable results and should be avoided.
133 public final class Period
139     public static final Period ZERO = new Period(0, 0, 0);
170      * Obtains a {@code Period} representing a number of years.
178     public static Period ofYears(int years) {
183      * Obtains a {@code Period} representing a number of months.
191     public static Period ofMonths(int months) {
196      * Obtains a {@code Period} representing a number of weeks.
205     public static Period ofWeeks(int weeks) {
210      * Obtains a {@code Period} representing a number of days.
218     public static Period ofDays(int days) {
224      * Obtains a {@code Period} representing a number of years, months and days.
233     public static Period of(int years, int months, int days) {
239      * Obtains an instance of {@code Period} from a temporal amount.
243      * date-based or time-based, which this factory extracts to a {@code Period}.
254      * @throws DateTimeException if unable to convert to a {@code Period}
257     public static Period from(TemporalAmount amount) {
258         if (amount instanceof Period) {
259             return (Period) amount;
263                 throw new DateTimeException("Period requires ISO chronology: " + amount);
287      * Obtains a {@code Period} from a text string such as {@code PnYnMnD}.
311      *   "P2Y"             -- Period.ofYears(2)
312      *   "P3M"             -- Period.ofMonths(3)
313      *   "P4W"             -- Period.ofWeeks(4)
314      *   "P5D"             -- Period.ofDays(5)
315      *   "P1Y2M3D"         -- Period.of(1, 2, 3)
316      *   "P1Y2M3W4D"       -- Period.of(1, 2, 25)
317      *   "P-1Y2M"          -- Period.of(-1, 2, 0)
318      *   "-P1Y2M"          -- Period.of(-1, -2, 0)
325     public static Period parse(CharSequence text) {
343                     throw new DateTimeParseException("Text cannot be parsed to a Period", text, 0, ex);
347         throw new DateTimeParseException("Text cannot be parsed to a Period", text, 0);
362             throw new DateTimeParseException("Text cannot be parsed to a Period", text, 0, ex);
368      * Obtains a {@code Period} consisting of the number of years, months,
386     public static Period between(LocalDate startDateInclusive, LocalDate endDateExclusive) {
398     private static Period create(int years, int months, int days) {
402         return new Period(years, months, days);
412     private Period(int years, int months, int days) {
556      * @return a {@code Period} based on this period with the requested years, not null
558     public Period withYears(int years) {
578      * @return a {@code Period} based on this period with the requested months, not null
580     public Period withMonths(int months) {
596      * @return a {@code Period} based on this period with the requested days, not null
598     public Period withDays(int days) {
615      * The specified amount is typically an instance of {@code Period}.
616      * Other types are interpreted using {@link Period#from(TemporalAmount)}.
621      * @return a {@code Period} based on this period with the requested period added, not null
626     public Period plus(TemporalAmount amountToAdd) {
627         Period isoAmount = Period.from(amountToAdd);
644      * @return a {@code Period} based on this period with the specified years added, not null
647     public Period plusYears(long yearsToAdd) {
664      * @return a {@code Period} based on this period with the specified months added, not null
667     public Period plusMonths(long monthsToAdd) {
684      * @return a {@code Period} based on this period with the specified days added, not null
687     public Period plusDays(long daysToAdd) {
704      * The specified amount is typically an instance of {@code Period}.
705      * Other types are interpreted using {@link Period#from(TemporalAmount)}.
710      * @return a {@code Period} based on this period with the requested period subtracted, not null
715     public Period minus(TemporalAmount amountToSubtract) {
716         Period isoAmount = Period.from(amountToSubtract);
733      * @return a {@code Period} based on this period with the specified years subtracted, not null
736     public Period minusYears(long yearsToSubtract) {
750      * @return a {@code Period} based on this period with the specified months subtracted, not null
753     public Period minusMonths(long monthsToSubtract) {
767      * @return a {@code Period} based on this period with the specified days subtracted, not null
770     public Period minusDays(long daysToSubtract) {
786      * @return a {@code Period} based on this period with the amounts multiplied by the scalar, not null
789     public Period multipliedBy(int scalar) {
808      * @return a {@code Period} based on this period with the amounts negated, not null
812     public Period negated() {
831      * @return a {@code Period} based on this period with excess months normalized to years, not null
834     public Period normalized() {
980      * The comparison is based on the type {@code Period} and each of the three amounts.
993         if (obj instanceof Period) {
994             Period other = (Period) obj;
1047      *  out.writeByte(14);  // identifies a Period
1075     static Period readExternal(DataInput in) throws IOException {
1079         return Period.of(years, months, days);