Date — Elixir v1.16.3

Search documentation of Elixir

# View Source Date (Elixir v1.16.3)

A Date struct and functions.

The Date struct contains the fields year, month, day and calendar. New dates can be built with the `new/3` function or using the `~D` (see `sigil_D/2`) sigil:

    iex> ~D[2000-01-01]
    ~D[2000-01-01]

Both `new/3` and sigil return a struct where the date fields can be accessed directly:

    iex> date = ~D[2000-01-01]
    iex> date.year
    2000
    iex> date.month
    1

The functions on this module work with the `Date` struct as well as any struct that contains the same fields as the `Date` struct, such as `NaiveDateTime` and `DateTime`. Such functions expect `Calendar.date/0` in their typespecs (instead of `t/0`).

Developers should avoid creating the Date structs directly and instead rely on the functions provided by this module as well as the ones in third-party calendar libraries.

## Comparing dates

Comparisons in Elixir using `==/2`, `>/2`, `</2` and similar are structural and based on the `Date` struct fields. For proper comparison between dates, use the `compare/2` function. The existence of the `compare/2` function in this module also allows using `Enum.min/2` and `Enum.max/2` functions to get the minimum and maximum date of an `Enum`. For example:

    iex>  Enum.min([~D[2017-03-31], ~D[2017-04-01]], Date)
    ~D[2017-03-31]

## Using epochs

The `add/2` and `diff/2` functions can be used for computing dates or retrieving the number of days between instants. For example, if there is an interest in computing the number of days from the Unix epoch (1970-01-01):

    iex> Date.diff(~D[2010-04-17], ~D[1970-01-01])
    14716

    iex> Date.add(~D[1970-01-01], 14716)
    ~D[2010-04-17]

Those functions are optimized to deal with common epochs, such as the Unix Epoch above or the Gregorian Epoch (0000-01-01).

# Summary

## Types

t()

## Functions

add(date, days)

Adds the number of days to the given `date`.

after?(date1, date2)

Returns `true` if the first date is strictly later than the second.

before?(date1, date2)

Returns `true` if the first date is strictly earlier than the second.

beginning_of_month(date)

Calculates a date that is the first day of the month for the given `date`.

beginning_of_week(date, starting_on \\ :default)

Calculates a date that is the first day of the week for the given `date`.

compare(date1, date2)

Compares two date structs.

convert(date, calendar)

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

convert!(date, calendar)

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

day_of_era(date)

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

day_of_week(date, starting_on \\ :default)

Calculates the day of the week of a given `date`.

day_of_year(date)

Calculates the day of the year of a given `date`.

days_in_month(date)

Returns the number of days in the given `date` month.

diff(date1, date2)

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

end_of_month(date)

Calculates a date that is the last day of the month for the given `date`.

end_of_week(date, starting_on \\ :default)

Calculates a date that is the last day of the week for the given `date`.

from_erl(tuple, calendar \\ Calendar.ISO)

Converts an Erlang date tuple to a `Date` struct.

from_erl!(tuple, calendar \\ Calendar.ISO)

Converts an Erlang date tuple but raises for invalid dates.

from_gregorian_days(days, calendar \\ Calendar.ISO)

Converts a number of gregorian days to a `Date` struct.

from_iso8601(string, calendar \\ Calendar.ISO)

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

from_iso8601!(string, calendar \\ Calendar.ISO)

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

leap_year?(date)

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

months_in_year(date)

Returns the number of months in the given `date` year.

new(year, month, day, calendar \\ Calendar.ISO)

Builds a new ISO date.

new!(year, month, day, calendar \\ Calendar.ISO)

Builds a new ISO date.

quarter_of_year(date)

Calculates the quarter of the year of a given `date`.

range(first, last)

Returns a range of dates.

range(first, last, step)

Returns a range of dates with a step.

to_erl(date)

Converts the given `date` to an Erlang date tuple.

to_gregorian_days(date)

Converts a `date` struct to a number of gregorian days.

to_iso8601(date, format \\ :extended)

Converts the given `date` to ISO 8601:2019.

to_string(date)

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

utc_today(calendar \\ Calendar.ISO)

Returns the current date in UTC.

year_of_era(date)

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

# Types

Link to this type

# t()

View Source

    @type t() :: %Date{
      calendar: Calendar.calendar(),
      day: Calendar.day(),
      month: Calendar.month(),
      year: Calendar.year()
    }

# Functions

Link to this function

# add(date, days)

View Source (since 1.5.0)

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

Link to this function

# after?(date1, date2)

