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 type date exception Date val date : {year : int, month : month, day : int, hour : int, minute : int, second : int, offset : Time.time option} -> date val year : date -> int val month : date -> month val day : date -> int val hour : date -> int val minute : date -> int val second : date -> int val weekDay : date -> weekday val yearDay : date -> int val offset : date -> Time.time option val isDst : date -> bool option val localOffset : unit -> Time.time val fromTimeLocal : Time.time -> date val fromTimeUniv : 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

type date

An abstract type whose values represents an instant in a specific time zone.

exception Date

date date_info

creates a canonical date from the given date information. If the resulting date is outside the range supported by the implementation, the Date exception is raised.

Seconds outside the range 0..59 are converted to the equivalent minutes and added to the minutes argument. Similar conversions are performed for minutes to hours, hours to days, days to months, and months to years.

The offset argument provides time zone information. A value of NONE represents the local time zone. A value of (SOME t) corresponds to time t west of UTC. In particular, (SOME Time.zeroTime) is UTC. Offsets outside the range 0..23 are added to the hours (before converting excess hours to days).

Leap years follow the Gregorian calendar. Leap seconds may or may not be ignored. In an implementation that takes account of leap seconds, the seconds function may return 60 or 61 in the rare cases that this is appropriate.

year date

month date

day date

hour date

minute date

second date

weekDay date

yearDay date

offset date

isDst date

return attributes of the value date. The year returned by year uses year 0 as its base. Thus, the date Robin Milner received the Turing award would have year 1991. The function yearDay returns the day of the year, starting from 0, i.e., 1 January is day 0. The value returned by offset date reports time zone information as the amount of time west of UTC. A value of NONE represents the local time zone. The function isDst returns NONE if the system has no information concerning daylight savings time. Otherwise, it returns (SOME dst) where dst is true if daylight savings time is in effect.

localOffset ()

returns the offset from UTC for the local time zone.

fromTimeLocal t

fromUTC t

return the date for a given (UTC) time. fromTimeLocal represents the date in the local time zone; it is the analogue of the ISO C function localtime. fromUTC returns the date in the UTC time zone; it is the analogue of the ISO C function gmtime.

If these functions are applied to the same time value, the resulting dates will differ by the offset of the local time zone from UTC.

toTime date

returns the time corresponding to the local date date in the host system. It raises Date if the date date cannot be represented as a Time.time value.

toString date

fmt s date

return a string representation the date date. The result may be wrong if the date is outside the representable Time.time range. Raises Date if the given date is invalid.

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

"Wed Mar 08 19:06:45 1995"

The latter formats the date according to the format string s, following the semantics of the ISO C function strftime. In particular, fmt is locale-dependent. The allowed formats are:

%a	locale's abbreviated weekday name
%A	locale's full weekday name
%b	locale's abbreviated month name
%B	locale's full month name
%c	locale's date and time representation (e.g. Dec 2 06:55:15 1979)
%d	day of month (01..31)
%H	hour (00..23)
%I	hour (01..12)
%j	day of year (001..366)
%m	month number (01..12)
%M	minutes (00..59)
%p	locale's equivalent of the AM/PM designation
%S	seconds (00..61)
%U	week number of year (00..53), with the first Sunday as the first day of week 01
%w	day of week (0..6), with 0 representing Sunday
%W	week number of year (00..53), with the first Monday as the first day of week 01
%x	locale's appropriate date representation
%X	locale's appropriate time representation
%y	year of century (00..99)
%Y	year including century (e.g. 1997)
%Z	time zone name or abbreviation, or the empty string if no time zone information exists
%%	the percent character
%`c`	the character `c`, if `c` is not one of the format characters listed above

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. Note, however, that unlike strftime, the behavior of fmt is defined for the directive %c for any character c.

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. In particular, the functions do not parse time zone abbreviations. 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, using the year, month, day, hour, minute and second information, but ignoring the offset and daylight savings time information. It does not detect invalid dates.

In order to compare dates in two different time zones, the user would have to handle the normalization.

Discussion

In the Date structure, the time type is used to represent intervals since a fixed reference point. These times are always measured in Universal Co-ordinated Time (UTC), also known as Greenwich Mean Time. The implementation of time values, however, is system dependent, so time values are not portable across implementations.

A conforming Date structure should support date values ranging from around 1900 to 2200, although they may be inaccurate with respect to daylight savings time outside the range of dates supported by time values.

Implementation note:

Implementations of this structure might use the ISO C mktime function. Some implementations of this function, when given dates that are out of range, wrap around instead of returning -1. Thus, implementations using mktime need to check the validity of a date before invoking the function.