time::chrono+x86_64 +linux

chrono: timescales and chronologies

The time::chrono module provides timescale utilities, and the foundations for chronology with the moment type, an abstract, extendable temporal object.

Hare defines a chronology as a system for naming and ordering moments in time. In practice, it is the combination of a calendar and wall clock. For the Gregorian chronology, see the time::date:: module.

The timescale interface facilitates leapsecond aware convertion of moments. The tai timescale is the default intermediary timescale.

Index

Types

type moment = struct {
	time::instant,
	tsc: *timescale,
};
type timescale = struct {
	name: str,
	abbr: str,
	convto: *tsconverter,
	convfrom: *tsconverter,
};

// Undocumented types:
type tsconverter = fn(ts: *timescale, i: time::instant) ([]time::instant | void | nomem);

Errors

type error = !(tscmismatch | utciniterror);
type tscmismatch = !(*timescale, *timescale);
type utciniterror = !(fs::error | io::error | utf8::invalid);

Constants

def UTC_LEAPSECS_PATH: str = "/usr/share/zoneinfo/leap-seconds.list";

Globals

const gps: timescale;
const mtc: timescale;
const tai: timescale;
const tt: timescale;
const utc: timescale;

// Undocumented globals:
let utc_status: (bool | utciniterror);

Functions

fn add(m: *moment, x: time::duration) moment;
fn compare(a: *moment, b: *moment) (i8 | tscmismatch);
fn convert(m: moment, tscs: *timescale...) ([]moment | nomem);
fn diff(a: *moment, b: *moment) (time::duration | tscmismatch);
fn new(tsc: *timescale, t: time::instant) moment;
fn strerror(e: error) const str;
fn to_instant(m: moment) time::instant;

Types

type moment[permalink] [source]

type moment = struct {
	time::instant,
	tsc: *timescale,
};

A precise moment in time, in reference to a specific timescale. An extension of time::instant coupled with a timescale.

type timescale[permalink] [source]

type timescale = struct {
	name: str,
	abbr: str,
	convto: *tsconverter,
	convfrom: *tsconverter,
};

Represents a scale of time; a time standard. See convert.

type tsconverter[permalink] [source]

Show undocumented member 
type tsconverter = fn(ts: *timescale, i: time::instant) ([]time::instant | void | nomem);

Errors

type error[permalink] [source]

type error = !(tscmismatch | utciniterror);

All possible errors returned from this module.

type tscmismatch[permalink] [source]

type tscmismatch = !(*timescale, *timescale);

Timescale mismatch.

type utciniterror[permalink] [source]

type utciniterror = !(fs::error | io::error | utf8::invalid);

Error initializing the utc timescale.

Constants

def UTC_LEAPSECS_PATH[permalink] [source]

def UTC_LEAPSECS_PATH: str = "/usr/share/zoneinfo/leap-seconds.list";

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

Globals

let gps[permalink] [source]

const gps: timescale;

Global Positioning System Time

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

let mtc[permalink] [source]

const mtc: timescale;

Coordinated Mars Time

Used for timekeeping on Mars. Based on TT; constant factor. Continuous (no leap seconds).

let tai[permalink] [source]

const tai: timescale;

International Atomic Time

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

let tt[permalink] [source]

const tt: timescale;

Terrestrial Time

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

let utc[permalink] [source]

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 leapsecond data from UTC_LEAPSECS_PATH; otherwise, fails silently. If failed, any attempt to consult UTC leapsec data (e.g. calling convert on UTC) causes an abort. This includes time::date::in.

let utc_status[permalink] [source]

Show undocumented member 
let utc_status: (bool | utciniterror);

Functions

fn add[permalink] [source]

fn add(m: *moment, x: time::duration) moment;

Adds a time::duration to a moment with time::add.

fn compare[permalink] [source]

fn compare(a: *moment, b: *moment) (i8 | tscmismatch);

Compares two moments. Returns -1 if a precedes b, 0 if a and b are simultaneous, or +1 if b precedes a.

tscmismatch is returned if the timescales of the two moments are different.

fn convert[permalink] [source]

fn convert(m: moment, tscs: *timescale...) ([]moment | nomem);

Converts a moment from one timescale to the next exhaustively. The final conversion result is returned. For each considered pair of timescales, if neither implements conversion from the first to the second, a two-step intermediary tai conversion will occur. If given zero timescales, the given moment is returned. The caller must free the result.

fn diff[permalink] [source]

fn diff(a: *moment, b: *moment) (time::duration | tscmismatch);

Returns the time::duration between two moments, from a to b.

tscmismatch is returned if the timescales of the two moments are different.

fn new[permalink] [source]

fn new(tsc: *timescale, t: time::instant) moment;

Creates a new moment.

fn strerror[permalink] [source]

fn strerror(e: error) const str;

Converts an error into a human-friendly string. The result may be statically allocated.

fn to_instant[permalink] [source]

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

Extracts the time::instant of the given moment.