Time structure

Up to index

The Time structure provides an abstract type for representing both absolute times and time intervals, with functions for conversion, arithmetic, comparison, formatting, and parsing. Time values are measured in nanoseconds internally, and conversions to/from seconds, milliseconds, microseconds, and nanoseconds are provided.

Specified by the Standard ML Basis Library.

Synopsis

type time

exception Time

val zeroTime : time
val fromReal : real -> time
val toReal : time -> real
val toSeconds : time -> int
val toMilliseconds : time -> int
val toMicroseconds : time -> int
val toNanoseconds : time -> int
val fromSeconds : int -> time
val fromMilliseconds : int -> time
val fromMicroseconds : int -> time
val fromNanoseconds : int -> time
val + : time * time -> time
val - : time * time -> time
val compare : time * time -> order
val < : time * time -> bool
val <= : time * time -> bool
val > : time * time -> bool
val >= : time * time -> bool
val now : unit -> time
val fmt : int -> time -> string
val toString : time -> string
val scan : (char, 'a) reader -> (time, 'a) reader
val fromString : string -> time option

type time

is an equality type representing both absolute times (relative to the Unix epoch, 1970-01-01T00:00:00Z) and time durations. Both absolute times and intervals are represented identically; the interpretation is contextual. Negative values represent times before the epoch or negative intervals.

exception Time

is raised when a conversion produces a value that cannot be represented as a time value (for example, when fromReal is called with NaN or infinity).

zeroTime

zeroTime denotes an empty interval and serves as the reference point for absolute times. It is equivalent to fromReal(0.0).

fromReal

fromReal r converts r (measured in seconds) to a time value. Raises Time if r is NaN, infinite, or otherwise not representable.

toReal

toReal t (or t.toReal ()) converts the time value t to a real number representing seconds.

toSeconds

toSeconds t (or t.toSeconds ()) returns the number of whole seconds in t, truncated toward zero.

toMilliseconds

toMilliseconds t (or t.toMilliseconds ()) returns the number of whole milliseconds in t, truncated toward zero.

toMicroseconds

toMicroseconds t (or t.toMicroseconds ()) returns the number of whole microseconds in t, truncated toward zero.

toNanoseconds

toNanoseconds t (or t.toNanoseconds ()) returns the number of whole nanoseconds in t.

fromSeconds

fromSeconds n returns the time value corresponding to n seconds.

fromMilliseconds

fromMilliseconds n returns the time value corresponding to n milliseconds.

fromMicroseconds

fromMicroseconds n returns the time value corresponding to n microseconds.

fromNanoseconds

fromNanoseconds n returns the time value corresponding to n nanoseconds.

+

t1 + t2 (or +.t1 t2) returns the sum of the two time values t1 and t2.

-

t1 - t2 (or -.t1 t2) returns the difference of the two time values t1 and t2.

compare

compare (t1, t2) (or t1.compare t2) returns LESS, EQUAL, or GREATER depending on whether t1 is less than, equal to, or greater than t2.

<

t1 < t2 (or <.t1 t2) returns true if t1 is less than t2.

<=

t1 <= t2 (or <=.t1 t2) returns true if t1 is less than or equal to t2.

>

t1 > t2 (or >.t1 t2) returns true if t1 is greater than t2.

>=

t1 >= t2 (or >=.t1 t2) returns true if t1 is greater than or equal to t2.

now

now () returns the current time.

fmt

fmt n t formats t as a decimal number of seconds with n fractional digits. For example, fmt 3 (fromReal 1.5) returns "1.500". Negative time values are formatted with a leading ~.

toString

toString t (or t.toString ()) formats t as a decimal number of seconds with 3 fractional digits. Equivalent to fmt 3 t.

scan

scan getc strm reads a time from a prefix of the character stream strm, after skipping initial whitespace. The time is a decimal number of seconds, optionally signed with ~, - or +, and with an optional fractional part; the sign must be followed immediately by the number, and a decimal point must be followed by at least one digit. Returns SOME (t, rest), or NONE if no time can be read. Digits beyond a nanosecond are discarded. Raises Time if the time is too large to be represented.

fromString

fromString s parses a time from a prefix of the string s, which should be a decimal number of seconds, after skipping initial whitespace. Returns SOME t if successful, NONE otherwise; characters after the number are ignored. Equivalent to StringCvt.scanString scan.