Basic Usage
Some common scenarios with examples
Getting Dates/DateTimes
Getting the current datetime in UTC
iex> DateTime.now
%DateTime{calendar: :gregorian, day: 24, hour: 4, minute: 45, month: 6,
millisecond: 730, second: 8,
timezone: %TimezoneInfo{abbreviation: "UTC", from: :min,
full_name: "UTC", offset_std: 0, offset_utc: 0, until: :max}, year: 2015}
iex> Date.today
%Date{calendar: :gregorian, day: 24, month: 6, year: 2015}
Getting the current datetime in the local timezone
iex> DateTime.local
%DateTime{calendar: :gregorian, day: 23, hour: 23, minute: 45, month: 6,
millisecond: 713, second: 58,
timezone: %TimezoneInfo{abbreviation: "CDT",
from: {:sunday, {{2015, 3, 8}, {2, 0, 0}}}, full_name: "America/Chicago",
offset_std: 60, offset_utc: -360,
until: {:sunday, {{2015, 11, 1}, {1, 0, 0}}}}, year: 2015}
Getting the current datetime in an arbitrary timezone
iex> DateTime.now("Europe/Copenhagen")
%DateTime{calendar: :gregorian, day: 24, hour: 4, minute: 50, month: 6,
millisecond: 308, second: 34,
timezone: %TimezoneInfo{abbreviation: "CEST",
from: {:sunday, {{2015, 3, 29}, {2, 0, 0}}}, full_name: "Europe/Copenhagen",
offset_std: 60, offset_utc: 60,
until: {:sunday, {{2015, 10, 25}, {2, 0, 0}}}}, year: 2015}
Constructing Dates/DateTimes
Constructing a date in UTC
iex> Timex.date({2015, 6, 24})
%Date{calendar: :gregorian, day: 24, month: 6, year: 2015}
iex> Timex.datetime({{2015, 6, 24}, {4, 50, 34}})
%DateTime{calendar: :gregorian, day: 24, hour: 4, minute: 50, month: 6,
millisecond: 0, second: 34,
timezone: %TimezoneInfo{abbreviation: "UTC", from: :min,
full_name: "UTC", offset_std: 0, offset_utc: 0, until: :max}, year: 2015}
Constructing a date in the local timezone
iex> Timex.datetime({{2015, 6, 24}, {4, 50, 34}}, :local)
%DateTime{calendar: :gregorian, day: 24, hour: 4, minute: 50, month: 6,
millisecond: 0, second: 34,
timezone: %TimezoneInfo{abbreviation: "CDT",
from: {:sunday, {{2015, 3, 8}, {2, 0, 0}}}, full_name: "America/Chicago",
offset_std: 60, offset_utc: -360,
until: {:sunday, {{2015, 11, 1}, {1, 0, 0}}}}, year: 2015}
Constructing a date in an arbitrary timezone
iex> Timex.datetime({{2015, 6, 24}, {4, 50, 34}}, "Europe/Copenhagen")
%DateTime{calendar: :gregorian, day: 24, hour: 4, minute: 50, month: 6,
millisecond: 0, second: 34,
timezone: %TimezoneInfo{abbreviation: "CEST",
from: {:sunday, {{2015, 3, 29}, {2, 0, 0}}}, full_name: "Europe/Copenhagen",
offset_std: 60, offset_utc: 60,
until: {:sunday, {{2015, 10, 25}, {2, 0, 0}}}}, year: 2015}
Parsing DateTime strings
Parsing an ISO 8601-formatted DateTime string
# With timezone offset
iex> date = "2015-06-24T04:50:34-05:00"
iex> Timex.parse(date, "{ISO}")
{:ok,
%DateTime{calendar: :gregorian, day: 24, hour: 4, minute: 50, month: 6,
millisecond: 0, second: 34,
timezone: %TimezoneInfo{abbreviation: "GMT+5", from: :min,
full_name: "Etc/GMT+5", offset_std: 0, offset_utc: -300, until: :max},
year: 2015}}
# Without timezone offset
> date = "2015-06-24T04:50:34Z"
> Timex.parse(date, "{ISOz}")
{:ok,
%DateTime{calendar: :gregorian, day: 24, hour: 4, minute: 50, month: 6,
millisecond: 0, second: 34,
timezone: %TimezoneInfo{abbreviation: "UTC", from: :min,
full_name: "UTC", offset_std: 0, offset_utc: 0, until: :max}, year: 2015}}
Formatting DateTimes
Formatting a DateTime as an ISO 8601 string
> DateTime.local |> Timex.format("{ISO}")
{:ok, "2015-06-24T00:04:09.293-05:00"}
> DateTime.local |> Timex.format("{ISOz}")
{:ok, "2015-06-24T05:04:13.910Z"}