Module Ptime.Span

module Span: sig .. end
POSIX time spans.

WARNING. A POSIX time span is not equal to an SI second based time span see the basics.

POSIX time spans

type t = Ptime.span 
The type for signed, picosecond precision, POSIX time spans.
val v : int * int64 -> Ptime.span
v s is like Ptime.Span.of_d_ps s but
Raises Invalid_argument if s is not in the right range. Use Ptime.Span.of_d_ps to deal with untrusted input.
val zero : Ptime.span
zero is the neutral element of Ptime.Span.add.
val of_d_ps : int * int64 -> Ptime.span option
of_d_ps (d, ps) is a span for the signed POSIX picosecond span d * 86_400e12 + ps. d is a signed number of POSIX days and ps a number of picoseconds in the range [0;86_399_999_999_999_999L]. None is returned if ps is not in the right range.
val to_d_ps : Ptime.span -> int * int64
to_d_ps d is the span d as a pair (d, ps) expressing the POSIX picosecond span d * 86_400e12 + ps with ps in the range [0;86_399_999_999_999_999L]
val of_int_s : int -> Ptime.span
of_int_s secs is a span from the signed integer POSIX second span secs.
val to_int_s : Ptime.span -> int option
to_int_s d is the span d as a signed integer POSIX second span, if int's range can represent it (note that this depends on Sys.word_size). Subsecond precision numbers are truncated.
val of_float_s : float -> Ptime.span option
of_float_s secs is a span from the signed floating point POSIX second span d. Subpicosecond precision numbers are truncated.

None is returned if secs cannot be represented as a span. This occurs on Pervasives.nan or if the duration in POSIX days cannot fit on an int (on 32-bit platforms this means the absolute magnitude of the duration is greater than ~2'941'758 years).

val to_float_s : Ptime.span -> float
to_float_s s is the span d as floating point POSIX seconds.

Warning. The magnitude of s may not be represented exactly by the floating point value.


val equal : Ptime.span -> Ptime.span -> bool
equal d d' is true iff d and d' are the same time span.
val compare : Ptime.span -> Ptime.span -> int
compare d d' is a total order on durations that is compatible with signed time span order.


Note. The following functions rollover on overflows.

val neg : Ptime.span -> Ptime.span
neg d is the span d negated.
val add : Ptime.span -> Ptime.span -> Ptime.span
add d d' is d + d'.
val sub : Ptime.span -> Ptime.span -> Ptime.span
sub d d' is d - d'.
val abs : Ptime.span -> Ptime.span
abs d is the absolute value of span d.


val round : frac_s:int -> Ptime.span -> Ptime.span
round ~frac_s t is t rounded to the frac_s decimal fractional second. Ties are rounded away from zero. frac_s is clipped to the range [0;12].
val truncate : frac_s:int -> Ptime.span -> Ptime.span
truncate ~frac_s t is t truncated to the frac_s decimal fractional second. frac_s is clipped to the range [0;12].

Pretty printing

val pp : Format.formatter -> Ptime.span -> unit
pp ppf d prints an unspecified, approximative, representation of d on ppf.

The representation is not fixed-width, depends on the magnitude of d and uses locale independent SI prefixes on seconds and accepted non-SI units. Years are counted in Julian years (365.25 SI-accepted days) as defined by the International Astronomical Union (IUA).

The representation is approximative. In particular beyond 60 seconds it only keeps the two most significant time units and rounds towards the infinity. The latter means that case arising, it always over approximates durations.

Warning Becomes unprecise (but does not overflow) if the absolute number of POSIX days in the time span is greater than max_int / 4 (on 32-bit platforms this is ~735'439 years)

val dump : Format.formatter -> Ptime.span -> unit
dump ppf s prints an unspecified raw representation of d on ppf.