calendar

Contains functions and types to work with calendars and timezones.

Filtrera has instant, date and duration primitives, and the :: operator converts between them. This module adds what those cannot express: reading a calendar field (which weekday? which quarter?) and truncating to a local boundary (when did the month containing this instant begin, in Stockholm?).

Every function takes a timezone

There is no implicit “local”. Server-local time is a defect waiting to happen, so the zone is always an argument, which keeps the choice visible at the call site rather than inherited invisibly from whatever machine the script runs on.

import 'calendar'

param zone: Timezone = 'Europe/Stockholm'

from now startOf ('month', zone)

Typing the parameter as Timezone makes a misspelled zone a compile-time error at the boundary of the script, rather than a surprise deep inside a calculation.

Timezone rules are resolved per instant

Offsets are looked up for the specific instant in question, not taken from the zone’s current offset. So the same zone gives different answers at different times of year, and historical rule changes are honoured too — Sweden had no summer time in 1970, and these functions know that.

This matters most when producing a series that spans a transition. See periods for a worked example.

Only the Gregorian calendar

Gregorian is the native calendar and the only one supported. Language-level duration arithmetic (+ 2 years) is Gregorian and always will be; if other calendar systems are ever supported, they will live here.

Exports

CalendarParts	The record of local calendar fields returned by parts.
endOf	The exclusive upper edge of the local period containing the input, in the given timezone.
Granularity	A type matching the calendar period sizes the module understands.
offsetAt	The UTC offset in force at a given instant, in the given timezone.
parts	The local calendar fields of an instant in the given timezone.
periods	Every calendar period overlapping a range, aligned to local calendar boundaries.
startOf	The instant at which the local period containing the input begins, in the given timezone.
Timezone	A type matching any IANA timezone id.
Weekday	A type matching the days of the week.