Structure Date

(* Date -- SML Basis Library *)

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,                       (* e.g. 1995 *)
    month  : month,
    day    : int,                       (* 1-31  *)
    hour   : int,                       (* 0-23  *)
    minute : int,                       (* 0-59  *)
    second : int,                       (* 0-61 (allowing for leap seconds) *)
    wday   : weekday option,
    yday   : int option,                (* 0-365 *)
    isDst  : bool option                (* daylight savings time in force *)
  }

exception Date

val fromTime : Time.time -> date
val fromUTC  : Time.time -> date
val toTime   : date -> Time.time

val compare  : date * date -> order

val toString   : date -> string
val fmt        : string -> date -> string
val fromString : string -> date option
val scan       : (char, 'a) StringCvt.reader -> (date, 'a) StringCvt.reader

(* These functions convert times to dates and vice versa, and format
   and scan dates.

   [fromTime t] returns the local date at time t.  The fields year,
   month, day, hour, minute, and second are as expected.  The fields
   wday and yday are guaranteed to be SOME _, whereas isDst may be
   NONE if the system cannot determine whether daylight savings time
   is in effect at the given time.  Corresponds to the ANSI C function 
   `localtime'.

   [fromUTC t] is similar to fromTime, but returns the UTC date at
   time t.  Corresponds to the ANSI C function `gmtime'.

   [toTime dt] returns the time corresponding to the local date dt.
   Ignores the yday and wday fields (it does not matter whether they
   are NONE or SOME _).  Uses the isDst time field if it is present
   (SOME _) and cannot be calculated from the given date.  May raise
   Date if the given date is invalid.  Raises Time.Time if the Date
   cannot be represented as a Time.time value.  At least the dates in
   the interval 1970-2030 can be represented as Time.time values.  
   Corresponds to the ANSI C function `mktime'.

   The weekday wday of a given date dt can be found by evaluating:
       val DATE {wday = SOME wday, ...} = fromTime(toTime dt) 
   The yday and isDst can be computed similarly.

   [compare(d1, d2)] returns LESS, EQUAL, or GREATER, according 
   as date d1 precedes, equals, or follows d2 in time.  Lexicographically
   compares the dates, ignoring wday, yday, and isDst, and does not detect
   invalid dates.

   [toString dt] returns a 24 character string representing the date dt
   in the following format:  
              Wed Mar  8 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.
   Corresponds to the ANSI C function `asctime'.

   [fmt fmtstr dt] formats the date dt according to the format string
   fmtstr.  The format string has the same meaning as with the ANSI C
   function `strftime'.  For instance, (fmt "%A" dt) 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.  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] scans a 24-character date from the string s, after
   possible initial whitespace (blanks, tabs, newlines).  The format
   of the string must be 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.

   [scan getc src] scans a 24-character date from the stream src,
   using the stream accessor getc.  Otherwise works as fromString.  In
   case of success, returns SOME(date, rst) where date is the scanned
   date and rst is the remainder of the stream; otherwise returns
   NONE.
*)