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
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
in their typespecs (instead of t
).
Developers should avoid creating the Date struct directly and instead rely on the functions provided by this module as well as the ones in 3rd party calendar libraries.
Compares two Date
structs
Calculates the day of the week of a given Date
struct
Returns the number of days in the given date month
Converts an Erlang date tuple to a Date
struct
Converts an Erlang date tuple but raises for invalid dates
Parses the extended “Date and time of day” format described by ISO 8601:2004
Parses the extended “Date and time of day” format described by ISO 8601:2004
Returns true if the year in date
is a leap year
Builds a new ISO date
Converts a Date
struct to an Erlang date tuple
Converts the given datetime to ISO 8601:2004
Converts the given date to a string according to its calendar
Returns the current date in UTC
t() :: %Date{calendar: Calendar.calendar, day: Calendar.day, month: Calendar.month, year: Calendar.year}
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.
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
day_of_week(Calendar.date) :: non_neg_integer
Calculates the day of the week of a given Date
struct.
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.
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
days_in_month(Calendar.date) :: Calendar.day
Returns the number of days in the given date month.
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
from_erl(:calendar.date) :: {:ok, t} | {:error, atom}
Converts an Erlang date tuple to a Date
struct.
Attempting to convert an invalid ISO calendar date will produce an error tuple.
iex> Date.from_erl({2000, 1, 1})
{:ok, ~D[2000-01-01]}
iex> Date.from_erl({2000, 13, 1})
{:error, :invalid_date}
from_erl!(:calendar.date) :: t | no_return
Converts an Erlang date tuple but raises for invalid dates.
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
from_iso8601(String.t) :: {:ok, t} | {:error, atom}
Parses the extended “Date and time of day” format described by ISO 8601:2004.
Timezone offset may be included in the string but they will be simply discarded as such information is not included in naive date times.
Time representations with reduced accuracy are not supported.
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}
from_iso8601!(String.t) :: t | no_return
Parses the extended “Date and time of day” format described by ISO 8601:2004.
Raises if the format is invalid.
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
leap_year?(Calendar.date) :: boolean
Returns true if the year in date
is a leap year.
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
new(Calendar.year, Calendar.month, Calendar.day) :: {: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.
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}
to_erl(Calendar.date) :: :calendar.date
Converts a Date
struct to an Erlang date tuple.
Only supports converting dates which are in the ISO calendar, attempting to convert dates from other calendars will raise.
iex> Date.to_erl(~D[2000-01-01])
{2000, 1, 1}
iex> Date.to_erl(~N[2000-01-01 01:23:45])
{2000, 1, 1}
to_iso8601(Calendar.date) :: String.t
Converts the given datetime to ISO 8601:2004.
Only supports converting datetimes which are in the ISO calendar, attempting to convert datetimes from other calendars will raise.
iex> Date.to_iso8601(~D[2000-02-28])
"2000-02-28"
iex> Date.to_iso8601(~N[2000-02-28 01:23:45])
"2000-02-28"
to_string(Calendar.date) :: String.t
Converts the given date to a string according to its calendar.
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"
utc_today() :: t
Returns the current date in UTC.
iex> date = Date.utc_today()
iex> date.year >= 2016
true
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.4.1/Date.html