@spec add(Calendar.date(), integer()) :: t()

Adds the number of days to the given date.

The days are counted as Gregorian days. The date is returned in the same calendar as it was given in.

Examples

iex> Date.add(~D[2000-01-03], -2)
~D[2000-01-01]
iex> Date.add(~D[2000-01-01], 2)
~D[2000-01-03]
iex> Date.add(~N[2000-01-01 09:00:00], 2)
~D[2000-01-03]
iex> Date.add(~D[-0010-01-01], -2)
~D[-0011-12-30]

@spec compare(Calendar.date(), Calendar.date()) :: :lt | :eq | :gt

Compares two date structs.

Returns :gt if first date is later than the second and :lt for vice versa. If the two dates are equal :eq is returned.

Examples

iex> Date.compare(~D[2016-04-16], ~D[2016-04-28])
:lt

This function can also be used to compare across more complex calendar types by considering only the date fields:

iex> Date.compare(~D[2016-04-16], ~N[2016-04-28 01:23:45])
:lt
iex> Date.compare(~D[2016-04-16], ~N[2016-04-16 01:23:45])
:eq
iex> Date.compare(~N[2016-04-16 12:34:56], ~N[2016-04-16 01:23:45])
:eq

@spec convert(Calendar.date(), Calendar.calendar()) ::
  {:ok, t()} | {:error, :incompatible_calendars}

Converts the given date from its calendar to the given calendar.

Returns {:ok, date} if the calendars are compatible, or {:error, :incompatible_calendars} if they are not.

See also Calendar.compatible_calendars?/2.

Examples

Imagine someone implements Calendar.Holocene, a calendar based on the Gregorian calendar that adds exactly 10,000 years to the current Gregorian year:

iex> Date.convert(~D[2000-01-01], Calendar.Holocene)
{:ok, %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}}

@spec convert!(Calendar.date(), Calendar.calendar()) :: t()

Similar to Date.convert/2, but raises an ArgumentError if the conversion between the two calendars is not possible.

Examples

Imagine someone implements Calendar.Holocene, a calendar based on the Gregorian calendar that adds exactly 10,000 years to the current Gregorian year:

iex> Date.convert!(~D[2000-01-01], Calendar.Holocene)
%Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}

@spec day_of_era(Calendar.date()) :: {Calendar.day(), non_neg_integer()}

Calculates the day-of-era and era for a given calendar date.

Returns a tuple {day, era} representing the day within the era and the era number.

Examples

iex> Date.day_of_era(~D[0001-01-01])
{1, 1}

iex> Date.day_of_era(~D[0000-12-31])
{1, 0}

@spec day_of_week(Calendar.date()) :: Calendar.day()

Calculates the day of the week of a given date.

Returns the day of the week as an integer. For the ISO 8601 calendar (the default), it is an integer from 1 to 7, where 1 is Monday and 7 is Sunday.

Examples

iex> Date.day_of_week(~D[2016-10-31])
1
iex> Date.day_of_week(~D[2016-11-01])
2
iex> Date.day_of_week(~N[2016-11-01 01:23:45])
2
iex> Date.day_of_week(~D[-0015-10-30])
3

@spec day_of_year(Calendar.date()) :: Calendar.day()

Calculates the day of the year of a given date.

Returns the day of the year as an integer. For the ISO 8601 calendar (the default), it is an integer from 1 to 366.

Examples

iex> Date.day_of_year(~D[2016-01-01])
1
iex> Date.day_of_year(~D[2016-11-01])
306
iex> Date.day_of_year(~D[-0015-10-30])
303
iex> Date.day_of_year(~D[2004-12-31])
366

@spec days_in_month(Calendar.date()) :: Calendar.day()

Returns the number of days in the given date month.

Examples

iex> Date.days_in_month(~D[1900-01-13])
31
iex> Date.days_in_month(~D[1900-02-09])
28
iex> Date.days_in_month(~N[2000-02-20 01:23:45])
29

@spec diff(Calendar.date(), Calendar.date()) :: integer()

Calculates the difference between two dates, in a full number of days.

It returns the number of Gregorian days between the dates. Only Date structs that follow the same or compatible calendars can be compared this way. If two calendars are not compatible, it will raise.

Examples

iex> Date.diff(~D[2000-01-03], ~D[2000-01-01])
2
iex> Date.diff(~D[2000-01-01], ~D[2000-01-03])
-2
iex> Date.diff(~D[0000-01-02], ~D[-0001-12-30])
3
iex> Date.diff(~D[2000-01-01], ~N[2000-01-03 09:00:00])
-2

@spec from_erl(:calendar.date(), Calendar.calendar()) :: {:ok, t()} | {:error, atom()}

Converts an Erlang date tuple to a Date struct.

Only supports converting dates which are in the ISO calendar, or other calendars in which the days also start at midnight. Attempting to convert dates from other calendars will return an error tuple.

Examples

iex> Date.from_erl({2000, 1, 1})
{:ok, ~D[2000-01-01]}
iex> Date.from_erl({2000, 13, 1})
{:error, :invalid_date}

@spec from_erl!(:calendar.date(), Calendar.calendar()) :: t()

Converts an Erlang date tuple but raises for invalid dates.

Examples

iex> Date.from_erl!({2000, 1, 1})
~D[2000-01-01]
iex> Date.from_erl!({2000, 13, 1})
** (ArgumentError) cannot convert {2000, 13, 1} to date, reason: :invalid_date

@spec from_iso8601(String.t(), Calendar.calendar()) :: {:ok, t()} | {:error, atom()}

