(* $Id: gregorianDate.mli,v 1.2 2004/08/06 15:56:06 rich Exp $
* Gregorian date calculations, inspired by and derived from Perl's
* Date::Calc.
* Copyright (C) 2004 Merjis Ltd. [OCaml version]
* Copyright (C) 1995 - 2002 by Steffen Beyer [Date::Calc]
*)
(** Gregorian calendar date calculations.
*
* This is a library of useful date calculations using the Gregorian
* calendar, as used in most Western countries, and increasingly in
* the East. Although the Gregorian calendar was adopted in 1582,
* this library extends it back through to 1 AD.
*
* It is inspired and derived from Perl's [Date::Calc].
*
* Copyright (C) 2004 Merjis Ltd., Richard W.M. Jones (OCaml version)
*
* Copyright (C) 1995 - 2002 by Steffen Beyer (Perl [Date::Calc])
*)
val leap_year : int -> bool
(** [leap_year year] returns a boolean indicating whether the year
* is a leap year. *)
val days_in_year : ?month:int -> int -> int
(** [days_in_year year] returns the number of days in the given
* year, taking into account leap years.
*
* [days_in_year ~month year] returns the number of days in the year
* up to the end of the given month. Thus [days_in_year ~month:12 year]
* is the same as [days_in_year year]. *)
val days_in_month : int -> int -> int
(** [days_in_month year month] returns the number of days in the
* given month, taking into account leap years. *)
val weeks_in_year : int -> int
(** [weeks_in_year year] returns the number of weeks in the given year. *)
val check_date : int * int * int -> bool
(** [check_date (year, month, day)] checks that the standard date given
* is valid. *)
val check_time : int * int * int -> bool
(** [check_time (hour, min, sec)] checks that the time given is valid. *)
val check_business_date : int * int -> int -> bool
(** [check_business_date (year, week) dow] checks that the business
* date (ISO 8601) given is valid. *)
val day_of_year : int * int * int -> int
(** [day_of_year (year, month, day)] returns the number of days since
* the beginning of the year. [day_of_year (year, 1, 1)] returns [1]. *)
val date_to_days : int * int * int -> int
(** [date_to_days (year, month, day)] returns the absolute number
* of days since 1st Jan 1 AD (assuming that the Gregorian calendar
* is extended back to this date).
*
* This is very useful in all sorts of comparison operations, such as
* comparing whether one date is later than another (convert both
* dates first using [date_to_days], then compare the integers). *)
val day_of_week : int * int * int -> int
(** [day_of_week (year, month, day)] returns the day number of the
* date, [1] for Monday, [2] for Tuesday, etc. to [7] for Sunday. *)
val week_number : int * int * int -> int
(** [week_number (year, month, day)] returns the week number (ISO 8601)
* in which the date lies. See also {!week_of_year} and
* {!business_of_standard}. *)
val week_of_year : int * int * int -> int * int
(** [week_of_year (year, month, day)] returns the business week (ISO 8601)
* in which the date lies. See also {!business_of_standard}. *)
val monday_of_week : int * int -> int * int * int
(** [monday_of_week (year, week)] given a business week will return
* the standard date of the Monday in that week. *)
val nth_weekday_of_month : int * int -> int -> int -> int * int * int
(** [nth_weekday_of_month (year, month) dow n] returns the n-th
* day in a particular month, for instance the 3rd Thursday of
* the month. If the day does not exist (eg. 5th Friday of
* Feb. 2004), then this function will raise [Not_found]. *)
val business_of_standard : int * int * int -> (int * int) * int
(** [business_of_standard (year, month, day)] returns the
* business week (year, week) and the day of the business week.
* Notice that business weeks at the beginning and end of the year
* can sometimes have year numbers which don't match the real year. *)
val standard_of_business : int * int -> int -> int * int * int
(** [standard_of_business (year, week) dow] given a business week
* (see ISO 8601) and a day of the week, returns the standard
* date of that day. *)
val delta_days : int * int * int -> int * int * int -> int
(** [delta_days d1 d2] returns the number of days in [d2 - d1]. *)
(*
val delta_dhms : int * int * int -> int * int * int -> int * int * int -> int * int * int -> int * (int * int * int)
val delta_ymd : int * int * int -> int * int * int -> int * int * int
val delta_ymdhms : int * int * int -> int * int * int -> int * int * int -> int * int * int -> (int * int * int) * (int * int * int)
val normalize_dhms : int -> (int * int * int) -> int * (int * int * int)
*)
val add_delta_days : int * int * int -> int -> int * int * int
(** [add_delta_days (year,month,day) delta] adds [delta] days to the
* given date, returning the new date. The date given and the result
* date must both be in year >= 1, otherwise the function will
* throw [Invalid_argument]. *)
(*
val add_delta_dhms : int * int * int -> int * int * int -> int -> int * int * int -> (int * int * int) * (int * int * int)
val add_delta_ym : int * int * int -> int * int -> int * int * int
val add_delta_ymd : int * int * int -> int * int * int -> int * int * int
val add_delta_ymdhms : int * int * int -> int * int * int -> int * int * int -> int * int * int -> (int * int * int) * (int * int * int)
*)
val easter_sunday : int -> int * int * int
(** [easter_sunday year] computes Easter Sunday for the given
* year in the Christian calendar. Only years in the range 1583 - 2299
* work (outside this range, the function will throw [Invalid_argument]).
*
* Note the following dates which are derived from Easter Sunday:
*
* Carnival Monday / Rosenmontag / Veille du Mardi Gras = easter sunday - 48
*
* Mardi Gras / Karnevalsdienstag / Mardi Gras = easter sunday - 47
*
* Ash Wednesday / Aschermittwoch / Mercredi des Cendres= easter sunday - 46
*
* Palm Sunday / Palmsonntag / Dimanche des Rameaux = easter sunday - 7
*
* Easter Friday / Karfreitag / Vendredi Saint = easter sunday - 2
*
* Easter Saturday / Ostersamstag / Samedi de Paques = easter sunday - 1
*
* Easter Monday / Ostermontag / Lundi de Paques = easter sunday + 1
*
* Ascension / Christi Himmelfahrt / Ascension = easter sunday + 39
*
* Whitsunday / Pfingstsonntag / Dimanche de Pentecote = easter sunday + 49
*
* Whitmonday / Pfingstmontag / Lundi de Pentecote = easter sunday + 50
*
* Feast of Corpus Christi / Fronleichnam / Fete-Dieu = easter sunday + 60
*)