calendar 3.0.0 · OCaml Package

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

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.

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

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

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

Getters

val days_in_month : [> `Year | `Month ] date -> 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 : [> `Month ] date -> month

Month. @example month (make 2003 6 26) returns Jun.

val year : [> `Year ] date -> 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.

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

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.

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.

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

add d p returns d + 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]. @example add (make 2003 12 31) (Period.month 1) returns the date 2004-1-31 @example add (make 2003 12 31) (Period.month 2) returns the date 2004-3-2 (following the coercion rule describes in the introduction).

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

next d f returns the date corresponding to the next specified field.

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]. @example next (make 2003 12 31) `Month returns the date 2004-1-31 (i.e. one month later).

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

prev d f returns the date corresponding to the previous specified field.

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]. @example prev (make 2003 12 31) `Year returns the date 2002-12-31 (i.e. one year ago).

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

Century of a year. @example century 2000 returns 20 @example century 2001 returns 21.

val millenium : year -> int

Millenium of a year. @example millenium 2000 returns 2 @example millenium 2001 returns 3.

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

package calendar