Date

The built-in type Date represents a calendar date as a year, month and day-of-month. Being a representation of a calendar date, Date does not uniquely define an Instant or even a range of Instant values on the global timeline. For example, the date 2020-01-01 can be seen as the range of instants from #2020-01-01T00:00Z# to #2020-01-01T23:59:59.999Z# if interpreted as a local date in the GMT time zone, but in the time zone Europe/Copenhagen it can be seen as the instants from #2019-12-31T23:00Z# to #2020-01-01T22:59:59.999Z#.

If you need to perform arithmetic on calendar dates together with time of day, use the zoned time and date functions.

Date::components : Date -> Date::Components

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

module YearMonth {
  type Components {
    year : Year,
    month : Month
  }
}

module Date {
  type Components : YearMonth::Components {
    day : Int
  }
}

Examples

val a = Date::components (Date::from 2020 December 21)
//    = Date::Components {
//      day = 21,
//      month = December,
//      year = Year::fromInt 2020
//    }

Date::fromComponents : Date::Components -> Date

Construct a Date from the underlying components. This function is partial and fails if the day component is invalid for the given year and month.

Examples

val a = Date::fromComponents Date::Components {
          day = 21,
          month = December,
          year = Year::fromInt 2020
        }
//   = Date::from 2020 December 21

Date::from : Int -> Int -> Int -> Date

A convenience wrapper around Date::fromComponents which takes the year, month and day as positional Int arguments.

Date::epochDay : Date -> Int

Returns the epoch day, defined as the number of calendar days since 1970-01-01 until the given date. The returned value may be negative if the given date is before the epoch.

This function is useful for obtaining the number of calendar days between two dates, as this equals the difference between their epoch days.

To obtain a Date from an epoch day, use Date::addPeriod.

Examples

val a = Date::epochDay (Date::from 2020 December 21)
//    = 18617

val b = Date::addPeriod (Period::from 0 0 18617) (Date::from 1970 January 1)
//    = Date::from 2020 12 21

Date::dayOfWeek : Date -> DayOfWeek

Returns the day of week for the given date.

Examples

val a = Date::dayOfWeek (Date::from 2020 December 21)
//    = Monday

Date::addPeriod : Period -> Date -> Date

Adds a calendar period to the given date.

A calendar period consists of a number of years, months and days. The period is added to the given date by first adding all the years, then all the months and finally all the days. Adding one year and adding 12 months is equivalent. If the day of month component would be invalid after all the months have been added, then it is adjusted back to the last valid day of month before the days of the period are added.

Examples

// Adding 1 month. Adding one month to 2020-03-31 gives the invalid date 2020-04-31 which is adjusted back to 2020-04-30.
val a = Date::addPeriod (Period::from 0 1 0) (Date::from 2020 March 31)
//    = Date::from 2020 4 30

// Adding 1 month and 1 day.
val b = Date::addPeriod (Period::from 0 1 1) (Date::from 2020 March 31)
//    = Date::from 2020 5 1