View Source (since 1.15.0)

    @spec after?(Calendar.date(), Calendar.date()) :: boolean()

Returns `true` if the first date is strictly later than the second.

## Examples

    iex> Date.after?(~D[2022-02-02], ~D[2021-01-01])
    true
    iex> Date.after?(~D[2021-01-01], ~D[2021-01-01])
    false
    iex> Date.after?(~D[2021-01-01], ~D[2022-02-02])
    false

Link to this function

# before?(date1, date2)

View Source (since 1.15.0)

    @spec before?(Calendar.date(), Calendar.date()) :: boolean()

Returns `true` if the first date is strictly earlier than the second.

## Examples

    iex> Date.before?(~D[2021-01-01], ~D[2022-02-02])
    true
    iex> Date.before?(~D[2021-01-01], ~D[2021-01-01])
    false
    iex> Date.before?(~D[2022-02-02], ~D[2021-01-01])
    false

Link to this function

# beginning_of_month(date)

View Source (since 1.11.0)

    @spec beginning_of_month(Calendar.date()) :: t()

Calculates a date that is the first day of the month for the given `date`.

## Examples

    iex> Date.beginning_of_month(~D[2000-01-31])
    ~D[2000-01-01]
    iex> Date.beginning_of_month(~D[2000-01-01])
    ~D[2000-01-01]
    iex> Date.beginning_of_month(~N[2000-01-31 01:23:45])
    ~D[2000-01-01]

Link to this function

# beginning_of_week(date, starting_on \\ :default)

View Source (since 1.11.0)

    @spec beginning_of_week(Calendar.date(), starting_on :: :default | atom()) :: t()

Calculates a date that is the first day of the week for the given `date`.

If the day is already the first day of the week, it returns the day itself. For the built-in ISO calendar, the week starts on Monday. A weekday rather than `:default` can be given as `starting_on`.

## Examples

    iex> Date.beginning_of_week(~D[2020-07-11])
    ~D[2020-07-06]
    iex> Date.beginning_of_week(~D[2020-07-06])
    ~D[2020-07-06]
    iex> Date.beginning_of_week(~D[2020-07-11], :sunday)
    ~D[2020-07-05]
    iex> Date.beginning_of_week(~D[2020-07-11], :saturday)
    ~D[2020-07-11]
    iex> Date.beginning_of_week(~N[2020-07-11 01:23:45])
    ~D[2020-07-06]

Link to this function

# compare(date1, date2)

View Source (since 1.4.0)

    @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

Link to this function

# convert(date, calendar)

View Source (since 1.5.0)

    @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}}

Link to this function

# convert!(date, calendar)

View Source (since 1.5.0)

    @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}

Link to this function

# day_of_era(date)

View Source (since 1.8.0)

    @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}

Link to this function

# day_of_week(date, starting_on \\ :default)

View Source (since 1.4.0)

    @spec day_of_week(Calendar.date(), starting_on :: :default | atom()) ::
      Calendar.day_of_week()

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.

An optional `starting_on` value may be supplied, which configures the weekday the week starts on. The default value for it is `:default`, which translates to `:monday` for the built-in ISO calendar. Any other weekday may be given to.

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

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

Link to this function

# day_of_year(date)

View Source (since 1.8.0)

    @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

Link to this function

# days_in_month(date)

View Source (since 1.4.0)

    @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

Link to this function

# diff(date1, date2)

View Source (since 1.5.0)

    @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

Link to this function

# end_of_month(date)

View Source (since 1.11.0)

    @spec end_of_month(Calendar.date()) :: t()

Calculates a date that is the last day of the month for the given `date`.

## Examples

    iex> Date.end_of_month(~D[2000-01-01])
    ~D[2000-01-31]
    iex> Date.end_of_month(~D[2000-01-31])
    ~D[2000-01-31]
    iex> Date.end_of_month(~N[2000-01-01 01:23:45])
    ~D[2000-01-31]

Link to this function

# end_of_week(date, starting_on \\ :default)

View Source (since 1.11.0)

    @spec end_of_week(Calendar.date(), starting_on :: :default | atom()) :: t()

Calculates a date that is the last day of the week for the given `date`.

If the day is already the last day of the week, it returns the day itself. For the built-in ISO calendar, the week ends on Sunday. A weekday rather than `:default` can be given as `starting_on`.

