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 date;
type locality;
type moment;
type timescale;
type timezone;
type transition;
type ts_converter;
type zone;


type error;
type invalid;
type invalidtzif;
type tzdberror;


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


let GPS: locality;
let LOCAL: locality;
let MTC: locality;
let TAI: locality;
let TT: locality;
let UTC: locality;
let gps: timescale;
let mtc: timescale;
let tai: timescale;
let tt: 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(locality, date, time::duration) (moment | invalid);
fn strerror(error) const str;
fn to_instant(moment) time::instant;
fn tz(str) (timezone | tzdberror);

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


type date[link]

type date = i64;

An ordinal day since an epoch. The Hare epoch (zeroth day) 1970 Jan 1st is used for terrestrial chronologies.

type locality[link]

type locality = *timezone;

The locality of a moment. Contains information about how to present a moment's chronological values.

type moment[link]

type moment = struct {
	// The ordinal day (on Earth or otherwise)
// since the Hare epoch (zeroth day) 1970-01-01
date: date, // 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 moment in time, within a locality, interpreted 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 or general 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 = !(invalid | tzdberror | invalidtzif);

All possible errors returned from time::chrono.

type invalid[link]

type invalid = !void;

Invalid moment.

type invalidtzif[link]

type invalidtzif = !void;

Invalid TZif data.

type tzdberror[link]

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

Error concerning the Timezone database.


def EARTH_DAY[link]

def EARTH_DAY: time::duration;

The duration of a day on Earth, in terrestrial (SI) seconds.


def MARS_SOL_MARTIAN: time::duration;

The duration of a solar day on Mars, in Martian seconds.


def MARS_SOL_TERRESTRIAL: time::duration;

The duration of a solar day on Mars, in terrestrial (SI) seconds.

def SECS_1900_1970[link]

def SECS_1900_1970: i64;

The number of seconds between the years 1900 and 1970. This number is deliberately hypothetical since timekeeping before atomic clocks was not accurate enough to account for small changes in time.



The filepath of the system's "leap-seconds.list" file, which contains UTC/TAI leap second data.


let GPS[link]

const GPS: locality;

The GPS (Global Positioning System) "Zulu" timezone as a locality.

let LOCAL[link]

const LOCAL: locality;

The system's locality; the system's local timezone.

This is set during a program's initialisation, where the TZ environment variable is tried, otherwise the /etc/localtime file is tried, otherwise a default is used.

The default timezone is equivalent to that of UTC, with "Local" being the name of both the timezone and its single zero-offset zone.

let MTC[link]

const MTC: locality;

The MTC (Coordinated Mars Time) "Zulu" timezone as a locality.

let TAI[link]

const TAI: locality;

The TAI (International Atomic Time) "Zulu" timezone as a locality.

let TT[link]

const TT: locality;

The TT (Terrestrial Time) "Zulu" timezone as a locality.

let UTC[link]

const UTC: locality;

The UTC (Coordinated Universal Time) "Zulu" timezone as a locality.

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 timekeeping on Mars. Based on TT; 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 tt[link]

const tt: timescale;

Terrestrial Time

Used for astronomical timekeeping. Based on TAI; constant +32.184 offset. Continuous (no leap seconds).

let utc[link]

const utc: timescale;

Coordinated Universal Time

Used as the basis of civil timekeeping. Based on TAI; time-dependent offset. Discontinuous (has leap seconds).

During a program's initialization, this timescale initializes by loading its UTC/TAI leap second data from UTC_LEAPSECS_FILE; otherwise, fails silently. If failed, any attempt to consult UTC leapsec data (like calling utc.to_tai(), utc.from_tai()) causes an abort. This includes chrono::in.


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;

Creates an equivalent moment with a different locality.

If the old and new localities have different timescales, a direct conversion between them will be tried, and will abort if unsuccessful. To avoid this, consider manually converting moments to instants, and those instants between timescales.

fn lookupzone[link]

fn lookupzone(m: *moment) zone;

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

fn new[link]

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

Creates a new moment.

fn strerror[link]

fn strerror(err: error) const str;

Converts an error into a human-friendly string.

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 | tzdberror);

Finds and loads a timezone from the system's Timezone database, normally located at /usr/share/zoneinfo. All timezones provided default to the utc timescale and EARTH_DAY day-length.

fn transform[link]

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