Calendar v0.17.3 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 NaiveDateTimes 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 NaiveDateTimes 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 NaiveDateTimes 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

add(ndt, seconds)

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}}
add!(ndt, seconds)

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}
advance(ndt, seconds)

Deprecated version of add/2

advance!(ndt, seconds)

Deprecated version of add!/2

after?(ndt1, ndt2)

Takes a two NaiveDateTimes 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
before?(ndt1, ndt2)

Takes a two NaiveDateTimes 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
diff(first_dt, second_dt)

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}
from_date_and_time(date_container, time_container)

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}}
from_date_and_time!(date_container, time_container)

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}
from_erl(dt, microsecond \\ {0, 0})

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}
from_erl!(erl_date_time, microsecond \\ {0, 0})

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
gregorian_seconds(ndt)

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
same_time?(ndt1, ndt2)

Takes a two NaiveDateTimes 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
subtract(ndt, seconds)
subtract!(ndt, seconds)
to_date(ndt)

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}
to_date_time(ndt, timezone)

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}}
to_date_time_utc(ndt)

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}
to_erl(ndt)

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}}
to_micro_erl(ndt)

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}}
to_time(ndt)

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}
with_offset_to_datetime_utc(ndt, total_utc_offset)

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}