(**************************************************************************)
(* *)
(* This file is part of Calendar. *)
(* *)
(* Copyright (C) 2003-2008 Julien Signoles *)
(* *)
(* you can redistribute it and/or modify it under the terms of the GNU *)
(* Lesser General Public License version 2.1 as published by the *)
(* Free Software Foundation. *)
(* *)
(* It 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. *)
(* *)
(* See the GNU Lesser General Public Licence version 2.1 for more *)
(* details (enclosed in the file LGPL). *)
(* *)
(**************************************************************************)
(*i $Id: date_sig.mli,v 1.5 2008/02/08 13:06:45 signoles Exp $ i*)
(** Date interface. A date may be seen as a triple (year, month, day).
All the dates should belong to
[[January, 1st 4713 BC; January 22th, 3268 AC]] (called the Julian period).
An [Out_of_bounds] exception is raised if you attempt to create a date
outside the Julian period.
If a date [d] does not exists and if [d_bef] (resp. [d_aft]) is
the last (resp. first) existing date before (resp. after) [d],
[d] is automatically coerced to [d_aft + d - d_bef - 1].
For example, both dates "February 29th, 2003" and
"February 30th, 2003" do not exist and they are coerced respectively to the
date "Mars 1st, 2003" and "Mars 2nd, 2003".
This rule is called the coercion rule.
As an exception to the coercion rule, the date belonging to
[[October 5th, 1582; October 14th, 1582]] do not exist and an [Undefined]
exception is raised if you attempt to create such a date.
Those dropped days correspond to the change from the Julian to the Gregorian
calendar. *)
(** Common operations for all date representations.
@since 2.0 (this signature was before inlined in interface of Date). *)
module type S = sig
(** {2 Datatypes} *)
(** Type of a date. *)
type t
(** Days of the week. *)
type day = Sun | Mon | Tue | Wed | Thu | Fri | Sat
(** Months of the year. *)
type month =
Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec
(** Year as an [int]. *)
type year = int
(** The different fields of a date. *)
type field = [ `Year | `Month | `Week | `Day ]
(** {2 Exceptions} *)
exception Out_of_bounds
(** Raised when a date is outside the Julian period. *)
exception Undefined
(** Raised when a date belongs to
[[October 5th, 1582; October 14th, 1582]]. *)
(** {2 Constructors} *)
val make : year -> int -> int -> t
(** [make year month day] makes the date year-month-day. A BC year [y]
corresponds to the year [-(y+1)].
@example years (5 BC) and (1 BC) respectively correspond to years
(-4) and 0.
@raise Out_of_bounds when a date is outside the Julian period.
@raise Undefined when a date belongs to [[October 5th, 1582; October
14th, 1582]]. *)
val lmake : year:year -> ?month:int -> ?day:int -> unit -> t
(** Labelled version of [make].
The default value of [month] and [day] is [1].
@raise Out_of_bounds when a date is outside the Julian period.
@raise Undefined when a date belongs to [[October 5th, 1582; October
14th, 1582]].
@since 1.05 *)
val today : unit -> t
(** Date of the current day (based on [Time_Zone.current ()]). *)
val from_jd : int -> t
(** Make a date from its Julian day.
@example [from_jd 0] returns the date 4713 BC-1-1. *)
val from_mjd : int -> t
(** Make a date from its modified Julian day (i.e. Julian day - 2 400 001).
The Modified Julian day is more manageable than the Julian day.
@example [from_mjd 0] returns the date 1858-11-17. *)
val from_day_of_year: year -> int -> t
(** Make a date from a year and its day of the year.
@example [from_day_of_year 2008 39] returns the date 2008-2-8.
@since 2.0 *)
(** {2 Getters} *)
val days_in_month : t -> int
(** Number of days in the month of a date.
@example [days_in_month (make 2003 6 26)] returns [30]. *)
val day_of_week : t -> day
(** Day of the week.
@example [day_of_week (make 2003 6 26)] returns [Thu]. *)
val day_of_month : t -> int
(** Day of the month.
@example [day_of_month (make 2003 6 26)] returns [26]. *)
val day_of_year : t -> int
(** Day of the year.
@example [day_of_year (make 2003 1 5)] returns [5]
@example [day_of_year (make 2003 12 28)] returns [362]. *)
val week : t -> int
(** Week.
@example [week (make 2000 1 3)] returns [1].
@example [week (make 2000 1 2)] returns [52].
@example [week (make 2003 12 28)] returns [52].
@example [week (make 2003 12 29)] returns [1]. *)
val month : t -> month
(** Month.
@example [month (make 2003 6 26)] returns [Jun]. *)
val year : t -> year
(** Year.
@example [year (make 2003 6 26)] returns [2003]. *)
val to_jd : t -> int
(** Julian day.
@example [to_jd (make (-4712) 1 1)] returns 0. *)
val to_mjd : t -> int
(** Modified Julian day (i.e. Julian day - 2 400 001).
The Modified Julian day is more manageable than the Julian day.
@example [to_mjd (make 1858 11 17)] returns 0. *)
(** {2 Dates are comparable} *)
val equal: t -> t -> bool
(** Equality function between two dates.
@see <Utils.Comparable.html#VALequal> Utils.Comparable.equal
@since 1.09.0 *)
val compare : t -> t -> int
(** Comparison function between two dates.
@see <Utils.Comparable.html#VALcompare> Utils.Comparable.compare *)
val hash: t -> int
(** Hash function for dates.
@see <Utils.Comparable.html#VALhash> Utils.Comparable.hash
@since 2.0 *)
(** {2 Boolean operations on dates} *)
val is_valid_date: year -> int -> int -> bool
(** Check if a date is valid, that is the date has not been coerced to look
like a real date.
@example [is_valid_date 2008 2 8] returns [true]
@example [is_valid_date 2008 2 30] returns [false]
@since 2.0 *)
val is_leap_day : t -> bool
(** Return [true] if a date is a leap day
(i.e. February, 24th of a leap year); [false] otherwise. *)
val is_gregorian : t -> bool
(** Return [true] if a date belongs to the Gregorian calendar;
[false] otherwise. *)
val is_julian : t -> bool
(** Return [true] iff a date belongs to the Julian calendar;
[false] otherwise. *)
(** {2 Coercions} *)
val to_unixtm : t -> Unix.tm
(** Convert a date into the [Unix.tm] type.
The field [is_isdst] is always [false]. The fields [Unix.tm_sec],
[Unix.tm_min] and [Unix.tm_hour] are irrelevant.
@since 1.01 *)
val from_unixtm : Unix.tm -> t
(** Inverse of [to_unixtm]. Assume the current time zone.
@since 1.01 *)
val to_unixfloat : t -> float
(** Convert a date to a float such than [to_unixfloat (make 1970 1 1)]
returns [0.0]. So such a float is convertible with those of the [Unix]
module. The fractional part of the result is always [0].
@since 1.01 *)
val from_unixfloat : float -> t
(** Inverse of [to_unixfloat]. Ignore the fractional part of the argument.
Assume the current time zone.
@since 1.01 *)
val to_business: t -> year * int * day
(** Return the "business week" and the day in this week respecting ISO 8601.
Notice that business weeks at the beginning and end of the year can
sometimes have year numbers which don't match the real year.
@example [to_business (make 2000 1 3)] returns [2000, 1, Mon]
@example [to_business (make 2000 1 2)] returns [1999, 52, Sun]
@example [to_business (make 2003 12 28)] returns [2003, 52, Sun]
@example [to_business (make 2003 12 29)] returns [2004, 1, Mon].
@since 1.09.0 *)
val from_business: year -> int -> day -> t
(** Inverse of [to_business] respecting ISO-8601.
Notice that business weeks at the beginning and end of the year
can sometimes have year numbers which don't match the real year.
@raise Invalid_argument if the date is bad.
@since 1.09.0 *)
val int_of_day : day -> int
(** Convert a day to an integer respecting ISO-8601.
