(* $Id: netdate.mli 1691 2012-02-05 18:29:36Z gerd $
 * ----------------------------------------------------------------------
 *
 *)

(** Support for common date/time parsing and formatting.
 * Many routines refer to the epoch, which for Unix is 
 * 00:00:00 UTC, January 1, 1970.
 *)

type t = {
  year : int;		(** complete year *)
  month : int;		(** 1..12 *)
  day : int;		(** 1..31 *)
  hour : int;           (** 0..23 *)
  minute : int;         (** 0..59 *)
  second : int;         (** 0..60 (60=leapsecond) *)
  nanos : int;          (** nanoseconds, new since Ocamlnet-3.5 *)
  zone : int;		(** in minutes; 60 = UTC+0100 *)
  week_day : int	(** 0 = sunday; -1 if not given *)
}

val localzone : int
  (** The offset in minutes for the local time zone from the UTC.
      This is the zone from the time when the program was started.
      For long-running programs, it is possible that the zone changes.
   *)

val get_localzone : unit -> int
  (** Retrieves the current offset for the local time zone *)

val create : ?localzone:bool -> ?zone:int -> ?nanos:int -> float -> t
  (** Convert the time (seconds since the epoch) to a date/time record 

      The [nanos] are added to the float as nanoseconds.

      If [zone] is set this zone is taken. Otherwise, if
      [localzone] is set, the current local timezone is used. Otherwise,
      UTC is used.
   *)

val parse : ?localzone:bool -> ?zone:int -> string -> t
  (** Parse a string and return a date/time record.

      The following particles are recognized (by example):
      - Date: [1971/06/22]
      - Date: [06/22/1971]
      - Date: [1971-06-22]
      - Date: [22-June-1971]
      - Date: [22.06.1971]
      - Date: [June 22, 1971]
      - Date: [22 June 1971]
      - Date (2 digit year): [06/22/71]
      - Date (2 digit year): [22.06.71]
      - Date (2 digit year): [71-06-22]
      - Date (2 digit year): [22-June-71]
      - Month names ([June], [Jun])
      - Weekday names ([Monday], [Mon])
      - Time: [14:55]
      - Time: [14:55:28]
      - Time: [14:55:28.6754]   (the fractional part is not returned)
      - Time may be preceded by [T]
      - Time zone: identifiers like [UTC], [CET], or [Z]
      - Time zone: [+01:00], [-01:00], only following time
      - Time zone: [+0100], [-0100], only following time

      Years must have 2 or 4 digits. 2-digit years >= 70 are interpreted
      as [1900+x]. 2-digit years < 70 are interpreted as [2000+x].
      Support for 2-digit years will be removed in a future version
      of Ocamlnet. (Support for 3-digit years is already removed in
      Ocamlnet 3.0.)

      Only English names of months and weekdays are recognized.

      A date must be given. Time, time zones, and weekdays are optional.
      A missing time is reported as "00:00:00". A missing weekday is
      reported by setting [week_day=(-1)]. A missing time zone is 
      reported by setting [zone] to the passed default (which is determined
      from the [zone] and [localzone] arguments as for [create]).

      It is not checked whether the parsed numbers make sense
      (e.g. whether months are between 1 and 12).

      Date/time strings as defined in RFC 3339 are supported since
      Ocamlnet 3.0.
   *)

val since_epoch : t -> float
  (** Convert a date/time record into the time (seconds since the epoch),
      rounded down to the next integral number.
   *)

val since_epoch_timespec : t -> (float * int)
  (** Returns the seconds since the epoch as pair [(seconds,nanos)] *)

val since_epoch_approx : t -> float
  (** Same, but the nanos are added to the seconds. The precision of
      floats is not sufficient to represent this precisely, so the
      result is only an approximation.
   *)

val parse_epoch : ?localzone:bool -> ?zone:int -> string -> float
  (** Parse a string and return the time (integral seconds since the epoch) *)

val parse_epoch_timespec : ?localzone:bool -> ?zone:int -> string -> float * int
  (** Parse a string and return the time (seconds and nanos since the epoch) *)
  
val parse_epoch_approx  : ?localzone:bool -> ?zone:int -> string -> float
  (** Parse a string and return the time (approximate seconds since the epoch)
   *)

