std/time/calendar▲toc

Calendars.

A Calendar determines how a datestd/time/date/date: V and clockstd/time/date/clock: V relates to an instantstd/time/instant/instant: V in time with respect to a timezonestd/time/calendar/timezone: V. These functions turn instantstd/time/instant/instant: V's into “human” dates. Months, days etc. are always 1-based.

A Calendar determines how a datestd/time/date/date: V and clockstd/time/date/clock: V relates to an instantstd/time/instant/instant: V in time.

Check if two calendars use the same date calculations. (Display of era names etc. may differ).

The (proleptic) Gregorian calendar. Just like the ISO calendar except that the year 0 does not exist, i.e. after 1 BCE (=~1) we have 1 CE (=1). The calendar short name is GC.

The standard ISO 8601 calendar using TI time (ts-tistd/time/utc/ts-ti: timescale). This is a proleptic Gregorian calendar except that it uses the year 0 for 1 BCE, -1 for 2 BCE etc.
This is the default calendar used in the library as it guarantees deterministic date calculations while still taking historical leap seconds into account.

The standard ISO 8601 calendar but using TI-SLS time (ts-ti-slsstd/time/utc/ts-ti-sls: timescale), i.e. TI with smoothed leap seconds.

This calendar is equivalent to the ISO calendar except for the last 1000 seconds of a day where a leap second occurs. On such day, the leap second time step (positive or negative) is distributed over the last 1000 seconds of the day. On the full hour, ISO and ISO-SLS are equal again.

This is a recommended calendar to use for time stamps or communication with other services since it avoids any potential trouble with leap seconds while still being quite precise.

Other good properties include:

  • All days have 86400 seconds, and the time 23:59:60 never appears
  • The time never differs more than one second from UTC
  • Time as always equal to UTC on the full and half hour.

Create a standard ISO 8601 calendar using UTC time (ts-utc-createstd/time/utc/ts-utc-create: (leaps : leaps-table) -> timescale) given a provide leap second table (leaps-tablestd/time/utc/leaps-table: V). This is a proleptic Gregorian calendar except that it uses the year 0 for 1 BCE, -1 for 2 BCE etc.

You can create an ISO 8601 UTC calendar using the latest IETF leap second data using cal-utc-load.

Create a new ISO 8601 calendar based on UTC-SLS time, i.e. UTC with smoothed leap seconds.

Create a new calendar from by combining two other calendars. The switch-date is in terms of the second calendar (cal2) and time after (and including) the switch date is displayed in cal2 while times before it in cal1. This function is used for example for the Julian Gregorian calendar.

Return the days between two dates interpreted by calendar cal.

Create a calendar where we assume that each day has 24 hours with 60 minutes, and where minutes are 60 seconds (with possibly leap seconds). The function takes care of timezones, epoch shifts, and leap seconds, and only needs a calendar name, a function days-to-datestd/time/calendar/days-to-date: (calendar : calendar) -> ((days : int) -> date) to calculate a date given a number of days since the epochstd/time/instant/epoch: instant, a function date-to-daysstd/time/calendar/date-to-days: (calendar : calendar) -> ((date : date) -> int) to calculate days since the epochstd/time/instant/epoch: instant for a given date, and an optional time scale to be used (=ts-utc).
month-prefixstd/time/calendar/month-prefix: (calendar : calendar) -> string (="") is used when displaying numeric months and is set for the ISO week dates to "W" for example. The show-erastd/time/calendar/show-era: (calendar : calendar) -> ((date) -> string) function can be given to display the era of a date.

Create a standard ISO calendar using a particular time scale and calendar name (=ts.name).

Automatically generated. Retrieves the name constructor field of the calendarstd/time/calendar/calendar: V type.

fun solar-calendar( name : stringstd/core/string: V, long-name : stringstd/core/string: V, days-before-year : (year : intstd/core/int: V) -> intstd/core/int: V, days-to-yeardoy : (days : intstd/core/int: V) -> (intstd/core/int: V, intstd/core/int: V), days-before-month : (year : intstd/core/int: V, month : intstd/core/int: V) -> intstd/core/int: V, days-to-month : (year : intstd/core/int: V, doy : intstd/core/int: V) -> intstd/core/int: V, epoch-shift : ?intstd/core/int: V, has-year-zero? : ?boolstd/core/bool: V, month-prefix : ?stringstd/core/string: V, show-era : ?(datestd/time/date/date: V) -> stringstd/core/string: V ) : calendarstd/time/calendar/calendar: V

An abstraction over solar calendars. Almost all calendars can be defined in terms of this function (and solar-ecalendarstd/time/calendar/solar-ecalendar: (name : string, long-name : string, days-before-year : (year : int) -> int, estimate-year : (days : int) -> (int, maybe<int>), days-before-month : (year : int, month : int) -> int, days-to-month : (year : int, doy : int) -> int, epoch-shift : ?int, has-year-zero? : ?bool, month-prefix : ?string, show-era : ?(date) -> string) -> calendar). Given functions to convert days to and from a year, and day-of-the-year to and from month and month day, this constructs a full calendar.
Also needs an epoch-shift that gives the number of days from the calendar epoch to the date 2000-01-01. By default this is 730119 which corresponds to a 0001-01-01 ISO calendar epoch. The has-year-zero? (=Truestd/core/True: bool) parameter is used when the calendar has a year zero. The month-prefixstd/time/calendar/month-prefix: (calendar : calendar) -> string (="") is used for displaying numeric months (and is "W" for cal-iso-week for example). The show-erastd/time/calendar/show-era: (calendar : calendar) -> ((date) -> string) function can be given to display an era for a given date. Finally the ts (=ts-tistd/time/utc/ts-ti: timescale) gives the time scale for the calendar.

