POSIX time spans
The type for signed picosecond precision POSIX time spans. A value of this type represent the POSIX duration between two POSIX timestamps.
module Span : sig ... end
POSIX time spans.
POSIX timestamps
val v : (int * int64) -> t
v s
is of_span (Span.v s)
but
- raises Invalid_argument
if
s
is not in the right range. UseSpan
.of_d_ps andof_span
to deal with untrusted input.
val epoch : t
epoch
is 1970-01-01 00:00:00 UTC.
val max : t
max
is 9999-12-31 23:59:59.999999999999 UTC, the latest timestamp representable by Ptime
.
val of_float_s : float -> t option
of_float_s d
is like of_span
but with d
as a floating point second POSIX span d
. This function is compatible with the result of Unix.gettimeofday
. Decimal fractional seconds beyond 1e-12
are truncated.
val to_float_s : t -> float
to_float_s t
is like to_span
but returns a floating point second POSIX span.
Warning. Due to floating point inaccuracies do not expect the function to round trip with of_float_s
; especially near Ptime.min
and Ptime.max
.
truncate ~frac_s t
is t
truncated to the frac_s
decimal fractional second. Effectively this reduces precision without rounding, the timestamp remains in the second it is in. frac_s
is clipped to the range [0
;12
].
Predicates
compare t t'
is a total order on timestamps that is compatible with timeline order.
POSIX arithmetic
diff t t'
is the signed POSIX span t - t'
that happens between the timestamps t
and t'
.
Time zone offsets between local and UTC timelines
The type for time zone offsets between local and UTC timelines in seconds. This is the signed difference in seconds between the local timeline and the UTC timeline:
tz_offset_s = local - UTC
- A value of
-3600
means that the local timeline is sixty minutes behind the UTC timeline. - A value of
3600
means that the local timeline is sixty minutes ahead the UTC timeline.
Date-time value conversions
The type for big-endian proleptic Gregorian dates. A triple (y, m, d)
with:
y
the year from0
to9999
.0
denotes -1 BCE (this follows the ISO 8601 convention).m
is the month from1
to12
d
is the day from1
to28
,29
,30
or31
depending onm
andy
A date is said to be valid iff the values (y, m, d)
are in the range mentioned above and represent an existing date in the proleptic Gregorian calendar.
type time = (int * int * int) * tz_offset_s
The type for daytimes on a local timeline. Pairs a triple (hh,
mm, ss)
denoting the time on the local timeline and a tz_offset
stating the relationship of the local timeline to the UTC timeline.
The (hh, mm, ss)
components are understood and constrainted as follows:
hh
is the hour from0
to23
.mm
is the minute from0
to59
.ss
is the seconds from0
to60
.60
may happen whenever a leap second is added.
A time
value is said to be valid iff the values (hh, mm, ss)
are in the ranges mentioned above.
of_date_time dt
is the POSIX timestamp corresponding to date-time dt
or None
if dt
has an invalid date, invalid time or the date-time is not in the range [min
;max
].
Leap seconds. Any date-time with a seconds value of 60
, hence representing a leap second addition, is mapped to the date-time that happens 1 second later. Any date-time with a seconds value of 59
is mapped to the POSIX timestamp that represents this instant, if a leap second was subtracted at that point, this is the POSIX timestamp that represents this inexisting instant. See the basics.
val to_date_time : ?tz_offset_s:tz_offset_s -> t -> date * time
to_date_time ~tz_offset_s t
is the date-time of the timestamp t
.
tz_offset_s
hints the time zone offset used for the resulting daytime component (defaults to 0
, i.e. UTC). The offset is not honoured and fallbacks to 0
in case the resulting date-time rendering of the timestamp would yield an invalid date. This means that you should always interpret the resulting time component with the time zone offset it is paired with in the result and not assume it will be the one you gave to the function. Note that for real-world time zone offsets the fallback to 0
will only happen around Ptime.min
and Ptime.max
. Formally the fallback occurs whenever add_span t (Span.of_int_s
tz_offset_s)
is None
.
Leap seconds. No POSIX timestamp can represent a date-time with a leap second added, hence this function will never return a date-time with a 60
seconds value. This function does return inexisting UTC date-times with 59
seconds whenever a leap second is subtracted since POSIX timestamps do represent them. See the basics.
Subsecond precision. POSIX timestamps with subsecond precision are floored, i.e. the date-time always has the second mentioned in the timestamp.
val weekday : ?tz_offset_s:tz_offset_s -> t -> [ `Mon | `Tue | `Wed | `Thu | `Fri | `Sat | `Sun ]
weekday ~tz_offset_s t
is the day in the 7-day week of timestamp t
expressed in the time zone offset ts_offset_s
(defaults to 0
).
This can be used with the time zone offset result of to_date_time
to convert timestamps to denormalized timestamp formats.
RFC 3339 timestamp conversions
val pp_rfc3339_error : Stdlib.Format.formatter -> rfc3339_error -> unit
pp_rfc3339_error ppf e
prints an unspecified representation of e
on ppf
.
val rfc3339_error_to_msg : ('a, [ `RFC3339 of error_range * rfc3339_error ]) Result.result -> ('a, [> `Msg of string ]) Result.result
rfc3339_error_to_msg r
converts RFC 3339 parse errors to error messages.
val of_rfc3339 : ?strict:bool -> ?sub:bool -> ?start:int -> string -> (t * tz_offset_s option * int, [> `RFC3339 of error_range * rfc3339_error ]) Result.result
of_rfc3339 ~strict ~sub ~start s
parses an RFC 3339 date-time
starting at start
(defaults to 0
) in s
to a triple (t, tz, count)
with:
t
the POSIX timestamp (hence on the UTC timeline).tz
, the optional time zone offset found in the timestamp.None
is returned iff the date-time satisfies the unknown local offset convention.count
the number of bytes read starting atstart
to parse the timestamp. Ifsub
isfalse
(default) this is alwaysString.length s - start
andError `Trailing_input
is returned if there are still bytes ins
after the date-time was parsed. Use~sub:true
for allowing trailing input to exist.
If strict
is true
(defaults to false
) the parsing function errors on timestamps with lowercase 'T'
or 'Z'
characters or space separated date and times.
Notes and limitations.
- If
start
is not an index ofs
,Error ((start, start), `Eoi)
is returned. - RFC 3339 allows a few degenerate (I say) timestamps with non-zero time zone offsets to be parsed at the boundaries that correspond to timestamps that cannot be expressed in UTC in RFC 3339 itself (e.g.
0000-01-01T00:00:00+00:01
). The function errors on these timestamps with`Invalid_stamp
as they cannot be represented in the range [min
;max
]. - Leap seconds are allowed on any date-time and handled as in
of_date_time
- Fractional parts beyond the picosecond (
1e-12
) are truncated.
val to_rfc3339 : ?space:bool -> ?frac_s:int -> ?tz_offset_s:tz_offset_s -> t -> string
to_rfc3339_tz ~space ~frac_s ~tz_offset_s t
formats the timestamp t
according to a RFC 3339 date-time
production with:
tz_offset_s
hints the time zone offset to use, use0
for UTC. The hint is ignored in the following cases: iftz_offset_s
is not an integral number of minutes and its magnitude not in the range permitted by the standard, ifadd_span t (Span.of_int_s tz_offset_s)
isNone
(the resulting timestamp rendering would not be RFC 3339 compliant). If either the hint is ignored ortz_offset_s
is unspecified then the unknown local offset convention is used to render the time zone component.frac_s
, clipped to the range [0
;12
] specifies that exactlyfrac_s
decimal digits of the fractional second oft
are rendered (defaults to0
).space
iftrue
the date and time separator is a space rather than a'T'
(not recommended but may be allowed by the protocol you are dealing with, defaults tofalse
).
val pp_rfc3339 : ?space:bool -> ?frac_s:int -> ?tz_offset_s:tz_offset_s -> unit -> Stdlib.Format.formatter -> t -> unit
pp_rfc3339 ?space ?frac_s ?tz_offset_s () ppf t
is Format.fprintf ppf "%s" (to_rfc3339 ?space ?frac_s ?tz_offset_s t)
.
Pretty printing
val pp_human : ?frac_s:int -> ?tz_offset_s:tz_offset_s -> unit -> Stdlib.Format.formatter -> t -> unit
pp_human ~frac_s ~tz_offset_s () ppf t
prints an unspecified, human readable, locale-independent, representation of t
with:
tz_offset_s
hints the time zone offset to use. The hint is ignored in the following cases: iftz_offset_s
is not an integral number of minutes and its magnitude not in the range permitted by the standard, ifadd_span t (Span.of_int_s tz_offset_s)
isNone
. If either the hint is ignored ortz_offset_s
is unspecified then RFC 3339's unknown local offset convention is used to render the time zone component.frac_s
clipped to the range [0
;12
] specifies that exactlyfrac_s
decimal digits of the fractional second oft
are rendered (defaults to0
).
Note. The output of this function is similar to but not compliant with RFC 3339, it should only be used for presentation, not as a serialization format.
val pp : Stdlib.Format.formatter -> t -> unit
pp
is pp_human ~tz_offset_s:0
.
val dump : Stdlib.Format.formatter -> t -> unit
dump ppf t
prints an unspecified raw representation of t
on ppf
.