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.yeardate.monthThe 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, </2 and similar are structural
and based on the Date struct fields. For proper comparison between
dates, use the compare/2 function.
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):
Date.diff(~D[2010-04-17], ~D[1970-01-01])Date.add(~D[1970-01-01], 14716)Those functions are optimized to deal with common epochs, such as the Unix Epoch above or the Gregorian Epoch (0000-01-01).
Function add/2
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
Date.add(~D[2000-01-03], -2)Date.add(~D[2000-01-01], 2)Date.add(~N[2000-01-01 09:00:00], 2)Date.add(~D[-0010-01-01], -2)Function beginning_of_month/1
Calculates a date that is the first day of the month for the given date.
Examples
Date.beginning_of_month(~D[2000-01-31])Date.beginning_of_month(~D[2000-01-01])Date.beginning_of_month(~N[2000-01-31 01:23:45])Function beginning_of_week/2
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
Date.beginning_of_week(~D[2020-07-11])Date.beginning_of_week(~D[2020-07-06])Date.beginning_of_week(~D[2020-07-11], :sunday)Date.beginning_of_week(~D[2020-07-11], :saturday)Date.beginning_of_week(~N[2020-07-11 01:23:45])Function compare/2
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
Date.compare(~D[2016-04-16], ~D[2016-04-28])This function can also be used to compare across more complex calendar types by considering only the date fields:
Date.compare(~D[2016-04-16], ~N[2016-04-28 01:23:45])Date.compare(~D[2016-04-16], ~N[2016-04-16 01:23:45])Date.compare(~N[2016-04-16 12:34:56], ~N[2016-04-16 01:23:45])Function convert/2
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:
Date.convert(~D[2000-01-01], Calendar.Holocene)Function convert!/2
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:
Date.convert!(~D[2000-01-01], Calendar.Holocene)Function day_of_era/1
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
Date.day_of_era(~D[0001-01-01])Date.day_of_era(~D[0000-12-31])Function day_of_week/2
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
Date.day_of_week(~D[2016-10-31])Date.day_of_week(~D[2016-11-01])Date.day_of_week(~N[2016-11-01 01:23:45])Date.day_of_week(~D[-0015-10-30])Date.day_of_week(~D[2016-10-31], :sunday)Date.day_of_week(~D[2016-11-01], :sunday)Date.day_of_week(~N[2016-11-01 01:23:45], :sunday)Date.day_of_week(~D[-0015-10-30], :sunday)Function day_of_year/1
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
Date.day_of_year(~D[2016-01-01])Date.day_of_year(~D[2016-11-01])Date.day_of_year(~D[-0015-10-30])Date.day_of_year(~D[2004-12-31])Function days_in_month/1
Returns the number of days in the given date month.
Examples
Date.days_in_month(~D[1900-01-13])Date.days_in_month(~D[1900-02-09])Date.days_in_month(~N[2000-02-20 01:23:45])Function diff/2
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
Date.diff(~D[2000-01-03], ~D[2000-01-01])Date.diff(~D[2000-01-01], ~D[2000-01-03])Date.diff(~D[0000-01-02], ~D[-0001-12-30])Date.diff(~D[2000-01-01], ~N[2000-01-03 09:00:00])Function end_of_month/1
Calculates a date that is the last day of the month for the given date.
Examples
Date.end_of_month(~D[2000-01-01])Date.end_of_month(~D[2000-01-31])Date.end_of_month(~N[2000-01-01 01:23:45])Function end_of_week/2
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
Date.end_of_week(~D[2020-07-11])Date.end_of_week(~D[2020-07-05])Date.end_of_week(~D[2020-07-06], :sunday)Date.end_of_week(~D[2020-07-06], :sunday)Date.end_of_week(~D[2020-07-06], :saturday)Date.end_of_week(~N[2020-07-11 01:23:45])Function from_erl/2
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
Date.from_erl({2000, 1, 1})Date.from_erl({2000, 13, 1})Function from_erl!/2
Converts an Erlang date tuple but raises for invalid dates.
Examples
Date.from_erl!({2000, 1, 1})Date.from_erl!({2000, 13, 1})Function from_gregorian_days/2
Converts a number of gregorian days to a Date struct.
Examples
Date.from_gregorian_days(1)Date.from_gregorian_days(730_485)Date.from_gregorian_days(-1)Function from_iso8601/2
Parses the extended "Dates" format described by ISO 8601:2019.
The year parsed by this function is limited to four digits.
Examples
Date.from_iso8601("2015-01-23")Date.from_iso8601("2015:01:23")Date.from_iso8601("2015-01-32")Function from_iso8601!/2
Parses the extended "Dates" format described by ISO 8601:2019.
Raises if the format is invalid.
Examples
Date.from_iso8601!("2015-01-23")Date.from_iso8601!("2015:01:23")Function leap_year?/1
Returns true if the year in the given date is a leap year.
Examples
Date.leap_year?(~D[2000-01-01])Date.leap_year?(~D[2001-01-01])Date.leap_year?(~D[2004-01-01])Date.leap_year?(~D[1900-01-01])Date.leap_year?(~N[2004-01-01 01:23:45])Function months_in_year/1
Returns the number of months in the given date year.
Example
Date.months_in_year(~D[1900-01-13])Function new/4
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
Date.new(2000, 1, 1)Date.new(2000, 13, 1)Date.new(2000, 2, 29)Date.new(2000, 2, 30)Date.new(2001, 2, 29)Function new!/4
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
Date.new!(2000, 1, 1)Date.new!(2000, 13, 1)Date.new!(2000, 2, 29)Function quarter_of_year/1
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
Date.quarter_of_year(~D[2016-10-31])Date.quarter_of_year(~D[2016-01-01])Date.quarter_of_year(~N[2016-04-01 01:23:45])Date.quarter_of_year(~D[-0015-09-30])Function range/2
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
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)
rangeEnum.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 >= 2016Function 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])
