time::chrono +linux +x86_64

The time::chrono submodule provides the basis for chronology in Hare, namely timescales (leap second handling), timezones, and the moment type, an abstracted datetime for external modules to interface with.

For working with the ISO 8601 Gregorian calendar, see the datetime submodule.

Hare defines a chronology as a system used to name and order moments in time. In practice, a chronology is the combination of a calendar (for handling days) and a wall clock (for handling times throughout a day).



type epochal;
type locality;
type moment;
type timescale;
type timezone;
type transition;
type ts_converter;
type zone;


type error;
type invalid;
type invalidtzif;


const EARTH_DAY: time::duration;
const MARS_SOL_MARTIAN: time::duration;
const MARS_SOL_TERRESTRIAL: time::duration;
const SECS_1900_1970: i64;


let LOCAL: locality;
let MTC: locality;
let TAI: locality;
let TT: timescale;
let UTC: locality;
let gps: timescale;
let mtc: timescale;
let tai: timescale;
let utc: timescale;


fn fixedzone(*timescale, time::duration, zone) timezone;
fn from_instant(time::instant, locality) moment;
fn in(locality, moment) moment;
fn lookupzone(*moment) zone;
fn new(epochal, time::duration, locality) (moment | invalid);
fn strerror(error) const str;
fn to_instant(moment) time::instant;
fn tz(str) (timezone | fs::error | io::error | invalidtzif);

// Undocumented functions:
fn transform(moment, time::duration) moment;


type epochal[link]

type epochal = i64;

An ordinal day (on Earth or otherwise) since the Hare epoch (zeroth day) 1970-01-01

type locality[link]

type locality = *timezone;

The virtual region a moment is interpreted in

type moment[link]

type moment = struct {
	// The ordinal day (on Earth or otherwise)
// since the Hare epoch (zeroth day) 1970-01-01
date: epochal, // The time since the start of the day
time: time::duration, // The timezone used for interpreting a moment's date and time
loc: locality, // The current [[zone]] this moment observes
zone: zone, };

A date & time, within a locality, intepreted via a chronology

type timescale[link]

type timescale = struct {
	name: str,
	abbr: str,
	to_tai: *ts_converter,
	from_tai: *ts_converter,

Represents a scale of time; a time standard

type timezone[link]

type timezone = struct {
	// The textual identifier ("Europe/Amsterdam")
name: str, // The base timescale (chrono::utc)
timescale: *timescale, // The duration of a day in this timezone (24 * time::HOUR)
daylength: time::duration, // The possible temporal zones a locality with this timezone can observe
// (CET, CEST, ...)
zones: []zone, // The transitions between this timezone's zones
transitions: []transition, // A timezone specifier in the POSIX "expanded" TZ format.
// See https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html
// Used for extending calculations beyond the last known transition.
posix_extend: str, };

A timezone; a political region with a ruleset regarding offsets for calculating localized civil time

type transition[link]

type transition = struct {
	when: time::instant,
	zoneindex: int,

A timezone transition between two zones

type ts_converter[link]

type ts_converter = fn(i: time::instant) (time::instant | time::error);

Converts one time::instant from one timescale to another

type zone[link]

type zone = struct {
	// The offset from the normal timezone (2 * time::HOUR)
zoffset: time::duration, // The full descriptive name ("Central European Summer Time")
name: str, // The abbreviated name ("CEST")
abbr: str, // Indicator of Daylight Saving Time
dst: bool, };

A timezone state, with an offset for calculating localized civil time


type error[link]

type error = !(fs::error | io::error | invalidtzif);

Possible errors returned from tz.

type invalid[link]

type invalid = !void;

This date, time, and locality combination is invalid.

type invalidtzif[link]

type invalidtzif = !void;

Some TZif data is invalid


def EARTH_DAY[link]

def EARTH_DAY: time::duration;

The temporal length of a day on Earth. Interpreted with an appropriate timescale like utc, tai, gps.


def MARS_SOL_MARTIAN: time::duration;

The temporal length of a solar day on Marth, in Martian seconds


def MARS_SOL_TERRESTRIAL: time::duration;

The temporal length of a solar day on Marth, in Earth (SI) seconds

def SECS_1900_1970[link]

def SECS_1900_1970: i64;

The number of seconds between the years 1900 and 1970.



The filepath of the leap-seconds.list file


let LOCAL[link]

const LOCAL: locality;

The system's local timezone, set during initialisation

let MTC[link]

const MTC: locality;

The MTC (Coordinated Mars Time) "Zulu" timezone

let TAI[link]

const TAI: locality;

The TAI (International Atomic Time) "Zulu" timezone

let TT[link]

const TT: timescale;

Terrestrial Time

Used for astronomical timekeeping. Based on TAI, with a constant offset. Continuous (no leap seconds).

let UTC[link]

const UTC: locality;

The UTC (Coordinated Universal Time) "Zulu" timezone

let gps[link]

const gps: timescale;

Global Positioning System Time

Used for GPS coordination. Based on TAI, constant -19 second offset. Continuous (no leap seconds).

let mtc[link]

const mtc: timescale;

Coordinated Mars Time

Used for local solar time on Mars. Based on TT, with a constant factor. Continuous (no leap seconds).

let tai[link]

const tai: timescale;

International Atomic Time

The realisation of proper time on Earth's geoid. Continuous (no leap seconds).

let utc[link]

const utc: timescale;

Coordinated Universal Time

Used as the basis of civil timekeeping. Based on TAI, with an offset, changed roughly biannually. Discontinuous (has leap seconds).


fn fixedzone[link]

fn fixedzone(ts: *timescale, daylen: time::duration, z: zone) timezone;

Creates a timezone with a single zone. Useful for fixed offsets. For example, replicate the civil time Hawaii timezone on Earth:

let hawaii = chrono::fixedzone(&chrono::utc, chrono::EARTH_DAY,
	chrono::zone {
		zoffset = -10 * time::HOUR,
		name = "Hawaiian Reef",
		abbr = "HARE",
		dst = false,

fn from_instant[link]

fn from_instant(i: time::instant, loc: locality) moment;

Creates a new moment from a time::instant in a locality

fn in[link]

fn in(loc: locality, m: moment) moment;

Converts a moment to one in a different locality

fn lookupzone[link]

fn lookupzone(m: *moment) zone;

Finds, sets and returns a moment's currently observed zone

fn new[link]

fn new(date: epochal, time: time::duration, loc: locality) (moment | invalid);

Creates a new moment

fn strerror[link]

fn strerror(err: error) const str;

Converts an error to a human-friendly representation.

fn to_instant[link]

fn to_instant(m: moment) time::instant;

Creates a new time::instant from a moment

fn tz[link]

fn tz(name: str) (timezone | fs::error | io::error | invalidtzif);

Parses and retrieves a timezone from the system's zoneinfo database, or if applicable, from an internal selection of timezones. All timezones provided default to the utc timescale and EARTH_DAY daylength.

fn transform[link]

Show undocumented member
fn transform(m: moment, zo: time::duration) moment;