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

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

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 ISO8601:2004
from_iso8601!(string): Parses the extended “Date and time of day” format described by ISO8601:2004
new(year, month, day): Builds a new ISO date
to_erl(date): Converts a Date struct to an Erlang date tuple
to_iso8601(date): Converts the given date time to ISO8601
to_string(date): Converts the given date to a string according to its calendar

Types

t()

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

Functions

from_erl(arg)

from_erl(:calendar.date) :: {:ok, Date.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) :: 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, Date.t} | {:error, atom}

Parses the extended “Date and time of day” format described by ISO8601: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) :: Date.t | no_return

Parses the extended “Date and time of day” format described by ISO8601: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

new(year, month, day)

new(Calendar.year, Calendar.month, Calendar.day) ::
  {:ok, Date.t} |
  {:error, atom}

Builds a new ISO date.

Expects all values to be integers. Returns {:ok, time} if each entry fits its appropriate range, returns :error 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(date)

to_erl(Date.t) :: :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}

to_iso8601(date)

to_iso8601(Date.t) :: String.t

Converts the given date time to ISO8601.

Only supports converting date times which are in the ISO calendar, attempting to convert date times from other calendars will raise.

Examples

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

to_string(date)

to_string(Date.t) :: 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"