js-joda

When performing arithmetic on a ZonedDateTime, the behavior depends on whether you use date units or time units:

• Date units (e.g., plusWeeks, plusDays): Calculations are performed on the local timeline. The local time remains the same even if a daylight savings transition occurs.
• Time units (e.g., plusHours, plusMinutes): Calculations are performed on the instant timeline. The absolute point in time is advanced, which may result in a different local time if a daylight savings transition occurs.

// assume the system default time zone is CET; we define a time as 2016-03-18 at 17:00 local time
var zdt = ZonedDateTime.parse("2016-03-18T17:00+01:00[Europe/Berlin]");

// adding a date unit of 2 weeks, crossing a daylight saving transition
zdt.plusWeeks(2); // 2016-04-01T17:00+02:00[Europe/Berlin] (still 17:00)

// adding a time unit of 2 weeks (2 * 7 * 24)
zdt.plusHours(2 * 7 * 24); // 2016-04-01T18:00+02:00[Europe/Berlin] (now 18:00)

A Period represents a date-based amount of time in the ISO-8601 calendar system (e.g., '2 years, 3 months and 4 days'). Unlike Duration, which is time-based (seconds/nanoseconds), Period is used for calendar-based calculations like years, months, and days.

Common operations include:

• Parsing: Create a Period from an ISO-8601 string using Period.parse().
• Creation: Use factory methods like Period.of(years, months, days) or specific methods like Period.ofYears(n).
• Manipulation: Use plusDays(), plusMonths(), minusDays(), etc., to modify a period. Note that these operations are immutable and return a new Period instance.
• Normalization: Use .normalized() to convert a period like '1 year and 37 months' into its standard form (e.g., '2 years and 1 month').
• Date Arithmetic: Add a Period to a LocalDate or LocalDateTime using the .plus() method.
• Difference Calculation: Calculate the period between two LocalDate instances using Period.between(start, end).

// parse and format ISO 8601 period strings
Period.parse("P1Y10M").toString(); // 'P1Y10M'

// obtain a Period of 10 years, 5 month and 30 days
Period.of(10, 5, 30).toString(); // 'P10Y5M30D'

// 10 years
Period.ofYears(10).toString(); // 'P10Y'

// add 45 days to a Period
Period.ofYears(10)
  .plusDays(45)
  .toString(); // 'P10Y45D'

// normalize a Period of years and month
Period.of(1, 37, 0)
  .normalized()
  .toString(); // 'P4Y1M'

// add/subtract from a Period
Period.ofYears(10)
  .plusMonths(10)
  .minusDays(42)
  .toString(); // 'P10Y10M-42D'

// add a Period to LocalDate
var p = Period.ofMonths(1);
LocalDate.parse("2012-12-12").plus(p); // '2013-01-12';
LocalDate.parse("2012-01-31").plus(p); // '2012-02-29';
LocalDateTime.parse("2012-05-31T12:00").plus(p); // '2012-06-30T12:00';

// calculate the Period between two Dates
Period.between(LocalDate.parse("2012-06-30"), LocalDate.parse("2012-08-31")); // 'P2M1D'