Module Prelude.Time

include module type of struct include Prelude_time end

Time and Date Functions

See: Misha Wolf and Charles Wicksteed, Date and Time Formats, September 15, 1997

exception Parse_error of string

raised when there is an error in strftime or convert's format string

exception NYI of string

raised when a strftime %-escape is Not Yet Implemented

val weekdayname : int -> string

convert an integer 0..6 to the name of a weekday (0 = Sunday)

val monthname : int -> string

convert an integer 0..11 to the name of a month (0 = January)

val gmtime : unit -> Unix.tm

gmtime (): return the Greenwich Mean Time (GMT / UTC +0) for now.

val localtime : unit -> Unix.tm

localtime (): return the localtime for now.

val tz : unit -> int * int

tz (): return local timezone as (hours,minutes) offset from zulu.

val strftime : ?tz:(int * int) -> string -> Unix.tm -> string

format date and time (pure-ocaml implementation of Posix strftime(3))

Bugs:

  • Locale-specific escapes are hard-wired to EN_US
  • %U %V %W escapes are Not Yet Implemented and raise NYI
  • parameter tz

    time zone as (hours,minutes) offset from zulu

  • parameter fmt

    string with %-escapes to format

  • parameter tm

    Unix.tm record representing the time

  • returns

    formatted string

  • raises NYI

    for %-escapes that are Not Yet Implemented: 'U', 'V', 'W'

val w3c : string

w3c time format %Y-%m-%dT%H:%M:%S

Parsing Dates

parse doesn't attempt to parse a free-form date, but rather a date specified by a strftime format; it's to some extent the inverse of strftime.

exception UNSUPPORTED of char

(UNSUPPORTED (c)) is the type of exception raised by tm_of_string for an unsupported strtime escape character c.

type locale = {
  1. full_months : string list;
  2. abbr_months : string list;
  3. full_days : string list;
  4. abbr_days : string list;
  5. ampm : string list;
}

The type of locale-specific data for month names.

val locale : locale

locale is the values for the en_US locale.

val parse : string -> string -> string list

(parse format str) parses str according to strftime format format and returns values for each %-escape in format.

Example of parsing an American-style date format:

(Time.parse "%m/%e/%Y" "7/1/2003") = [|"7"; "1"; "2003"|]
  • raises Invalid_arg

    if format contains an invalid escape.

  • raises Failure

    if str doesn't match format

val tm_of_string : string -> string -> Unix.tm

(tm_of_string format str) parses str according to the strftime format, returning a Unix.tm.

The following strftime escapes are not supported: %j, %I, %l, %U, %V, %W, %Z, and %z.

Example:

(tm_of_string "%c" "Wed Aug  9 09:35:53 2023") = {Unix.tm_sec = 53; tm_min = 35; tm_hour = 9; tm_mday = 9; tm_mon = 7; tm_year = 123; tm_wday = 0; tm_yday = 0; tm_isdst = false}
(tm_of_string "%c" "Wed Aug  9 09:35:53 2023" |> strftime "%c") = "Sun Aug  9 09:35:53 2023"
  • raises Invalid_arg

    if format contains an invalid escape.

  • raises Failure

    if format does not match str