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