6.49.1 Time spans object–type

Time spans are represented by instances of <time> objects, which is a disjoint object–type. A <time> object can represent both absolute times (typically elapsed times since the Epoch) and positive and negative time spans relative to an arbitrary origin. The internal time representation has nanosecond resolution and it is immutable.

The following bindings are exported by the library (vicare).

Function: <time> make-time {seconds <exact-integer>} {nanoseconds <exact-integer>}

Function: <time> make-time {megaseconds <exact-integer>} {seconds <exact-integer>} {nanoseconds <exact-integer>}

Build and return a new <time> object. If nanoseconds exceeds #e1e9 its value is normalised and the excess added to seconds. If seconds exceeds #e1e6 its value is normalised and the excess added to megaseconds.

Function: <boolean> time? obj

Return #t if obj is a <time> object; otherwise return #f.

Function: <boolean> list-of-times? obj

Return #t if obj is a (possibly empty) proper list of <time> objects; otherwise return #f.

Accessors

Function: <exact-integer> time-seconds {T <time>}

Function: <fixnum> time-nanoseconds {T <time>}

The number of seconds and nanoseconds in the represented time span.

Function: <ratnum> time-ratnum {T <time>}

Function: <flonum> time-flonum {T <time>}

Return a real number representing the time in seconds. This single number is built from seconds and nanoseconds.

Arithmetics

Function: <time> time-addition {T1 <time>} {T <time>} …

Compute the addition between time objects: T1 + T + ... and return a time struct representing it.

Function: <time> time-difference {T1 <time>} {T <time>} …

When only one argument is given: return the negation of the time object. When multiple arguments are given, compute the difference between time objects: T1 - (T + ...) and return a time struct representing it.

Time comparison

Function: <boolean> time=? {T0 <time>} {T <time>} …

Return #t if the time objects are equal, else return #f.

Function: <boolean> time!=? {T0 <time>} {T <time>} …

Return #t if the arguments are all different: no two arguments are equal; otherwise return #f. When applied to a single argument: return #f.

Function: <boolean> time<? {T0 <time>} {T <time>} …

Return #t if the time objects are monotonically increasing; else return #f.

Function: <boolean> time<=? {T0 <time>} {T <time>} …

Return #t if the time objects are monotonically non–decreasing; else return #f.

Function: <boolean> time>? {T0 <time>} {T <time>} …

Return #t if the time objects are monotonically decreasing; else return #f.

Function: <boolean> time>=? {T0 <time>} {T <time>} …

Return #t if the time objects are monotonically non–decreasing; else return #f.

Function: <boolean> time-max {T0 <time>} {T <time>} …

Function: <boolean> time-min {T0 <time>} {T <time>} …

Return the maximum or minimum between the arguments.