val format_to : Netchannels.out_obj_channel -> fmt:string -> t -> unit
  (** Format a date/time record according to the format string and outputs
   * the resulting string to the channel.
   *
   * The format string consists of zero or more conversion specifications
   * and ordinary characters.  All ordinary characters are output directly
   * to the channel.  A conversion specification consists of the '%'
   * character and one other character.
   *
   * The conversion specifications are:
   *
   *  - [%A]: full weekday name.
   *  - [%a]: abbreviated weekday name.
   *  - [%B]: full month name.
   *  - [%b]: abbreviated month name.
   *  - [%C]: (year / 100) as an integer; single digits are preceded by a zero.
   *  - [%c]: equivalent to ["%a %b %e %T %Y"].
   *  - [%D]: equivalent to ["%m/%d/%y"].
   *  - [%d]: day of the month as an integer (01-31); single digits are
   *          preceded by a zero.
   *  - [%e]: day of the month as an integer (1-31).
   *  - [%H]: hour (24-hour clock) as an integer (00-23).
   *  - [%h]: the same as %b.
   *  - [%I]: hour (12-hour clock) as an integer (01-12).
   *  - [%j]: day of the year as an integer (001-366).
   *  - [%k]: hour (24-hour clock) as an integer (0-23);
   *          single digits are preceded by a blank.
   *  - [%l]: hour (12-hour clock) as an integer (1-12);
   *          single digits are preceded by a blank.
   *  - [%M]: minute as an integer (00-59).
   *  - [%m]: month as an integer (01-12).
   *  - [%n]: a newline.
   *  - [%p]: either "AM" or "PM" as appropriate.
   *  - [%P]: either "am" or "pm" as appropriate.
   *  - [%R]: equivalent to ["%H:%M"].
   *  - [%r]: equivalent to ["%I:%M:%S %p"].
   *  - [%S]: second as an integer (00-60). This format accepts a precision
        argument, e.g. [%.3S] to print the second with three digits after the
        dot.
   *  - [%T]: equivalent to ["%H:%M:%S"].
   *  - [%t]: a tab.
   *  - [%U]: week number of the year (Sunday as the first day
   *          of the week) as an integer (00-53).
   *  - [%u]  weekday (Monday as the first day of the week) as
   *          an integer (1-7).
   *  - [%w]: weekday (Sunday as the first day of the week) as
   *          an integer (0-6).
   *  - [%X]: representation of the time.
   *  - [%x]: representation of the date.
   *  - [%Y]: year with century as an integer.
   *  - [%y]: year without century as an integer (00-99).
   *  - [%z]: time zone offset from UTC; a leading plus sign
   *        stands for east of UTC, a minus sign for west of UTC, hours and
   *        minutes follow with two digits each and no delimiter between them
   *        (common form for RFC 822 date headers).
   *  - [%:z]: time zone with colon, e.g. +05:00 (new since Ocamlnet 3)
   *  - [%%]: a `%' character.
   *
   *)

val format : fmt:string -> t -> string
  (** Format a date/time record as a string *)

val mk_date : ?localzone:bool -> ?zone:int -> ?nanos:int -> fmt:string -> 
                 float -> string
  (** Format the seconds (plus nanos if present) as a string *)

val mk_mail_date : ?localzone:bool -> ?zone:int -> float -> string
  (** Convert the time (seconds since the epoch) to a date string that
   * conforms to RFC 1123 (which updates RFC 822).
   *
   * Example: ["Sun, 06 Nov 1994 08:49:37 -0500"].
   *)

val mk_usenet_date : ?localzone:bool -> ?zone:int -> float -> string
  (** Convert the time (seconds since the epoch) to a date string that
   * conforms to RFC 1036 (which obsoletes RFC 850).
   *
   * Example: ["Sunday, 06-Nov-94 08:49:37 -0500"].
   *
   * Note that this format has only two digits for the year.
   *)

val mk_internet_date : ?localzone:bool -> ?zone:int -> ?digits:int ->
                         float -> string
  (** Convert the time (seconds since the epoch) to a date string that
   * conforms to RFC 3339. This is the most modern format, and should
   * be used if permitted by the network protocol. Pass in [digits] the
   * number of digits for the fractional part of seconds.
   *
   * Example: ["1996-12-19T16:39:57.89-08:00"].
   *)
