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.

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`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`

`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`

].`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`

.