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 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);
fn transform(moment, time::duration) moment;
Types
type epochal
type epochal = i64;
An ordinal day (on Earth or otherwise) since the Hare epoch (zeroth day)
1970-01-01
type locality
type locality = *timezone;
The virtual region a moment is interpreted in
type moment
type moment = struct {
date: epochal,
time: time::duration,
loc: locality,
zone: zone,
};
A date & time, within a locality, intepreted 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 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 = !(fs::error | io::error | invalidtzif);
Possible errors returned from tz.
type invalid
type invalid = !void;
This date, time, and locality combination is invalid.
type invalidtzif
type invalidtzif = !void;
Some TZif data is invalid
Constants
def EARTH_DAY
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
def MARS_SOL_MARTIAN: time::duration;
The temporal length of a solar day on Marth, in Martian seconds
def MARS_SOL_TERRESTRIAL
def MARS_SOL_TERRESTRIAL: time::duration;
The temporal length of a solar day on Marth, in Earth (SI) seconds
def SECS_1900_1970
def SECS_1900_1970: i64;
The number of seconds between the years 1900 and 1970.
def UTC_LEAPSECS_FILE
def UTC_LEAPSECS_FILE: str;
The filepath of the leap-seconds.list file
Globals
let LOCAL
const LOCAL: locality;
The system's local timezone, set during initialisation
let MTC
const MTC: locality;
The MTC (Coordinated Mars Time) "Zulu" timezone
let TAI
const TAI: locality;
The TAI (International Atomic Time) "Zulu" timezone
let TT
const TT: timescale;
Terrestrial Time
Used for astronomical timekeeping.
Based on TAI, with a constant offset.
Continuous (no leap seconds).
let UTC
const UTC: locality;
The UTC (Coordinated Universal Time) "Zulu" timezone
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 local solar time on Mars.
Based on TT, with a 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 utc
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
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;
Converts a moment to one in a different locality
fn lookupzone
fn lookupzone(m: *moment) zone;
Finds, sets and returns a moment's currently observed zone
fn new
fn new(date: epochal, time: time::duration, loc: locality) (moment | invalid);
Creates a new moment
fn strerror
fn strerror(err: error) const str;
Converts an error to a human-friendly representation.
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 | 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.
Show undocumented member
fn transform(m: moment, zo: time::duration) moment;