Date

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 Kernel.sigil_D/2) sigil:

~D[2000-01-01]

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

date = ~D[2000-01-01]
date.year

date.month

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 t:Calendar.date/0 in their typespecs (instead of t: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, last). They are also always inclusive.

Examples

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:

range = Date.range(~D[2001-01-01], ~D[2002-01-01])
Enum.count(range)

Enum.member?(range, ~D[2001-02-01])

Enum.take(range, 3)

Function range/3

Returns a range of dates with a step.

Examples

range = Date.range(~D[2001-01-01], ~D[2002-01-01], 2)
range

Enum.count(range)

Enum.member?(range, ~D[2001-01-03])

Enum.take(range, 3)

Function to_erl/1

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

Date.to_erl(~D[2000-01-01])

Date.to_erl(~N[2000-01-01 00:00:00])

Function to_gregorian_days/1

Converts a date struct to a number of gregorian days.

Examples

Date.to_gregorian_days(~D[0000-01-02])

Date.to_gregorian_days(~D[2000-01-01])

Date.to_gregorian_days(~N[2000-01-01 00:00:00])

Function to_iso8601/2

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

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

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

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

Function to_string/1

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

Examples

Date.to_string(~D[2000-02-28])

Date.to_string(~N[2000-02-28 01:23:45])

Date.to_string(~D[-0100-12-15])

Function utc_today/1

Returns the current date in UTC.

Examples

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

Function year_of_era/1

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

Date.year_of_era(~D[0001-01-01])

Date.year_of_era(~D[0000-12-31])

Date.year_of_era(~D[-0001-01-01])