Calendar v1.0.0 Calendar.DateTime View Source
DateTime provides a struct which represents a certain time and date in a certain time zone.
The functions in this module can be used to create and transform DateTime structs.
Link to this section Summary
Functions
Takes a DateTime and an integer. Returns the date_time
advanced by the number
of seconds found in the seconds
argument.
Deprecated version of add/2
Deprecated version of add!/2
Takes a two DateTime
s and returns true if the first
one is greater than the second. Otherwise false. Greater than
means that it is later then the second datetime.
Takes a two DateTime
s and returns true if the first
one is less than the second. Otherwise false. Less than
means that it is earlier then the second datetime.
The difference between two DateTime structs. In seconds and microseconds.
Create new DateTime struct based on a date and a time and a timezone string.
Like from_date_and_time_and_zone
, but returns result untagged and
raises in case of an error or ambiguous datetime.
Takes an Erlang-style date-time tuple and additionally a timezone name. Returns a tuple with a tag and a DateTime struct.
Like from_erl/2 without "!", but returns the result directly without a tag. Will raise if date is ambiguous or invalid! Only use this if you are sure the date is valid. Otherwise use "from_erl" without the "!".
Like from_erl, but also takes an argument with the total UTC offset. (Total offset is standard offset + UTC offset)
Takes an erlang style 3 touple timestamp with the form: {megasecs, secs, microsecs}
Like from_erl_total_off/4
but takes a 7 element datetime tuple with
microseconds instead of a "normal" erlang style tuple.
Takes an NaiveDateTime and a time zone identifier and returns a DateTime
Takes a DateTime and returns an integer of gregorian seconds starting with year 0. This is done via the Erlang calendar module.
Takes a timezone name and returns a DateTime with the current time in that timezone. The result is returned in a tuple tagged with :ok
Takes a timezone name and returns a DateTime with the current time in that timezone. Timezone names must be in the TZ data format.
Like DateTime.now!("Etc/UTC")
Takes a two DateTime
s and returns true if the first
is at the same time as the second one.
Takes a DateTime and the name of a new timezone. Returns a DateTime with the equivalent time in the new timezone.
Like shift_zone without "!", but does not check that the time zone is valid and just returns a DateTime struct instead of a tuple with a tag.
Takes a DateTime
struct and an integer. Subtracts the number of seconds found in the
seconds
argument.
NOTE: subtract/2
ignores leap seconds. The
calculation is based on the (wrong) assumption that there are no leap seconds.
Takes a DateTime
struct and an integer. Returns a DateTime
struct in the past which is less
by the number of seconds found in the seconds
argument. NOTE: subtract!/2
ignores leap seconds. The
calculation is based on the (wrong) assumption that there are no leap seconds.
Takes a DateTime struct and returns a Date struct representing the date part of the provided DateTime.
Returns a tuple with a Date struct and a Time struct.
Takes a DateTime struct and returns an erlang style datetime tuple.
Takes a DateTime struct and returns an Ecto style datetime tuple. This is like an erlang style tuple, but with microseconds added as an additional element in the time part of the tuple.
Takes a DateTime and returns a NaiveDateTime
Takes a DateTime struct and returns a Time struct representing the time part of the provided DateTime.
Link to this section Functions
add(dt, seconds) View Source
Takes a DateTime
struct and an integer. Returns a DateTime
struct in the future which is greater
by the number of seconds found in the seconds
argument. NOTE: add/2
ignores leap seconds. The
calculation is based on the (wrong) assumption that there are no leap seconds.
Examples
# Add 2 seconds
iex> from_erl!({{2014,10,2},{0,29,10}}, "America/New_York", 123456) |> add(2)
{:ok, %DateTime{zone_abbr: "EDT", day: 2, hour: 0, minute: 29, month: 10,
second: 12, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6},
utc_offset: -18000, year: 2014}}
# Add 86400 seconds (one day)
iex> from_erl!({{2014,10,2},{0,29,10}}, "America/New_York", 123456) |> add(86400)
{:ok, %DateTime{zone_abbr: "EDT", day: 3, hour: 0, minute: 29, month: 10,
second: 10, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6},
utc_offset: -18000, year: 2014}}
# Add 10 seconds just before DST "spring forward" so we go from 1:59:59 to 3:00:09
iex> from_erl!({{2015,3,8},{1,59,59}}, "America/New_York", 123456) |> add(10)
{:ok, %DateTime{zone_abbr: "EDT", day: 8, hour: 3, minute: 0, month: 3,
second: 9, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6},
utc_offset: -18000, year: 2015}}
# If you add a negative number of seconds, the resulting datetime will effectively
# be subtracted.
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", 123456) |> add(-200)
{:ok, %DateTime{zone_abbr: "EDT", day: 1, hour: 23, minute: 56, month: 10, second: 40, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000, year: 2014}}
add!(dt, seconds) View Source
Takes a DateTime and an integer. Returns the date_time
advanced by the number
of seconds found in the seconds
argument.
If seconds
is negative, the time is moved back.
NOTE: this ignores leap seconds. The calculation is based on the (wrong) assumption that there are no leap seconds.
Examples
# Add 2 seconds
iex> from_erl!({{2014,10,2},{0,29,10}}, "America/New_York", {123456, 6}) |> add!(2)
%DateTime{zone_abbr: "EDT", day: 2, hour: 0, minute: 29, month: 10, second: 12,
std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000,
year: 2014}
# Add 86400 seconds (one day)
iex> from_erl!({{2014,10,2},{0,29,10}}, "America/New_York", {123456, 6}) |> add!(86400)
%DateTime{zone_abbr: "EDT", day: 3, hour: 0, minute: 29, month: 10, second: 10,
std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000,
year: 2014}
# Add 10 seconds just before DST "spring forward" so we go from 1:59:59 to 3:00:09
iex> from_erl!({{2015,3,8},{1,59,59}}, "America/New_York", {123456, 6}) |> add!(10)
%DateTime{zone_abbr: "EDT", day: 8, hour: 3, minute: 0, month: 3, second: 9,
std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000,
year: 2015}
# When add a negative integer, the seconds will effectively be subtracted and
# the result will be a datetime earlier than the the first argument
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", {123456, 6}) |> add!(-200)
%DateTime{zone_abbr: "EDT", day: 1, hour: 23, minute: 56, month: 10, second: 40, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000, year: 2014}
advance(date_time, seconds) View Source
Deprecated version of add/2
advance!(date_time, seconds) View Source
Deprecated version of add!/2
after?(dt1, dt2) View Source
Takes a two DateTime
s and returns true if the first
one is greater than the second. Otherwise false. Greater than
means that it is later then the second datetime.
Examples
# The wall times of the two times are the same, but the one in Los Angeles
# happens after the one in UTC because Los Angeles is behind UTC
iex> from_erl!({{2014,1,1}, {11,11,11}}, "America/Los_Angeles") |> after?(from_erl!({{2014, 1, 1}, {11, 11, 11}}, "Etc/UTC"))
true
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> after?(from_erl!({{1999, 1, 1}, {11, 11, 11}}, "Etc/UTC"))
true
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> after?(from_erl!({{2020, 1, 1}, {11, 11, 11}}, "Etc/UTC"))
false
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> after?(from_erl!({{2014, 1, 1}, {10, 10, 10}}, "Etc/UTC"))
false
before?(dt1, dt2) View Source
Takes a two DateTime
s and returns true if the first
one is less than the second. Otherwise false. Less than
means that it is earlier then the second datetime.
Examples
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> before?(from_erl!({{1999, 1, 1}, {11, 11, 11}}, "Etc/UTC"))
false
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> before?(from_erl!({{2020, 1, 1}, {11, 11, 11}}, "Etc/UTC"))
true
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> before?(from_erl!({{2014, 1, 1}, {10, 10, 10}}, "Etc/UTC"))
false
diff(first_dt, second_dt) View Source
The difference between two DateTime structs. In seconds and microseconds.
Leap seconds are ignored.
Returns tuple with {:ok, seconds, microseconds, :before or :after or :same_time}
If the first argument is later (e.g. greater) the second, the result will be positive.
In case of a negative result the second element (seconds) will be negative. This is always the case if both of the arguments have the microseconds as 0. But if the difference is less than a second and the result is negative, then the microseconds will be negative.
Examples
# March 30th 2014 02:00:00 in Central Europe the time changed from
# winter time to summer time. This means that clocks were set forward
# and an hour skipped. So between 01:00 and 4:00 there were 2 hours
# not 3. Two hours is 7200 seconds.
iex> diff(from_erl!({{2014,3,30},{4,0,0}}, "Europe/Stockholm"), from_erl!({{2014,3,30},{1,0,0}}, "Europe/Stockholm"))
{:ok, 7200, 0, :after}
# The first DateTime is 40 seconds after the second DateTime
iex> diff(from_erl!({{2014,10,2},{0,29,50}}, "Etc/UTC"), from_erl!({{2014,10,2},{0,29,10}}, "Etc/UTC"))
{:ok, 40, 0, :after}
# The first DateTime is 40 seconds before the second DateTime
iex> diff(from_erl!({{2014,10,2},{0,29,10}}, "Etc/UTC"), from_erl!({{2014,10,2},{0,29,50}}, "Etc/UTC"))
{:ok, -40, 0, :before}
# The first DateTime is 30 microseconds after the second DateTime
iex> diff(from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {31, 5}), from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {1, 6}))
{:ok, 0, 30, :after}
# The first DateTime is 2 microseconds after the second DateTime
iex> diff(from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {0, 0}), from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {2, 6}))
{:ok, 0, -2, :before}
# The first DateTime is 9.999998 seconds after the second DateTime
iex> diff(from_erl!({{2014,10,2},{0,29,10}}, "Etc/UTC", {0, 0}), from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {2,6}))
{:ok, 9, 999998, :after}
# The first DateTime is 9.999998 seconds before the second DateTime
iex> diff(from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {2, 6}), from_erl!({{2014,10,2},{0,29,10}}, "Etc/UTC", {0, 0}))
{:ok, -9, 999998, :before}
iex> diff(from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {0, 0}), from_erl!({{2014,10,2},{0,29,10}}, "Etc/UTC", {2, 6}))
{:ok, -10, 2, :before}
iex> diff(from_erl!({{2014,10,2},{0,29,1}}, "Etc/UTC", {100, 6}), from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {200, 5}))
{:ok, 0, 999900, :after}
iex> diff(from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {10, 5}), from_erl!({{2014,10,2},{0,29,0}}, "Etc/UTC", {999999, 6}))
{:ok, 0, -999989, :before}
# 0:29:10.999999 and 0:29:11 should result in -1 microseconds
iex> diff(from_erl!({{2014,10,2},{0,29,10}}, "Etc/UTC", {999999, 6}), from_erl!({{2014,10,2},{0,29,11}}, "Etc/UTC"))
{:ok, 0, -1, :before}
iex> diff(from_erl!({{2014,10,2},{0,29,11}}, "Etc/UTC"), from_erl!({{2014,10,2},{0,29,10}}, "Etc/UTC", {999999, 6}))
{:ok, 0, 1, :after}
from_date_and_time_and_zone(date_container, time_container, timezone) View Source
Create new DateTime struct based on a date and a time and a timezone string.
Examples
iex> from_date_and_time_and_zone({2016, 1, 8}, {14, 10, 55}, "Etc/UTC")
{:ok, %DateTime{day: 8, microsecond: {0, 0}, hour: 14, minute: 10, month: 1, second: 55, year: 2016, zone_abbr: "UTC", time_zone: "Etc/UTC", utc_offset: 0, std_offset: 0}}
from_date_and_time_and_zone!(date_container, time_container, timezone) View Source
Like from_date_and_time_and_zone
, but returns result untagged and
raises in case of an error or ambiguous datetime.
Examples
iex> from_date_and_time_and_zone!({2016, 1, 8}, {14, 10, 55}, "Etc/UTC")
%DateTime{day: 8, microsecond: {0, 0}, hour: 14, minute: 10, month: 1, second: 55, year: 2016, zone_abbr: "UTC", time_zone: "Etc/UTC", utc_offset: 0, std_offset: 0}
from_erl(date_time, timezone, microsecond \\ {0, 0}) View Source
Takes an Erlang-style date-time tuple and additionally a timezone name. Returns a tuple with a tag and a DateTime struct.
The tag can be :ok, :ambiguous or :error. :ok is for an unambigous time. :ambiguous is for a time that could have different UTC offsets and/or standard offsets. Usually when switching from summer to winter time.
An erlang style date-time tuple has the following format: {{year, month, day}, {hour, minute, second}}
Examples
Normal, non-ambigous time
iex> from_erl({{2014, 9, 26}, {17, 10, 20}}, "America/Montevideo")
{:ok, %DateTime{day: 26, hour: 17, minute: 10, month: 9, second: 20,
year: 2014, time_zone: "America/Montevideo",
zone_abbr: "-03",
utc_offset: -10800, std_offset: 0, microsecond: {0, 0}} }
Switching from summer to wintertime in the fall means an ambigous time.
iex> from_erl({{2014, 3, 9}, {1, 1, 1}}, "America/Montevideo")
{:ambiguous, %Calendar.AmbiguousDateTime{possible_date_times:
[%DateTime{day: 9, hour: 1, minute: 1, month: 3, second: 1,
year: 2014, time_zone: "America/Montevideo",
zone_abbr: "-02", utc_offset: -10800, std_offset: 3600},
%DateTime{day: 9, hour: 1, minute: 1, month: 3, second: 1,
year: 2014, time_zone: "America/Montevideo",
zone_abbr: "-03", utc_offset: -10800, std_offset: 0},
]}
}
iex> from_erl({{2014, 9, 26}, {17, 10, 20}}, "Non-existing timezone")
{:error, :timezone_not_found}
The time between 2:00 and 3:00 in the following example does not exist because of the one hour gap caused by switching to DST.
iex> from_erl({{2014, 3, 30}, {2, 20, 02}}, "Europe/Copenhagen")
{:error, :invalid_datetime_for_timezone}
Time with fractional seconds. This represents the time 17:10:20.987654321
iex> from_erl({{2014, 9, 26}, {17, 10, 20}}, "America/Montevideo", {987654, 6})
{:ok, %DateTime{day: 26, hour: 17, minute: 10, month: 9, second: 20,
year: 2014, time_zone: "America/Montevideo",
zone_abbr: "-03",
utc_offset: -10800, std_offset: 0, microsecond: {987654, 6}} }
from_erl!(date_time, time_zone, microsecond \\ {0, 0}) View Source
Like from_erl/2 without "!", but returns the result directly without a tag. Will raise if date is ambiguous or invalid! Only use this if you are sure the date is valid. Otherwise use "from_erl" without the "!".
Example:
iex> from_erl!({{2014, 9, 26}, {17, 10, 20}}, "America/Montevideo")
%DateTime{day: 26, hour: 17, minute: 10, month: 9, second: 20, year: 2014, time_zone: "America/Montevideo", zone_abbr: "-03", utc_offset: -10800, std_offset: 0}
from_erl_total_off(erl_dt, timezone, total_off, microsecond \\ {0, 0}) View Source
Like from_erl, but also takes an argument with the total UTC offset. (Total offset is standard offset + UTC offset)
The result will be the same as from_erl, except if the datetime is ambiguous.
When the datetime is ambiguous (for instance during change from DST to
non-DST) the total_offset argument is use to try to disambiguise the result.
If successful the matching result is returned tagged with :ok
. If the
total_offset
argument does not match either, an error will be returned.
Examples:
iex> from_erl_total_off({{2014, 9, 26}, {17, 10, 20}}, "America/Montevideo", -10800, 2)
{:ok, %DateTime{day: 26, hour: 17, minute: 10, month: 9, second: 20,
year: 2014, time_zone: "America/Montevideo",
zone_abbr: "-03",
utc_offset: -10800, std_offset: 0, microsecond: {2, 6}} }
iex> from_erl_total_off({{2014, 3, 9}, {1, 1, 1}}, "America/Montevideo", -7200, 2)
{:ok, %DateTime{day: 9, hour: 1, minute: 1, month: 3, second: 1,
year: 2014, time_zone: "America/Montevideo", microsecond: {2, 6},
zone_abbr: "-02", utc_offset: -10800, std_offset: 3600}
}
from_erlang_timestamp(erlang_timestamp) View Source
Takes an erlang style 3 touple timestamp with the form: {megasecs, secs, microsecs}
This is the form returned by the Erlang function :erlang.timestamp()
Examples
iex> from_erlang_timestamp({1453, 854322, 799236})
%DateTime{zone_abbr: "UTC", day: 27, hour: 0, minute: 25, month: 1, second: 22, std_offset: 0,
time_zone: "Etc/UTC", microsecond: {799236, 6}, utc_offset: 0, year: 2016}
from_micro_erl_total_off(arg, timezone, total_off) View Source
Like from_erl_total_off/4
but takes a 7 element datetime tuple with
microseconds instead of a "normal" erlang style tuple.
Examples:
iex> from_micro_erl_total_off({{2014, 3, 9}, {1, 1, 1, 2}}, "America/Montevideo", -7200)
{:ok, %DateTime{day: 9, hour: 1, minute: 1, month: 3, second: 1,
year: 2014, time_zone: "America/Montevideo", microsecond: {2, 6},
zone_abbr: "-02", utc_offset: -10800, std_offset: 3600}
}
from_naive(ndt, timezone) View Source
Takes an NaiveDateTime and a time zone identifier and returns a DateTime
iex> Calendar.NaiveDateTime.from_erl!({{2014,10,15},{2,37,22}}) |> from_naive("Etc/UTC")
{:ok, %DateTime{zone_abbr: "UTC", day: 15, microsecond: {0, 0}, hour: 2, minute: 37, month: 10, second: 22, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0, year: 2014}}
iex> Calendar.NaiveDateTime.from_erl!({{2014,10,15},{2,37,22}}, {13, 6}) |> from_naive("Etc/UTC")
{:ok, %DateTime{zone_abbr: "UTC", day: 15, microsecond: {13, 6}, hour: 2, minute: 37, month: 10, second: 22, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0, year: 2014}}
gregorian_seconds(date_time) View Source
Takes a DateTime and returns an integer of gregorian seconds starting with year 0. This is done via the Erlang calendar module.
Examples
iex> from_erl!({{2014,9,26},{17,10,20}}, "UTC") |> gregorian_seconds
63578970620
gregorian_seconds_and_microsecond(date_time) View Source
now(timezone)
View Source
now(String.t()) :: {:ok, DateTime.t()} | :error
now(String.t()) :: {:ok, DateTime.t()} | :error
Takes a timezone name and returns a DateTime with the current time in that timezone. The result is returned in a tuple tagged with :ok
iex > Calendar.DateTime.now! "Europe/Copenhagen"
{:ok, %DateTime{zone_abbr: "CEST", day: 15, hour: 4,
minute: 41, month: 10, second: 1, std_offset: 3600, time_zone: "Europe/Copenhagen",
utc_offset: 3600, year: 2014}}
iex> Calendar.DateTime.now "Invalid/Narnia"
:error
now!(timezone) View Source
Takes a timezone name and returns a DateTime with the current time in that timezone. Timezone names must be in the TZ data format.
Raises in case of an incorrect time zone name.
Examples
iex > Calendar.DateTime.now! "UTC"
%DateTime{zone_abbr: "UTC", day: 15, hour: 2,
minute: 39, month: 10, second: 53, std_offset: 0, time_zone: "UTC", utc_offset: 0,
year: 2014}
iex > Calendar.DateTime.now! "Europe/Copenhagen"
%DateTime{zone_abbr: "CEST", day: 15, hour: 4,
minute: 41, month: 10, second: 1, std_offset: 3600, time_zone: "Europe/Copenhagen",
utc_offset: 3600, year: 2014}
now_utc() View Source
Like DateTime.now!("Etc/UTC")
same_time?(dt1, dt2) View Source
Takes a two DateTime
s and returns true if the first
is at the same time as the second one.
Examples
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> same_time?(from_erl!({{2014, 1, 1}, {10, 10, 10}}, "Etc/UTC"))
true
# 10:00 in London is the same time as 11:00 in Copenhagen
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Europe/London") |> same_time?(from_erl!({{2014, 1, 1}, {11, 10, 10}}, "Europe/Copenhagen"))
true
iex> from_erl!({{2014,1,1}, {10,10,10}}, "America/Godthab") |> same_time?(from_erl!({{2014, 1, 1}, {10, 10, 10}}, "Etc/UTC"))
false
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Etc/UTC") |> same_time?(from_erl!({{2020, 1, 1}, {11, 11, 11}}, "Etc/UTC"))
false
iex> from_erl!({{2014,1,1}, {10,10,10}}, "Europe/London") |> same_time?(from_erl!({{2014, 1, 1}, {10, 10, 10}}, "Etc/UTC"))
true
shift_zone(date_time, timezone) View Source
Takes a DateTime and the name of a new timezone. Returns a DateTime with the equivalent time in the new timezone.
Examples
iex> from_erl!({{2014,10,2},{0,29,10}}, "America/New_York",123456) |> shift_zone("Europe/Copenhagen")
{:ok, %DateTime{zone_abbr: "CEST", day: 2, hour: 6, minute: 29, month: 10, second: 10, time_zone: "Europe/Copenhagen", utc_offset: 3600, std_offset: 3600, year: 2014, microsecond: {123456, 6}}}
iex> {:ok, nyc} = from_erl {{2014,10,2},{0,29,10}},"America/New_York"; shift_zone(nyc, "Invalid timezone")
{:invalid_time_zone, nil}
shift_zone!(date_time, timezone) View Source
Like shift_zone without "!", but does not check that the time zone is valid and just returns a DateTime struct instead of a tuple with a tag.
Example
iex> from_erl!({{2014,10,2},{0,29,10}},"America/New_York") |> shift_zone!("Europe/Copenhagen")
%DateTime{zone_abbr: "CEST", day: 2, hour: 6, minute: 29, month: 10, second: 10,
time_zone: "Europe/Copenhagen", utc_offset: 3600, std_offset: 3600, year: 2014}
subtract(dt, seconds) View Source
Takes a DateTime
struct and an integer. Subtracts the number of seconds found in the
seconds
argument.
NOTE: subtract/2
ignores leap seconds. The
calculation is based on the (wrong) assumption that there are no leap seconds.
See TimeZoneData.leap_seconds/0
function for a list of past leap seconds.
Examples
# Go back 62 seconds
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", 123456) |> subtract(62)
{:ok, %DateTime{zone_abbr: "EDT", day: 1, hour: 23, minute: 58, month: 10,
second: 58, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000,
year: 2014}}
# Go back too far so that year would be before 0
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", 123456) |> subtract(999999999999)
{:error, :function_clause_error}
# Using a negative amount of seconds with the subtract/2 means effectively adding the absolute amount of seconds
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", 123456) |> subtract!(-200)
%DateTime{zone_abbr: "EDT", day: 2, hour: 0, minute: 3, month: 10, second: 20, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000, year: 2014}
subtract!(dt, seconds) View Source
Takes a DateTime
struct and an integer. Returns a DateTime
struct in the past which is less
by the number of seconds found in the seconds
argument. NOTE: subtract!/2
ignores leap seconds. The
calculation is based on the (wrong) assumption that there are no leap seconds.
See Calendar.TimeZoneData.leap_seconds/0
function for a list of past leap seconds.
Examples
# Go back 62 seconds
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", {123456, 6}) |> subtract!(62)
%DateTime{zone_abbr: "EDT", day: 1, hour: 23, minute: 58, month: 10, second: 58,
std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000,
year: 2014}
# Go back too far so that year would be before 0
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", {123456, 6}) |> subtract!(999999999999)
** (MatchError) no match of right hand side value: {:error, :function_clause_error}
# Using a negative amount of seconds with the subtract/2 means effectively adding the absolute amount of seconds
iex> from_erl!({{2014,10,2},{0,0,0}}, "America/New_York", {123456, 6}) |> subtract!(-200)
%DateTime{zone_abbr: "EDT", day: 2, hour: 0, minute: 3, month: 10, second: 20, std_offset: 3600, time_zone: "America/New_York", microsecond: {123456, 6}, utc_offset: -18000, year: 2014}
to_date(dt) View Source
Takes a DateTime struct and returns a Date struct representing the date part of the provided DateTime.
iex> from_erl!({{2014,10,15},{2,37,22}}, "UTC") |> Calendar.DateTime.to_date
%Date{day: 15, month: 10, year: 2014}
to_date_and_time(dt) View Source
Returns a tuple with a Date struct and a Time struct.
iex> from_erl!({{2014,10,15},{2,37,22}}, "UTC") |> Calendar.DateTime.to_date_and_time
{%Date{day: 15, month: 10, year: 2014}, %Time{microsecond: {0, 0}, hour: 2, minute: 37, second: 22}}
to_erl(date_time) View Source
Takes a DateTime struct and returns an erlang style datetime tuple.
Examples
iex> from_erl!({{2014,10,15},{2,37,22}}, "Etc/UTC") |> Calendar.DateTime.to_erl
{{2014, 10, 15}, {2, 37, 22}}
to_micro_erl(date_time) View Source
Takes a DateTime struct and returns an Ecto style datetime tuple. This is like an erlang style tuple, but with microseconds added as an additional element in the time part of the tuple.
Examples
iex> from_erl!({{2014,10,15},{2,37,22}}, "Etc/UTC", {999999, 6}) |> Calendar.DateTime.to_micro_erl
{{2014, 10, 15}, {2, 37, 22, 999999}}
iex> from_erl!({{2014,10,15},{2,37,22}}, "Etc/UTC", {0, 0}) |> Calendar.DateTime.to_micro_erl
{{2014, 10, 15}, {2, 37, 22, 0}}
to_naive(dt) View Source
Takes a DateTime and returns a NaiveDateTime
iex> Calendar.DateTime.from_erl!({{2014,10,15},{2,37,22}}, "UTC", 55) |> to_naive
%NaiveDateTime{day: 15, microsecond: {55, 6}, hour: 2, minute: 37, month: 10, second: 22, year: 2014}
to_time(dt) View Source
Takes a DateTime struct and returns a Time struct representing the time part of the provided DateTime.
iex> from_erl!({{2014,10,15},{2,37,22}}, "UTC") |> Calendar.DateTime.to_time
%Time{microsecond: {0, 0}, hour: 2, minute: 37, second: 22}