time::chrono
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 date;
type locality;
type moment;
type timescale;
type timezone;
type transition;
type ts_converter;
type zone;
Errors
type error;
type invalid;
type invalidtzif;
type tzdberror;
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 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;
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(locality, date, time::duration) (moment | invalid);
fn strerror(error) const str;
fn to_instant(moment) time::instant;
fn tz(str) (timezone | tzdberror);
fn transform(moment, time::duration) moment;
Types
type date
type date = i64;
An ordinal day since an epoch. The Hare epoch (zeroth day) 1970 Jan 1st is
used for terrestrial chronologies.
type locality
type locality = *timezone;
The locality of a moment. Contains information about how to present a
moment's chronological values.
type moment
type moment = struct {
date: date,
time: time::duration,
loc: locality,
zone: zone,
};
A moment in time, within a locality, interpreted via a chronology.
type timescale
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
type timezone = struct {
name: str,
timescale: *timescale,
daylength: time::duration,
zones: []zone,
transitions: []transition,
posix_extend: str,
};
A timezone; a political or general region with a ruleset regarding offsets
for calculating localized civil time.
type transition
type transition = struct {
when: time::instant,
zoneindex: int,
};
A timezone transition between two zones.
type ts_converter
type ts_converter = fn(i: time::instant) (time::instant | time::error);
Converts one time::instant from one timescale to another.
type zone
type zone = struct {
zoffset: time::duration,
name: str,
abbr: str,
dst: bool,
};
A timezone state, with an offset for calculating localized civil time.
Errors
type error
type error = !(invalid | tzdberror | invalidtzif);
All possible errors returned from time::chrono.
type invalid
type invalid = !void;
Invalid moment.
type invalidtzif
type invalidtzif = !void;
Invalid TZif data.
type tzdberror
type tzdberror = !(invalidtzif | fs::error | io::error);
Error concerning the Timezone database.
Constants
def EARTH_DAY
def EARTH_DAY: time::duration;
The duration of a day on Earth, in terrestrial (SI) seconds.
def MARS_SOL_MARTIAN
def MARS_SOL_MARTIAN: time::duration;
The duration of a solar day on Mars, in Martian seconds.
def MARS_SOL_TERRESTRIAL
def MARS_SOL_TERRESTRIAL: time::duration;
The duration of a solar day on Mars, in terrestrial (SI) seconds.
def SECS_1900_1970
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.
def UTC_LEAPSECS_FILE
def UTC_LEAPSECS_FILE: str;
The filepath of the system's "leap-seconds.list" file, which contains UTC/TAI
leap second data.
Globals
let GPS
const GPS: locality;
The GPS (Global Positioning System) "Zulu" timezone as a locality.
let LOCAL
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
const MTC: locality;
The MTC (Coordinated Mars Time) "Zulu" timezone as a locality.
let TAI
const TAI: locality;
The TAI (International Atomic Time) "Zulu" timezone as a locality.
let TT
const TT: locality;
The TT (Terrestrial Time) "Zulu" timezone as a locality.
let UTC
const UTC: locality;
The UTC (Coordinated Universal Time) "Zulu" timezone as a locality.
let gps
const gps: timescale;
Global Positioning System Time
Used for GPS coordination.
Based on TAI; constant -19 second offset.
Continuous (no leap seconds).
let mtc
const mtc: timescale;
Coordinated Mars Time
Used for timekeeping on Mars.
Based on TT; constant factor.
Continuous (no leap seconds).
let tai
const tai: timescale;
International Atomic Time
The realisation of proper time on Earth's geoid.
Continuous (no leap seconds).
let tt
const tt: timescale;
Terrestrial Time
Used for astronomical timekeeping.
Based on TAI; constant +32.184 offset.
Continuous (no leap seconds).
let utc
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.
Functions
fn fixedzone
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 in
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
fn lookupzone(m: *moment) zone;
Finds, sets and returns a moment's currently observed zone.
fn new
fn new(loc: locality, d: date, t: time::duration) (moment | invalid);
Creates a new moment.
fn strerror
fn strerror(err: error) const str;
Converts an error into a human-friendly string.
fn to_instant
fn to_instant(m: moment) time::instant;
Creates a new time::instant from a moment.
fn tz
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.
Show undocumented member
fn transform(m: moment, zo: time::duration) moment;