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
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
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"
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.3.4/Date.html