Module CalendarLib.Date

include Date_sig.S

Datatypes

type field = Period.date_field

The different fields of a date.

since
2.02
type -'a date constraint 'a = [< field ]

Type of a date, without specifying any precision level.

since
2.02
type t = field date

Type of a date.

type day =
| Sun
| Mon
| Tue
| Wed
| Thu
| Fri
| Sat

Days of the week.

type month =
| Jan
| Feb
| Mar
| Apr
| May
| Jun
| Jul
| Aug
| Sep
| Oct
| Nov
| Dec

Months of the year.

type year = int

Year as an int.

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].

Constructors

val make : year -> int -> int -> t
val lmake : year:year -> ?⁠month:int -> ?⁠day:int -> unit -> t

Labelled version of make. The default value of month and day is 1.

raises Out_of_bounds

when a date is outside the Julian period.

raises Undefined

when a date belongs to [October 5th, 1582; October 14th, 1582].

since
1.05
val make_year : int -> [< `Year ] date

make_year y makes a date only represented by its year y. The month and the day of such a date are not relevant.

since
2.02
val make_year_month : int -> int -> [< `Year | `Month ] date

make_year_month y m makes a date only represented by its year y and its month m. The day of such a date is not relevant.

since
2.02
val today : unit -> t

Date of the current day (based on Time_Zone.current ()).

val from_jd : int -> t
val from_mjd : int -> t
val from_day_of_year : year -> int -> t

Getters

val days_in_month : [> `Year | `Month ] date -> int
val day_of_week : t -> day
val day_of_month : t -> int
val day_of_year : t -> int
val week : t -> int
val month : [> `Month ] date -> month
val year : [> `Year ] date -> year
val to_jd : t -> int
val to_mjd : t -> int

Dates are comparable

val equal : 'a date -> 'b date -> bool

Equality function between two dates.

see Utils.Comparable.html#VALequal

Utils.Comparable.equal

since
1.09.0
val compare : 'a date -> 'b date -> int

Comparison function between two dates.

see Utils.Comparable.html#VALcompare

Utils.Comparable.compare

val (>) : 'a date -> 'b date -> bool

Check if the first date is later than the second

val (>=) : 'a date -> 'b date -> bool

Check if the first date is later or equal to the second

val (<) : 'a date -> 'b date -> bool

Check if the first date is earlier than the second

val (<=) : 'a date -> 'b date -> bool

Check if the first date is earlier or equal to the second

val hash : 'a date -> int

Hash function for dates.

see Utils.Comparable.html#VALhash

Utils.Comparable.hash

since
2.0

Boolean operations on dates

val is_valid_date : year -> int -> int -> bool
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.

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
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.

raises 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. So, Monday is 1, Tuesday is 2, ..., and sunday is 7.

val day_of_int : int -> day

Inverse of int_of_day.

raises Invalid_argument

if the argument does not belong to 1; 7.

val int_of_month : month -> int

Convert a month to an integer respecting ISO-8601. So, January is 1, February is 2 and so on.

val month_of_int : int -> month

Inverse of int_of_month.

raises Invalid_argument

if the argument does not belong to 1; 12.

Period

module Period : sig ... end

A period is the number of days between two dates.

Arithmetic operations on dates and periods

val add : 'a date -> 'a Period.period -> 'a date
val sub : 'a date -> 'a date -> [> `Week | `Day ] Period.period

sub d1 d2 returns the period between d1 and d2.

val precise_sub : 'a date -> 'a date -> Period.t

precise_sub d1 d2 returns the period between d1 and d2. It is equivalent to sub, but:

  • the period is expressed with a number of years, months and days, not only with a number of days;
  • it is less efficient.
since
2.03
val rem : 'a date -> 'a Period.period -> 'a date

rem d p is equivalent to add d (Period.opp p).

raises Out_of_bounds

when the resulting date is outside the Julian period.

raises Undefined

when the resulting date belongs to [October 5th, 1582; October 14th, 1582].

val next : 'a date -> [< field ] as a -> 'a date
val prev : 'a date -> [< field ] as a -> 'a date

Operations on years

val is_leap_year : year -> bool

Return true if a year is a leap year; false otherwise.

val same_calendar : year -> year -> bool

Return true if two years have the same calendar; false otherwise.

val days_in_year : ?⁠month:month -> year -> int

Number of days in a year.

days_in_year ~month y returns the number of days in the year y up to the end of the given month. Thus days_in_year ~month:Dec y is the same as days_in_year y.

val weeks_in_year : year -> int

Number of weeks in a year.

val week_first_last : int -> year -> t * t

Return the first and last days of a week in a year.

since
1.08
val nth_weekday_of_month : year -> month -> day -> int -> t

nth_weekday_of_month y m d n returns the n-th day d in the month m of the year y (for instance the 3rd Thursday of the month).

since
1.09.0
val century : year -> int
val millenium : year -> int
val solar_number : year -> int

Solar number.

In the Julian calendar there is a one-to-one relationship between the Solar number and the day on which a particular date falls.

val indiction : year -> int

Indiction.

The Indiction was used in the middle ages to specify the position of a year in a 15 year taxation cycle. It was introduced by emperor Constantine the Great on 1 September 312 and ceased to be used in 1806.

The Indiction has no astronomical significance.

val golden_number : year -> int

Golden number.

Considering that the relationship between the moon's phases and the days of the year repeats itself every 19 years, it is natural to associate a number between 1 and 19 with each year. This number is the so-called Golden number.

val epact : year -> int

Epact.

The Epact is a measure of the age of the moon (i.e. the number of days that have passed since an "official" new moon) on a particular date.

val easter : year -> t

Easter Sunday.

In the Christian world, Easter (and the days immediately preceding it) is the celebration of the death and resurrection of Jesus in (approximately) AD 30.

val carnaval : year -> t

Carnaval Monday. carnaval y is easter y - 48.

since
1.09.0
val mardi_gras : year -> t

Mardi Gras. mardi_gras y is easter y - 47.

since
1.09.0
val ash : year -> t

Ash Wednesday. ash y is easter y - 46.

since
1.09.0
val palm : year -> t

Palm Sunday. palm y is easter y - 7.

since
1.09.0
val easter_friday : year -> t

Easter Friday. easter_friday y is easter y - 2.

since
1.09.0
val easter_saturday : year -> t

Easter Saturday. easter_saturday y is easter y - 1.

since
1.09.0
val easter_monday : year -> t

Easter Monday. easter_monday y is easter y + 1.

since
1.09.0
val ascension : year -> t

Ascension. ascension y is easter y + 39.

since
1.09.0
val withsunday : year -> t

Withsunday. withsunday y is easter y + 49.

since
1.09.0
val withmonday : year -> t

Withmonday. withmonday y is easter y + 50.

since
1.09.0
val corpus_christi : year -> t

Feast of Corpus Christi. corpus_christi y is easter + 60.

since
1.09.0