## Examples

    iex> Date.end_of_week(~D[2020-07-11])
    ~D[2020-07-12]
    iex> Date.end_of_week(~D[2020-07-05])
    ~D[2020-07-05]
    iex> Date.end_of_week(~D[2020-07-06], :sunday)
    ~D[2020-07-11]
    iex> Date.end_of_week(~D[2020-07-06], :saturday)
    ~D[2020-07-10]
    iex> Date.end_of_week(~N[2020-07-11 01:23:45])
    ~D[2020-07-12]

Link to this function

# from_erl(tuple, calendar \\ Calendar.ISO)

View Source

    @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}

Link to this function

# from_erl!(tuple, calendar \\ Calendar.ISO)

View Source

    @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

Link to this function

# from_gregorian_days(days, calendar \\ Calendar.ISO)

View Source (since 1.11.0)

    @spec from_gregorian_days(integer(), Calendar.calendar()) :: t()

Converts a number of gregorian days to a `Date` struct.

## Examples

    iex> Date.from_gregorian_days(1)
    ~D[0000-01-02]
    iex> Date.from_gregorian_days(730_485)
    ~D[2000-01-01]
    iex> Date.from_gregorian_days(-1)
    ~D[-0001-12-31]

Link to this function

# from_iso8601(string, calendar \\ Calendar.ISO)

View Source

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

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

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}

Link to this function

# from_iso8601!(string, calendar \\ Calendar.ISO)

View Source

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

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

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

Link to this function

# leap_year?(date)

View Source (since 1.4.0)

    @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

Link to this function

# months_in_year(date)

View Source (since 1.7.0)

    @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

Link to this function

# new(year, month, day, calendar \\ Calendar.ISO)

View Source

    @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}

Link to this function

# new!(year, month, day, calendar \\ Calendar.ISO)

View Source (since 1.11.0)

    @spec new!(Calendar.year(), Calendar.month(), Calendar.day(), Calendar.calendar()) ::
      t()

Builds a new ISO date.

Expects all values to be integers. Returns `date` if each entry fits its appropriate range, raises if the date is invalid.

## Examples

    iex> Date.new!(2000, 1, 1)
    ~D[2000-01-01]
    iex> Date.new!(2000, 13, 1)
    ** (ArgumentError) cannot build date, reason: :invalid_date
    iex> Date.new!(2000, 2, 29)
    ~D[2000-02-29]

Link to this function

# quarter_of_year(date)

View Source (since 1.8.0)

    @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

Link to this function

# range(first, last)

View Source (since 1.5.0)

    @spec range(Calendar.date(), Calendar.date()) :: 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 increasing (`first <= last`) and are always inclusive. For a decreasing range, use `range/3` with a step of -1 as first argument.

## Examples

    iex> Date.range(~D[1999-01-01], ~D[2000-01-01])
    Date.range(~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> range
    Date.range(~D[2001-01-01], ~D[2002-01-01])
    iex> Enum.count(range)
    366
    iex> ~D[2001-02-01] in range
    true
    iex> Enum.take(range, 3)
    [~D[2001-01-01], ~D[2001-01-02], ~D[2001-01-03]]

Link to this function

# range(first, last, step)

View Source (since 1.12.0)

    @spec range(Calendar.date(), Calendar.date(), step :: pos_integer() | neg_integer()) ::
      Date.Range.t()

Returns a range of dates with a step.

## Examples

    iex> range = Date.range(~D[2001-01-01], ~D[2002-01-01], 2)
    iex> range
    Date.range(~D[2001-01-01], ~D[2002-01-01], 2)
    iex> Enum.count(range)
    183
    iex> ~D[2001-01-03] in range
    true
    iex> Enum.take(range, 3)
    [~D[2001-01-01], ~D[2001-01-03], ~D[2001-01-05]]

Link to this function

# to_erl(date)

View Source

    @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}

Link to this function

# to_gregorian_days(date)

View Source (since 1.11.0)

    @spec to_gregorian_days(Calendar.date()) :: integer()

Converts a `date` struct to a number of gregorian days.

## Examples

    iex> Date.to_gregorian_days(~D[0000-01-02])
    1
    iex> Date.to_gregorian_days(~D[2000-01-01])
    730_485
    iex> Date.to_gregorian_days(~N[2000-01-01 00:00:00])
    730_485

Link to this function

# to_iso8601(date, format \\ :extended)

View Source

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

Converts the given `date` to ISO 8601:2019.

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"

Link to this function

# to_string(date)

View Source

    @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"

Link to this function

# utc_today(calendar \\ Calendar.ISO)

View Source (since 1.4.0)

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

Returns the current date in UTC.

## Examples

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

Link to this function

# year_of_era(date)

View Source (since 1.8.0)

    @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}