The Standard ML Basis Library

The Time structure

The structure Time provides an abstract type for representing times and time intervals, and functions for manipulating, converting, writing and reading them.

Synopsis

signature TIME
structure Time : TIME


Interface

eqtype time
exception Time
val zeroTime : time
val fromReal : LargeReal.real -> time
val toReal : time -> LargeReal.real
val toSeconds : time -> LargeInt.int
val toMilliseconds : time -> LargeInt.int
val toMicroseconds : time -> LargeInt.int
val fromSeconds : LargeInt.int -> time
val fromMilliseconds : LargeInt.int -> time
val fromMicroseconds : LargeInt.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 fromString : string -> time option
val scan : (char, 'a) StringCvt.reader -> 'a -> (time * 'a) option


Description

eqtype time

The type used to represent both absolute times and durations of time intervals. Absolute times are represented in the same way as time intervals, and can be thought of as time intervals starting at some fixed reference point. Their discrimination is only conceptual. Consequently, operations can be applied to all meaningful combinations (but also meaningless ones) of absolute times and intervals.

Implementation note:

Time values are required to have fixed-point semantics.

exception Time

Raised when the result of conversions to time or of operations over time is not representable, or when an illegal operation has been attempted.

zeroTime

denotes both the empty time interval and a common reference point for specifying absolute time values. It is equivalent to fromReal 0.0.

Absolute points on the time scale can be thought of as being represented as intervals starting at zeroTime. All time values are greater than or equal to zeroTime. The function Date.fromTimeLocal can be used to see what time zeroTime actually represents in the local timezone.

fromReal r

converts the real number r to the time value denoting r seconds. Depending on the resolution of time, fractions of a microsecond may be lost. Raises Time when the result is not representable.

toReal t

converts the time value t to a real number denoting the value of t in seconds. When the type real has less precision than Time.time (for example, when it is implemented as a single-precision float), information about microseconds or, for very large values, even seconds, may be lost.

toSeconds t

toMilliseconds t

toMicroseconds t

returns the number of full seconds (respectively, millseconds, microseconds) in t; fractions of the time unit are dropped. When this number is not representable by int, the exception Overflow is raised. Thus, if t denotes 2.01 seconds, the functions return 2, 2010 and 2010000, respectively.

fromSeconds n

fromMilliseconds n

fromMicroseconds n

converts the number n to a time value denoting n seconds (respectively, milliseconds, microseconds). If the result is not representable by time, e.g., n is negative, the exception Time is raised.

t1 + t2

returns a time interval denoting the duration of t1 plus that of t2, when both t1 and t2 are interpreted as intervals. Equivalently, when t1 is interpreted as an absolute time and t2 as an interval, the absolute time that is t2 later than t1 is returned. (Both views are equivalent as absolute times are represented as intervals from zeroTime). When the result is not representable as a time value, the exception Overflow is raised. This operation is commutative.

- (t1, t2)

returns a time interval denoting the duration of t1 minus that of t2, when both t1 and t2 are interpreted as intervals. Equivalently, when t1 is interpreted as an absolute time and t2 as an interval, the absolute time that is t2 earlier than t1 is returned; when both t1 and t2 are interpreted as absolute times, the interval between t1 and t2 is returned. (All views are equivalent as absolute times are represented as intervals from zeroTime). This operation is not defined when t1 is shorter (earlier) than t2; the exception Time is raised in this case.

compare (t1, t2)

returns LESS, EQUAL, or GREATER when the time interval t1 is shorter than, of same length as, or longer than t2, respectively, or the absolute time t1 is earlier than, coincides with, or is later than the absolute time t2.

t1 < t2

t1 <= t2

t1 > t2

t1 >= t2

return true if the corresponding relation holds between the two times.

now ()

returns the current time. Usually interpreted as an absolute time, the time at which the function call was made. Although now does not normally raise an exception, this may happen when it is called at a time that is not representable.

fmt n t

returns a string containing a decimal number representing t in seconds with the fractional part rounded to n decimal digits. If n = 0, there should be no fractional part. Having n < 0 is equivalent to n = 0.

Example:

	  fmt 3 (fromReal 1.8) = "1.800"
	  fmt 0 (fromReal 1.8) = "2"
	  fmt 0 zeroTime = "0"
	  

toString t

returns a string containing a decimal number representing t in seconds with the fractional part rounded to 3 decimal digits. Equivalent to fmt 3 t.

fromString s

scan getc src

scan a time value from a character stream. The recognized format is ([0-9]+(\.[0-9]+)?)|(\.[0-9]+), denoting a number of (possibly fractional) seconds. Initial whitespace is ignored. Both raise Overflow when the value is syntactically correct but not representable.

scan takes a character source src and an reader getc and tries to parse a time value from src. It returns SOME (t,r) where t is the time value denoted by a prefix of src and r is `the rest of' src; or it returns NONE when no prefix of src is a representation of a time value. The type of scan can also be written as

            (char, 'a) StringCvt.reader -> (time, 'a) StringCvt.reader
          

fromString parses a time value from s, returning SOME t where t is the time value denoted by a prefix of s or NONE when no prefix of s is a representation of a time value. Note that the function is equivalent to StringCvt.scanString scan.

See Also

Date, Timer, StringCvt

Last Modified October 4, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies