The Standard ML Basis Library

The Date structure

The Date structure provides functions for converting between times and dates, and formatting and scanning dates.

Synopsis

signature DATE
structure Date : DATE


Interface

datatype weekday
  = Mon
  | Tue
  | Wed
  | Thu
  | Fri
  | Sat
  | Sun
datatype month
  = Jan
  | Feb
  | Mar
  | Apr
  | May
  | Jun
  | Jul
  | Aug
  | Sep
  | Oct
  | Nov
  | Dec
datatype date
  = DATE of {year : int, month : month, day : int, hour : int, minute : int, second : int, wday : weekday option, yday : int option, isDst : bool option}
exception Date
val fromTime : Time.time -> date
val fromUTC : Time.time -> date
val toTime : date -> Time.time
val toString : date -> string
val fmt : string -> date -> string
val fromString : string -> date option
val scan : (char, 'a) StringCvt.reader -> 'a -> (date, 'a) option
val compare : (date * date) -> order


Description

datatype weekday

datatype month

datatype date

A date value provides a standard, calendar/clock representation of time.

• year specifies the year in the Gregorian calendar, e.g., 1995.
• day specifies the day of the month, with values from 1 to 31.
• hour values range from 0 to 23.
• minute values range from 0 to 59.
• second values range from 0 to 61, the last for handling leap seconds.
• yday values, when defined, range from 0 to 365.
• isDst, when defined, is true when daylight savings time is in effect. Otherwise, the status of daylight savings time is unspecified.

exception Date

fromTime t

returns the local date at time t. The fields wday and yday are guaranteed to be defined, whereas isDst may be NONE if the system cannot determine whether daylight savings time is in effect at the given time.

fromUTC t

is similar to fromTime, but returns the date based on Coordinated Universal Time (UTC), also known as Greenwich Mean Time.

toTime date

returns the time corresponding to the local date date. It ignores the yday and wday fields. It uses the isDst field if it is present and cannot be calculated from the given date. At least the dates in the interval 1970-2030 can be represented as Time.time values. It raises Date if the given date is invalid, and raises Time.Time if the date date cannot be represented as a Time.time value.

The weekday of a given date date can be computed as #wday(fromTime(toTime date)); yday and, if possible, isDst can be handled similarly.

toString date

returns a 24-character string representing the date date in the following format:

"Wed Mar 08 19:06:45 1995"

It ignores the weekday (if supplied) and recomputes it on the basis of the other fields; the result may be wrong if the date is outside the representable Time.time range. Raises Date if the given date is invalid.

fmt s date

formats the date date according to the format string s, following the semantics of the ISO C function strftime. In particular, fmt is locale-dependent. For instance, fmt "%A" date returns the full name of the weekday, such as "Monday", for the given date. For a full description of the fmt syntax, consult a description of strftime. As with toString, it ignores the weekday field (if supplied) and recomputes it on the basis of the other fields; the result may be wrong if the date is outside the representable Time.time range. ! Raises Date if the given date is invalid.

fromString s

scan getc str

scans a 24-character date from a character source after ignoring possible initial whitespace. The format of the string must be precisely as produced by toString. The fields yday and isDst in the resulting date will be NONE. No check of the consistency of the date (weekday, date in the month, ...) is performed. If the scanning fails, NONE is returned.

The function fromString takes a string s as its source of characters. Note that the function fromString is equivalent to StringCvt.scanString scan.

The function scan takes a character stream reader getc and a stream strm. In case of success, it returns SOME(date, rst), where date is the scanned date and rst is the remainder of the stream. The type of scan can also be written as

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

compare (date1, date2)

returns LESS, EQUAL, or GREATER, according as date date1 precedes, equals, or follows date2 in time. It lexicographically compares the dates, ignoring the wday, yday and isDst fields, and does not detect invalid dates.

See Also

StringCvt, Time

Last Modified May 15, 1996
Copyright © 1996 AT&T