(*
* Calendar library
* Copyright (C) 2003 Julien SIGNOLES
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License version 2, as published by the Free Software Foundation.
*
* 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 Library General Public License version 2 for more details
*)
(*i $Id: time.mli,v 1.12 2003/09/18 14:34:01 signoles Exp $ i*)
(*S Introduction.
This module implements operations on times.
A time is a triple (hour, minute, second).
If minutes and seconds do not belong to [[0; 59]], they are coerced into this
interval. For example, the time "30 hours, 60 minutes, 80 seconds" is coerced
to the time "31 hours, 1 minute, 20 seconds".
Each time is interpreted in the current time zone (given by
[Time_Zone.current ()]). So, if you change the time zone (by
[Time_Zone.change]), each time consequently changes.
If you want to express a time in another time zone (and do not affect
others times), use the [convert] function.\\ *)
(*S Datatypes. *)
(* Type of a time. *)
type t
(* The different fields of a time. *)
type field = [ `Hour | `Minute | `Second ]
(*S Constructors. *)
(* [make hour minute second] makes the time hour-minute-second. *)
val make : int -> int -> int -> t
(* Labelled version of [make]. The default value is [0] for each argument. *)
val lmake : ?hour:int -> ?minute:int -> ?second:int -> unit -> t
(* The current time based on [Time_Zone.current ()]. *)
val now : unit -> t
(* [midnight ()] is midnight (expressed in the current time zone).
So, it has always the same behaviour as [make 0 0 0]. *)
val midnight : unit -> t
(* [midday ()] is midday (expressed in the current time zone).
So, it has always the same behaviour as [make 12 0 0]. *)
val midday : unit -> t
(*S Conversions. *)
(* [convert t t1 t2] converts the time [t] expressed in the time zone [t1]
to the same time expressed in the time zone [t2].\\
E.g.
[convert (make 20 0 0) (Time_Zone.GMT_Plus 2) (Time_Zone.GMT_Plus 4)]
returns the time 22-0-0. *)
val convert : t -> Time_Zone.t -> Time_Zone.t -> t
(* [from_gmt t] is equivalent to
[convert t Time_Zone.GMT (Time_Zone.current ())]. *)
val from_gmt : t -> t
(* [to_gmt t] is equivalent to
[convert t (Time_Zone.current ()) Time_Zone.GMT]. *)
val to_gmt : t -> t
(* [normalize t] returns [t] such that [hour t] $\in [0; 23]$.
The second component of the result is the number of days needed by the
modification.
E.g. [normalize (make 22 0 0)] returns the time 22-0-0 and 0,
[normalize (make 73 0 0)] returns the time 1-0-0 and 3 and
[normalize (make (-73) 0 0)] returns the time 23-0-0 and (-4). *)
val normalize : t -> t * int
(*S Getters. *)
(* Hour.
E.g. [hour (make 20 0 0)] returns 20. *)
val hour : t -> int
(* Minute.
E.g. [minute (make 20 10 0)] returns 10. *)
val minute : t -> int
(* Second.
E.g. [second (make 20 10 5)] returns 5. *)
val second : t -> int
(* Number of seconds of a time.
E.g. [to_seconds (make 1 2 3)] returns [3600 + 120 + 3 = 3723]. *)
val to_seconds : t -> int
(* Number of minutes of a time. The resulting fractional part represents
seconds.\\
E.g. [to_minutes (make 1 2 3)] returns [60 + 2 + 0.05 = 62.05]. *)
val to_minutes : t -> float
(* Number of hours of a time. The resulting fractional part represents
minutes and seconds.
E.g. [to_hours (make 1 3 0)] returns [1 + 0.05 = 1.05]. *)
val to_hours : t -> float
(*S Boolean operations on times. *)
(* Comparison function between two times.
Same behaviour as [Pervasives.compare]. *)
val compare : t -> t -> int
(* Return [true] is the time is before midday; [false] otherwise.
E.g. both [is_pm (make 10 0 0)] and [is_pm (make 34 0 0)] return [true]. *)
val is_pm : t -> bool
(* Return [true] is the time is after midday; [false] otherwise.
E.g. both [is_am (make 20 0 0)] and [is_am (make 44 0 0)] return [true]. *)
val is_am : t -> bool
(*S Coercions. *)
(* Inverse of [to_seconds]. *)
val from_seconds : int -> t
(* Inverse of [to_minutes]. *)
val from_minutes : float -> t
(* Inverse of [to_hours]. *)
val from_hours : float -> t
(*S Period.
A period is the number of seconds between two times. *)
module Period : sig
include Period.S (*r Arithmetic operations. *)
(* Some other arithmetic operations.\\ *)
(* Number of seconds of a period. *)
val length : t -> int
(* Multiplication. *)
val mul : t -> t -> t
(* Division. *)
val div : t -> t -> t
(* Constructors.\\ *)
(* [make hour minute second] makes a period of the specified length. *)
val make : int -> int -> int -> t
(* Labelled version of [make]. The default value is [0] for each argument. *)
val lmake : ?hour:int -> ?minute:int -> ?second:int -> unit -> t
(* [hour n] makes a period of [n] hours. *)
val hour : int -> t
(* [minute n] makes a period of [n] minutes. *)
val minute : int -> t
(* [second n] makes a period of [n] seconds. *)
val second : int -> t
(* Getters.\\ *)
(* Number of seconds of a period.
E.g. [to_seconds (make 1 2 3)] returns [3600 + 120 + 3 = 3723]. *)
val to_seconds : t -> int
(* Number of minutes of a period. The resulting fractional part represents
seconds.\\
E.g. [to_minutes (make 1 2 3)] returns [60 + 2 + 0.05 = 62.05]. *)
val to_minutes : t -> float
(* Number of hours of a period. The resulting fractional part represents
minutes and seconds.
E.g. [to_hours (make 1 3 0)] returns [1 + 0.05 = 1.05]. *)
val to_hours : t -> float
end
(*S Arithmetic operations on times and periods. *)
(* [app t p] returns [t + p].
E.g. [add (make 20 0 0) (Period.minute 70)] returns the time 21-10-0. *)
val add : t -> Period.t -> t
(* [sub t1 t2] returns the period between [t1] and [t2]. *)
val sub : t -> t -> Period.t
(* [rem t p] is equivalent to [add t (Period.opp p)]. *)
val rem : t -> Period.t -> t
(* [next t f] returns the time corresponding to the next specified field.\\
E.g [next (make 20 3 31) `Minute] returns the time 20-4-31.
(i.e. one minute later). *)
val next : t -> field -> t
(* [prev t f] returns the time corresponding to the previous specified field.\\
E.g [prev (make 20 3 31) `Second] returns the time 20-3-30.
(i.e. one second ago). *)
val prev : t -> field -> t
This document was generated using caml2html