Parses the extended "Dates" format described by ISO 8601:2004.

The year parsed by this function is limited to four digits.

Examples

iex> Date.from_iso8601("2015-01-23")
{:ok, ~D[2015-01-23]}

iex> Date.from_iso8601("2015:01:23")
{:error, :invalid_format}

iex> Date.from_iso8601("2015-01-32")
{:error, :invalid_date}

@spec from_iso8601!(String.t(), Calendar.calendar()) :: t()

Parses the extended "Dates" format described by ISO 8601:2004.

Raises if the format is invalid.

Examples

iex> Date.from_iso8601!("2015-01-23")
~D[2015-01-23]
iex> Date.from_iso8601!("2015:01:23")
** (ArgumentError) cannot parse "2015:01:23" as date, reason: :invalid_format

@spec leap_year?(Calendar.date()) :: boolean()

Returns true if the year in the given date is a leap year.

Examples

iex> Date.leap_year?(~D[2000-01-01])
true
iex> Date.leap_year?(~D[2001-01-01])
false
iex> Date.leap_year?(~D[2004-01-01])
true
iex> Date.leap_year?(~D[1900-01-01])
false
iex> Date.leap_year?(~N[2004-01-01 01:23:45])
true

@spec months_in_year(Calendar.date()) :: Calendar.month()

Returns the number of months in the given date year.

Example

iex> Date.months_in_year(~D[1900-01-13])
12

@spec new(Calendar.year(), Calendar.month(), Calendar.day(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

Builds a new ISO date.

Expects all values to be integers. Returns {:ok, date} if each entry fits its appropriate range, returns {:error, reason} otherwise.

Examples

iex> Date.new(2000, 1, 1)
{:ok, ~D[2000-01-01]}
iex> Date.new(2000, 13, 1)
{:error, :invalid_date}
iex> Date.new(2000, 2, 29)
{:ok, ~D[2000-02-29]}

iex> Date.new(2000, 2, 30)
{:error, :invalid_date}
iex> Date.new(2001, 2, 29)
{:error, :invalid_date}

@spec quarter_of_year(Calendar.date()) :: non_neg_integer()

Calculates the quarter of the year of a given date.

Returns the day of the year as an integer. For the ISO 8601 calendar (the default), it is an integer from 1 to 4.

Examples

iex> Date.quarter_of_year(~D[2016-10-31])
4
iex> Date.quarter_of_year(~D[2016-01-01])
1
iex> Date.quarter_of_year(~N[2016-04-01 01:23:45])
2
iex> Date.quarter_of_year(~D[-0015-09-30])
3

@spec range(t(), t()) :: Date.Range.t()

Returns a range of dates.

A range of dates represents a discrete number of dates where the first and last values are dates with matching calendars.

Ranges of dates can be either increasing (first <= last) or decreasing (first > last). They are also always inclusive.

Examples

iex> Date.range(~D[1999-01-01], ~D[2000-01-01])
#DateRange<~D[1999-01-01], ~D[2000-01-01]>

A range of dates implements the Enumerable protocol, which means functions in the Enum module can be used to work with ranges:

iex> range = Date.range(~D[2001-01-01], ~D[2002-01-01])
iex> Enum.count(range)
366
iex> Enum.member?(range, ~D[2001-02-01])
true
iex> Enum.reduce(range, 0, fn _date, acc -> acc - 1 end)
-366

@spec to_erl(Calendar.date()) :: :calendar.date()

Converts the given date to an Erlang date tuple.

Only supports converting dates which are in the ISO calendar, or other calendars in which the days also start at midnight. Attempting to convert dates from other calendars will raise.

Examples

iex> Date.to_erl(~D[2000-01-01])
{2000, 1, 1}

iex> Date.to_erl(~N[2000-01-01 00:00:00])
{2000, 1, 1}

@spec to_iso8601(Calendar.date(), :extended | :basic) :: String.t()

Converts the given date to ISO 8601:2004.

By default, Date.to_iso8601/2 returns dates formatted in the "extended" format, for human readability. It also supports the "basic" format through passing the :basic option.

Only supports converting dates which are in the ISO calendar, or other calendars in which the days also start at midnight. Attempting to convert dates from other calendars will raise an ArgumentError.

Examples

iex> Date.to_iso8601(~D[2000-02-28])
"2000-02-28"

iex> Date.to_iso8601(~D[2000-02-28], :basic)
"20000228"

iex> Date.to_iso8601(~N[2000-02-28 00:00:00])
"2000-02-28"

@spec to_string(Calendar.date()) :: String.t()

Converts the given date to a string according to its calendar.

Examples

iex> Date.to_string(~D[2000-02-28])
"2000-02-28"
iex> Date.to_string(~N[2000-02-28 01:23:45])
"2000-02-28"
iex> Date.to_string(~D[-0100-12-15])
"-0100-12-15"

@spec utc_today(Calendar.calendar()) :: t()

Returns the current date in UTC.

Examples

iex> date = Date.utc_today()
iex> date.year >= 2016
true

@spec year_of_era(Calendar.date()) :: {Calendar.year(), non_neg_integer()}

Calculates the year-of-era and era for a given calendar year.

Returns a tuple {year, era} representing the year within the era and the era number.

Examples

iex> Date.year_of_era(~D[0001-01-01])
{1, 1}
iex> Date.year_of_era(~D[0000-12-31])
{1, 0}
iex> Date.year_of_era(~D[-0001-01-01])
{2, 0}