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).

Index

Types

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

Errors

type error;
type invalid;
type invalidtzif;

Constants

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

Globals

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;

Functions

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;

Types

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

Errors

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

Constants

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[link]

def MARS_SOL_MARTIAN: time::duration;

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

def MARS_SOL_TERRESTRIAL[link]

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.

def UTC_LEAPSECS_FILE[link]

def UTC_LEAPSECS_FILE: str;

The filepath of the leap-seconds.list file

Globals

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).

Functions

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;