(* time utility routines for ocaml
   Copyright (C) 2002,2003 Shawn Wagner <raevnos@pennmush.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.
	 
   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.
	 
   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*)

(** Time utility functions to fill in gaps in the Unix library and to
be more to my liking. *)


(** {1 Time-related structures} *)

(** Structure for high-resolution time *)
type timeval = {
  tv_sec: int32; (** Seconds *)
  tv_usec: int32 (** Microseconds *)
}

(** {1 Getting the time}

These are like [Unix.BLAH], but storing the time in int32 rather than float. *)

(** Return the current time *)
val time: unit -> int32

(** Take a time and return a [Unix.tm] using UTC *)
val gmtime: int32 -> Unix.tm

(** Take a time and return a [Unix.tm] using the local time zone *)
val localtime: int32 -> Unix.tm

(** Turn a [Unix.tm] into the current time plus a normalized [Unix.tm] *)
val mktime: Unix.tm -> int32 * Unix.tm

(** Return a high-precision time. Like [Unix.gettimeofday], but
returns a [timeval] instead of a float.  *)
val gettimeofday: unit -> timeval

(** {1 Manipulating time} *)

(** [difftime past now] returns the number of seconds between the two times *)
val difftime: int32 -> int32 -> float

(** {1 Pretty-printing a time} *)

(** Wrapper for the C strftime() function. See local documentation for
it for information on the string argument (strftime()'s format
argument) *)
val format_tm: string -> Unix.tm -> string

(** Same taking a time in seconds *)
val format_time: string -> int32 -> string

(** Wrapper for the C strptime() function. The first argument is the format
  string, the second argument is string to parse. See [man strptime] for
  information on the format string *)
val parse_tm: string -> string-> Unix.tm

(** Same returning time in seconds *)
val parse_time: string -> string-> int32

(** Returns the time as a string with trailing newline *)
val ctime: int32 -> string

(** Same as [ctime] but takes a [Unix.tm] *)
val asctime: Unix.tm -> string

(** Time as a string without trailing newline *)
val time_string: int32 -> string

(** Same as [time_string] but takes a [Unix.tm] *)
val tm_string: Unix.tm -> string