Date

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

Summary

Types

t()

Functions

compare(date1, date2)

Compares two Date structs

day_of_week(map)

Calculates the day of the week of a given Date struct

days_in_month(map)

Returns the number of days in the given date month

from_erl(arg)

Converts an Erlang date tuple to a Date struct

from_erl!(tuple)

Converts an Erlang date tuple but raises for invalid dates

from_iso8601(arg)

Parses the extended “Date and time of day” format described by ISO 8601:2004

from_iso8601!(string)

Parses the extended “Date and time of day” format described by ISO 8601:2004

leap_year?(map)

Returns true if the year in date is a leap year

new(year, month, day)

Builds a new ISO date

to_erl(map)

Converts a Date struct to an Erlang date tuple

to_iso8601(map)

Converts the given datetime to ISO 8601:2004

to_string(map)

Converts the given date to a string according to its calendar

utc_today()

Returns the current date in UTC

Types

t()

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

Functions

compare(date1, date2)

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

day_of_week(map)

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.

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

days_in_month(map)

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

from_erl(arg)

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.

Examples

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

from_erl!(tuple)

from_erl!(:calendar.date) :: t | no_return

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

from_iso8601(arg)

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.

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}

from_iso8601!(string)

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.

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

leap_year?(map)

leap_year?(Calendar.date) :: boolean

Returns true if the year in 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

new(year, month, day)

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.

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}

to_erl(map)

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.

Examples

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(map)

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.

Examples

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(map)

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"

utc_today()

utc_today() :: t

Returns the current date in UTC.

Examples

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