SRFI-19 Time

A time object has type, seconds and nanoseconds fields representing a point in time starting from some epoch. This is an arbitrary point in time, not just a time of day. Although times are represented in nanoseconds, the actual resolution may be lower.

The following variables hold the possible time types. For instance (current-time time-process) would give the current CPU process time.

Variable: time-utc

Universal Coordinated Time (UTC).

Variable: time-tai

International Atomic Time (TAI).

Variable: time-monotonic

Monotonic time, meaning a monotonically increasing time starting from an unspecified epoch.

Note that in the current implementation time-monotonic is the same as time-tai, and unfortunately is therefore affected by adjustments to the system clock. Perhaps this will change in the future.

Variable: time-duration

A duration, meaning simply a difference between two times.

Variable: time-process

CPU time spent in the current process, starting from when the process began.

Variable: time-thread

CPU time spent in the current thread. Not currently implemented.

Function: time? obj

Return #t if obj is a time object, or #f if not.

Function: make-time type nanoseconds seconds

Create a time object with the given type, seconds and nanoseconds.

Function: time-type time

Function: time-nanosecond time

Function: time-second time

Function: set-time-type! time type

Function: set-time-nanosecond! time nsec

Function: set-time-second! time sec

Get or set the type, seconds or nanoseconds fields of a time object.

set-time-type! merely changes the field, it doesn’t convert the time value. For conversions, see SRFI-19 Time/Date conversions.

Function: copy-time time

Return a new time object, which is a copy of the given time.

Function: current-time [type]

Return the current time of the given type. The default type is time-utc.

Note that the name current-time conflicts with the Guile core current-time function (see Time) as well as the SRFI-18 current-time function (see SRFI-18 Time). Applications wanting to use more than one of these functions will need to refer to them by different names.

Function: time-resolution [type]

Return the resolution, in nanoseconds, of the given time type. The default type is time-utc.

Function: time<=? t1 t2

Function: time<? t1 t2

Function: time=? t1 t2

Function: time>=? t1 t2

Function: time>? t1 t2

Return #t or #f according to the respective relation between time objects t1 and t2. t1 and t2 must be the same time type.

Function: time-difference t1 t2

Function: time-difference! t1 t2

Return a time object of type time-duration representing the period between t1 and t2. t1 and t2 must be the same time type.

time-difference returns a new time object, time-difference! may modify t1 to form its return.

Function: add-duration time duration

Function: add-duration! time duration

Function: subtract-duration time duration

Function: subtract-duration! time duration

Return a time object which is time with the given duration added or subtracted. duration must be a time object of type time-duration.

add-duration and subtract-duration return a new time object. add-duration! and subtract-duration! may modify the given time to form their return.