Period

The following functions operate on the built-in type Period representing calendar periods.

A Period represents an amount of time in terms of years, months and days. See Duration for another representation of time amounts based on absolute time.

components : Period -> Period::Components

Returns the underlying representation of the Period. The returned data type has the following definition:

module Period {
  type Components {
    years : Int,
    months : Int,
    days : Int
  }
}

Examples

val a = Period::components (Period::from 1 2 3)
//    = Period::Components { days = 3, months = 2, years = 1 }

fromComponents : Period::Components -> Period

Constructs a Period from its components.

Examples

val a = Period::fromComponents Period::Components { days = 3, months = 2, years = 1 }
//    = Period::from 3 2 1

from : Int -> Int -> Int -> Period

Convenience wrapper for Period::fromComponents which receives the components as positional arguments.

The order of arguments is

  1. years

  2. months

  3. days

between : Date -> Date -> Period

Returns a Period consisting of the number of years, months, and days between two dates.

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 2010-01-15 to 2011-03-18 is one year, two months and three days.

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.

Examples

val a = Period::between (Date::from 2020 January 1) (Date::from 2021 January 1)
//    = Period::from 1 0 0

val b = Period::between (Date::from 2020 May 30) (Date::from 1999 December 24)
//    = Period::from (-20) (-5) (-6)

// All components in the result have the same sign.
// Thus the following results in a period of 24 days rather than
// a period of 1 month and -5 days.
val c = Period::between (Date::from 2020 February 15) (Date::from 2020 March 10)
//    = Period::from 0 0 24

add : Period -> Period -> Period

Adds two periods.

This operates separately on the years, months and days. No normalization is performed.

For example, “1 year, 6 months and 3 days” plus “2 years, 6 months and 2 days” returns “3 years, 12 months and 5 days”.

Examples

val a = Period::add (Period::from 1 6 3) (Period::from 2 6 2)
//    = Period::from 3 12 5

negated : Period -> Period

Negates the Period. Each of the years, months and days components in the period are negated.

Examples

val a = Period::negated (Period::from 1 6 3)
//    = Period::from (-1) (-6) (-3)