Calendar v0.17.1 Calendar.NaiveDateTime
NaiveDateTime can represents a “naive time”. That is a point in time without a specified time zone.
Summary
Functions
Takes a NaiveDateTime and an integer.
Returns the naive_date_time
advanced by the number
of seconds found in the seconds
argument
Like add
without exclamation points.
Instead of returning a tuple with :ok and the result,
the result is returned untagged. Will raise an error in case
no correct result can be found based on the arguments
Deprecated version of add/2
Deprecated version of add!/2
Takes a two NaiveDateTime
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 NaiveDateTime
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 naive datetimes. In seconds and microseconds
Create new NaiveDateTime struct based on a date and a time
Like from_date_and_time/2
but returns the result untagged.
Raises in case of an error
Takes an Erlang-style date-time tuple. If the datetime is valid it returns a tuple with a tag and a naive DateTime. Naive in this context means that it does not have any timezone data
Like from_erl/1 without “!”, but returns the result directly without a tag. Will raise if date is invalid. Only use this if you are sure the date is valid
Takes a NaiveDateTime and returns an integer of gregorian seconds starting with year 0. This is done via the Erlang calendar module
Takes a two NaiveDateTime
s and returns true if the first
is equal to the second one
Takes a NaiveDateTime struct and returns a Date struct representing the date part of the provided NaiveDateTime
For turning NaiveDateTime structs to into a DateTime
Promote to DateTime with UTC time zone. Should only be used if you are sure that the provided argument is in UTC
Takes a NaiveDateTime struct and returns an erlang style datetime tuple
Takes a NaiveDateTime 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 NaiveDateTime struct and returns a Time struct representing the time part of the provided NaiveDateTime
If you have a naive datetime and you know the offset, promote it to a UTC DateTime
Functions
Takes a NaiveDateTime and an integer.
Returns the naive_date_time
advanced by the number
of seconds found in the seconds
argument.
If seconds
is negative, the time is moved back.
Examples
# Advance 2 seconds
iex> from_erl!({{2014,10,2},{0,29,10}}, 123456) |> add(2)
{:ok, %NaiveDateTime{day: 2, hour: 0, minute: 29, month: 10,
second: 12, microsecond: {123456, 6},
year: 2014}}
Like add
without exclamation points.
Instead of returning a tuple with :ok and the result,
the result is returned untagged. Will raise an error in case
no correct result can be found based on the arguments.
Examples
# Advance 2 seconds
iex> from_erl!({{2014,10,2},{0,29,10}}, 123456) |> add!(2)
%NaiveDateTime{day: 2, hour: 0, minute: 29, month: 10,
second: 12, microsecond: {123456, 6},
year: 2014}
Deprecated version of add/2
Deprecated version of add!/2
Takes a two NaiveDateTime
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
iex> {{2014,1,1}, {10,10,10}} |> after?({{1999, 1, 1}, {11, 11, 11}})
true
iex> {{2014,1,1}, {10,10,10}} |> after?({{2020, 1, 1}, {11, 11, 11}})
false
iex> {{2014,1,1}, {10,10,10}} |> after?({{2014, 1, 1}, {10, 10, 10}})
false
Takes a two NaiveDateTime
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> {{2014,1,1}, {10,10,10}} |> before?({{1999, 1, 1}, {11, 11, 11}})
false
iex> {{2014,1,1}, {10,10,10}} |> before?({{2020, 1, 1}, {11, 11, 11}})
true
iex> {{2014,1,1}, {10,10,10}} |> before?({{2014, 1, 1}, {10, 10, 10}})
false
The difference between two naive datetimes. In seconds and microseconds.
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 nil or 0. But if the difference is less than a second and the result is negative, then the microseconds will be negative.
Examples
# The first NaiveDateTime is 40 seconds after the second NaiveDateTime
iex> diff({{2014,10,2},{0,29,50}}, {{2014,10,2},{0,29,10}})
{:ok, 40, 0, :after}
# The first NaiveDateTime is 40 seconds before the second NaiveDateTime
iex> diff({{2014,10,2},{0,29,10}}, {{2014,10,2},{0,29,50}})
{:ok, -40, 0, :before}
iex> diff(from_erl!({{2014,10,2},{0,29,10}},{999999, 6}), from_erl!({{2014,10,2},{0,29,50}}))
{:ok, -39, 1, :before}
iex> diff(from_erl!({{2014,10,2},{0,29,10}},{999999, 6}), from_erl!({{2014,10,2},{0,29,11}}))
{:ok, 0, -1, :before}
iex> diff(from_erl!({{2014,10,2},{0,29,11}}), from_erl!({{2014,10,2},{0,29,10}},{999999, 6}))
{:ok, 0, 1, :after}
iex> diff(from_erl!({{2014,10,2},{0,29,11}}), from_erl!({{2014,10,2},{0,29,11}}))
{:ok, 0, 0, :same_time}
Create new NaiveDateTime struct based on a date and a time.
Examples
iex> from_date_and_time({2016, 1, 8}, {14, 10, 55})
{:ok, %NaiveDateTime{day: 8, microsecond: {0, 0}, hour: 14, minute: 10, month: 1, second: 55, year: 2016}}
iex> from_date_and_time(Calendar.Date.Parse.iso8601!("2016-01-08"), {14, 10, 55})
{:ok, %NaiveDateTime{day: 8, microsecond: {0, 0}, hour: 14, minute: 10, month: 1, second: 55, year: 2016}}
Like from_date_and_time/2
but returns the result untagged.
Raises in case of an error.
Example
iex> from_date_and_time!({2016, 1, 8}, {14, 10, 55})
%NaiveDateTime{day: 8, microsecond: {0, 0}, hour: 14, minute: 10, month: 1, second: 55, year: 2016}
Takes an Erlang-style date-time tuple. If the datetime is valid it returns a tuple with a tag and a naive DateTime. Naive in this context means that it does not have any timezone data.
Examples
iex>from_erl({{2014, 9, 26}, {17, 10, 20}})
{:ok, %NaiveDateTime{day: 26, hour: 17, minute: 10, month: 9, second: 20, year: 2014} }
iex>from_erl({{2014, 9, 26}, {17, 10, 20}}, 321321)
{:ok, %NaiveDateTime{day: 26, hour: 17, minute: 10, month: 9, second: 20, year: 2014, microsecond: {321321, 6}} }
# Invalid date
iex>from_erl({{2014, 99, 99}, {17, 10, 20}})
{:error, :invalid_datetime}
# Invalid time
iex>from_erl({{2014, 9, 26}, {17, 70, 20}})
{:error, :invalid_datetime}
Like from_erl/1 without “!”, but returns the result directly without a tag. Will raise if date is invalid. Only use this if you are sure the date is valid.
Examples
iex> from_erl!({{2014, 9, 26}, {17, 10, 20}})
%NaiveDateTime{day: 26, hour: 17, minute: 10, month: 9, second: 20, year: 2014}
iex from_erl!({{2014, 99, 99}, {17, 10, 20}})
# this will throw a MatchError
Takes a NaiveDateTime 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}}) |> gregorian_seconds
63578970620
Takes a two NaiveDateTime
s and returns true if the first
is equal to the second one.
In this context equal means that they happen at the same time.
Examples
iex> {{2014,1,1}, {10,10,10}} |> same_time?({{1999, 1, 1}, {11, 11, 11}})
false
iex> {{2014,1,1}, {10,10,10}} |> same_time?({{2020, 1, 1}, {11, 11, 11}})
false
iex> {{2014,1,1}, {10,10,10}} |> same_time?({{2014, 1, 1}, {10, 10, 10}})
true
Takes a NaiveDateTime struct and returns a Date struct representing the date part of the provided NaiveDateTime.
iex> from_erl!({{2014,10,15},{2,37,22}}) |> Calendar.NaiveDateTime.to_date
%Date{day: 15, month: 10, year: 2014}
For turning NaiveDateTime structs to into a DateTime.
Takes a NaiveDateTime and a timezone name. If timezone is valid, returns a tuple with an :ok and DateTime.
iex> from_erl!({{2014,10,15},{2,37,22}}) |> Calendar.NaiveDateTime.to_date_time("UTC")
{:ok, %DateTime{zone_abbr: "UTC", day: 15, microsecond: {0, 0}, hour: 2, minute: 37, month: 10, second: 22, std_offset: 0, time_zone: "UTC", utc_offset: 0, year: 2014}}
Promote to DateTime with UTC time zone. Should only be used if you are sure that the provided argument is in UTC.
Takes a NaiveDateTime. Returns a DateTime.
iex> from_erl!({{2014,10,15},{2,37,22}}) |> Calendar.NaiveDateTime.to_date_time_utc
%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}
Takes a NaiveDateTime struct and returns an erlang style datetime tuple.
Examples
iex> from_erl!({{2014, 10, 15}, {2, 37, 22}}) |> to_erl
{{2014, 10, 15}, {2, 37, 22}}
Takes a NaiveDateTime 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.
If the datetime has its microsecond field set to nil, 0 will be used for microsecond.
Examples
iex> from_erl!({{2014,10,15},{2,37,22}}, {999999, 6}) |> Calendar.NaiveDateTime.to_micro_erl
{{2014, 10, 15}, {2, 37, 22, 999999}}
iex> from_erl!({{2014,10,15},{2,37,22}}, {0, 0}) |> Calendar.NaiveDateTime.to_micro_erl
{{2014, 10, 15}, {2, 37, 22, 0}}
Takes a NaiveDateTime struct and returns a Time struct representing the time part of the provided NaiveDateTime.
iex> from_erl!({{2014,10,15},{2,37,22}}) |> Calendar.NaiveDateTime.to_time
%Time{microsecond: {0, 0}, hour: 2, minute: 37, second: 22}
If you have a naive datetime and you know the offset, promote it to a UTC DateTime.
Examples
# A naive datetime at 2:37:22 with a 3600 second offset will return
# a UTC DateTime with the same date, but at 1:37:22
iex> with_offset_to_datetime_utc {{2014,10,15},{2,37,22}}, 3600
{:ok, %DateTime{zone_abbr: "UTC", day: 15, microsecond: {0, 0}, hour: 1, minute: 37, month: 10, second: 22, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0, year: 2014} }
iex> with_offset_to_datetime_utc{{2014,10,15},{2,37,22}}, 999_999_999_999_999_999_999_999_999
{:error, nil}