An abstraction over solar calendars. Almost all calendars can be defined in terms of this function (and solar-calendarstd/time/calendar/solar-calendar: (name : string, long-name : string, days-before-year : (year : int) -> int, days-to-yeardoy : (days : int) -> (int, int), days-before-month : (year : int, month : int) -> int, days-to-month : (year : int, doy : int) -> int, epoch-shift : ?int, has-year-zero? : ?bool, month-prefix : ?string, show-era : ?(date) -> string) -> calendar). Given functions to convert days to and from a year, and day-of-the-year to and from month and month day, this constructs a full calendar. In contrast to solar-calendarstd/time/calendar/solar-calendar: (name : string, long-name : string, days-before-year : (year : int) -> int, days-to-yeardoy : (days : int) -> (int, int), days-before-month : (year : int, month : int) -> int, days-to-month : (year : int, doy : int) -> int, epoch-shift : ?int, has-year-zero? : ?bool, month-prefix : ?string, show-era : ?(date) -> string) -> calendar this function just needs an estimation function from days to a year – for most calendars this is much more convenient. The estimation function returns a conservative (i.e. lowest) estimate for the year and a maybe<int> that is the safe-day: if the day of the year is lower or equal to that the estimate is surely correct. Otherwise the wrapper will calculate the start day for the next year until the correct year is found.
Also needs an epoch-shift that gives the number of days from the calendar epoch to the date 2000-01-01. By default this is 730119 which corresponds to a 0001-01-01 ISO calendar epoch. The has-year-zero? (=Truestd/core/True: bool) parameter is used when the calendar has a year zero. The month-prefixstd/time/calendar/month-prefix: (calendar : calendar) -> string (="") is used for displaying numeric months (and is "W" for cal-iso-week for example). The show-erastd/time/calendar/show-era: (calendar : calendar) -> ((date) -> string) function can be given to display an era for a given date. Finally the ts (=ts-utc) gives the time scale for the calendar.

Create a new calendar from anoter calendar cal by adding an offset to the years (year-shift). This is used for example to create the Ethiopian calendar from the Coptic calendar, by using: year-shift-earth-calendarstd/time/calendar/year-shift-earth-calendar: (name : string, long-name : string, year-shift : int, cal : calendar, month-prefix : ?string, show-era : ?(date) -> string) -> calendar( "EC", "Ethiopian", ~276, cal-coptic ).

A timezonestd/time/calendar/timezone: V determines a time offset with respect to the UTC / GMT timezone. For using general time zones, see the std/time/timezone module.
The tz-utcstd/time/calendar/tz-utc: timezone and tz-localstd/time/calendar/tz-local: () -> ndet timezone time zones are used for UTC/GMT time and the local system time.
The name field contains the time zone name as IANA timezone identifier. The utc-deltastd/time/calendar/utc-delta: (timezone : timezone) -> ((instant) -> (duration, string)) field returns the time zone offset relative to UTC (for GMT-08:00 it returns a duration of -8*3600 seconds) and the abbreviated time zone name (PDT for example).
The optional utc-inversestd/time/calendar/utc-inverse: (timezone : timezone) -> ((instant) -> maybe<instant>) field returns for an instant in the time zone, the associated UTC time. By default it returns Nothingstd/core/Nothing: forall<a> maybe<a> in which case a generic algorithm is used to determine the inverse.

Automatically generated. Retrieves the name constructor field of the timezonestd/time/calendar/timezone: V type.

Create a time zone with a fixed number of hours and optional minutes (=0) difference from UTC/GMT. The time zone name and abbreviation is optional, and the default name will reflect the offset from UTC, for example "UTC+1:20", or "UTC-8". The default abbreviation is the empty string. The sign of the minutes will be matched to the hours (unless hours is 0). For example, tz-fixed(-1,30) gives a time zone offset of -90 minutes, “UTC-1:30”. Returns tz-utcstd/time/calendar/tz-utc: timezone if both hours and mins are zero.

Return the local timezone on the current system.

The standard UTC time zone with a 0 delta.

Is this the UTC timezone?

Return the instant in time for a given datestd/time/date/date: V and clockstd/time/date/clock: V (= clock0std/time/date/clock0: clock) interpreted by calendar cal (=cal-isostd/time/calendar/cal-iso: calendar) in a timezone tz (=tz-utcstd/time/calendar/tz-utc: timezone by default).

Convert an instantstd/time/instant/instant: V to a datestd/time/date/date: V, clockstd/time/date/clock: V, timezone delta and abbreviation, for a given timezone tz (=tz-utcstd/time/calendar/tz-utc: timezone by default) and calendar (=cal-isostd/time/calendar/cal-iso: calendar by default).

Return the instant in time for a given date and clock interpreted by calendar cal (=cal-isostd/time/calendar/cal-iso: calendar) in a timezone tz (=tz-utcstd/time/calendar/tz-utc: timezone by default).

The monthstd/time/date/month: (date : date) -> int, daystd/time/date/day: (date : date) -> int, hour, minutes may be outside their usual ranges and will be normalized during the conversion. For example, January 33 converts to February 2. This makes it very easy to add- or subtract days or months to an existing time. When the seconds or fraction of seconds frac add up over 60 those extra seconds are interpreted as leap seconds.

Due to timezone transitions, or leap seconds, it is possible to specify dates that never happened (as it was skipped by a timezone change), or ambigious times (as a timezone springs back). In such cases, the time is always interpreted in the earlier timezone.