package orsetto

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Conversions between Standard Time, UTC and TAI.

Overview

This module contains a type for representing values of standard time, defined as a reference from Coordinated Universal Time (UTC). It also provides functions for converting values of standard time to and from TAI64 values (see Cf_tai64).

Note: no facility is yet provided here for manipulating time with associated timezone attributes. Converting arbitrary values of UTC time to and from local time is tricky, since daylight savings time rules vary greatly from locality to locality, and some are even subject to change without advance notice.

Note: The historical record of the divergence between TAI and UTC, from the creation of the UTC time scale on January 1, 1960 until the standardization of the leap second on January 1, 1972, is not preserved. During that time period, the offset between TAI and UTC often contained fractions of a second, and time authorities adjusted it frequently and irregularly. This implementation ignores that history, and the offset from TAI to UTC for all points in time prior to January 1, 1972 is ten seconds.

Types
class type unqualified = object ... end

The class type inhabited by object types representing unqualified local time stamps, which comprise a Gregorian calendar date and a civil time synchronized with Coordinated Universal Time (UTC) without localizing time zone offset.

class type epoch = object ... end

The class type inhabited by object types representing time stamps qualified with an integral offset from local time to UTC in minutes.

type utc = private
  1. | UTC of unqualified

The private type inhabited by time stamps in UTC, i.e. with an explicit offset of +00:00.

type local = private
  1. | Local of epoch

The private type inhabited by time stamps qualified with a local timezone offset.

Functions
val is_valid_utc : date:Cf_gregorian.date -> time:Cf_clockface.time -> bool

Use is_valid_utc ~date ~time to check whether date and time comprise a valid point in time on the UTC time scale.

Note: The currently loaded leap second archive is consulted to validate the combination of date and time. The time value 23:59:60 is valid only when the archive contains a positive leap second at the adjust date, and the value 23:59:59 is not valid if the archive contains a negative leap second atdate.

val create : date:Cf_gregorian.date -> time:Cf_clockface.time -> offset:int -> local

Use create ~date ~time ~offset to create a time stamp comprising ~date, ~time and ~offset. Raises Invalid_argument if date and time, adjusted to UTC by offset, do not comprise a valid point in time on the UTC time scale.

val localize : ?offset:int -> utc -> local

Use localize t to convert the UTC time stamp t to a local time stamp. If ~offset is used, then the civil time and calendar date are adjusted accordingly. Raises Invalid_argument if the adjustment to the calendar date would overflow the 64-bit integer representation of the astronomical year.

val local_to_utc : local -> utc

Use local_to_utc t to convert t to the UTC. Raises Invalid_argument in the untypical case that time zone adjustment results in an overflow in the 64-bit integer arithetic for the Gregorian calendar year.

Conversions to RFC 3394 Internet Timestamp
val local_to_inet : local -> string

Use local_to_inet t to make a string representation of t in the Internet Timestamp format, c.f RFC 3339.

val inet_to_local : string -> local

Use inet_to_local s to make a timestamp with the value extracted from s according to the Internet Timestamp format.

Conversions to and from TAI64
val of_tai64 : Cf_tai64.t -> utc

Use of_tai64 t to create the UTC time stamp corresponding to t.

val in_tai64_range : utc -> bool

Using in_tai64_range t returns true if t is within the range of valid TAI64 epochs (see Cf_tai64).

val to_tai64 : utc -> Cf_tai64.t

Use to_tai64 t to create the TAI64 value corresponding to t. Raises Invalid_argument if t is outside the range of valid TAI64 values.

OCaml

Innovation. Community. Security.