dk.simongray.ical.tz — dk.simongray/ical-clj 0.1.0

Find the zone that a TZID names, and convert between its local date-times and instants.

A zone comes from the platform's time zone database (ZoneRules on the JVM, Intl.DateTimeFormat in JavaScript), from a VTIMEZONE in a calendar, or from a fixed UTC offset. The two platforms agree as long as their copies of the database are the same version.

Local date-times are strings in the form of jCal, e.g. "2026-10-12T19:00:00", and instants are insts.

instant clj/s

(instant zone s)

The inst of the local date-time s in the zone. When the clocks go back, a time that occurs twice means the first of them. When they go forward, a time that doesn't occur takes the offset from before.

(instant (zone "America/New_York") "2007-03-11T02:30:00")
;; => #inst "2007-03-11T07:30:00.000-00:00" (3:30 EDT)

local clj/s

(local zone at)

The local date-time of the inst at in the zone, e.g. "2026-10-12T19:00:00".

offset clj/s

(offset zone at)

The UTC offset of the zone at the inst at, e.g. "+02:00".

vtimezone clj/s

(vtimezone zone tzid from to)

A VTIMEZONE with the TZID tzid for the platform's zone, covering the years from to to. If the zone follows yearly rules at the end of that span, they become RRULEs, so the definition goes on after it.

(vtimezone (zone "Europe/Copenhagen") "Europe/Copenhagen" 2026 2027)

with-timezones clj/s

(with-timezones cal)

The calendar cal with a VTIMEZONE added at the front for each TZID that it uses without defining, when the platform knows the zone (see vtimezone). The TZIDs that cal defines, and those that name no known zone, stay as they are.

zone clj/s

(zone tzid)

(zone cal tzid)

(zone cal tzid {:keys [vtimezone?]})

The zone that the TZID tzid names, or nil when nothing defines it. Given the calendar cal, its VTIMEZONEs can define the zone too.

The function tries tzid, in order:

1. as a zone name of the platform's database, ignoring case
2. without its prefix, when it starts with a solidus, e.g. /mozilla.org/20050126_1/Europe/Berlin
3. as a Windows zone name, e.g. W. Europe Standard Time, mapped by CLDR's windowsZones
4. as the TZID of a VTIMEZONE in cal

The platform comes first because a calendar's own definition is often stale or covers only a few years. To prefer the calendar's, pass :vtimezone? true in opts. A fixed UTC offset such as +02:00 is a zone too.