Calendar v0.17.2 Calendar.Time

The Time module provides a struct to represent a simple time without specifying a date, nor a time zone.

Summary

Functions

Returns true if provided time is AM in the twelve hour clock system. Otherwise false

Difference in seconds between two times

Create a Time struct using an erlang style tuple and optionally a microsecond second

Like from_erl, but will raise if the time is not valid

Create a Time struct from an integer being the number of the second of the day

Takes a time and returns a new time with the next second. If the provided time is 23:59:59 it returns a Time for 00:00:00

Returns true if provided time is AM in the twelve hour clock system. Otherwise false

Takes a time and returns a new time with the previous second. If the provided time is 00:00:00 it returns a Time for 23:59:59

The number of the second in the day with 00:00:00 being second 1 and 23:59:59 being number 86400

Takes a Time struct and returns an erlang style time tuple

Takes a Time struct and returns an Ecto style time four-tuple with microseconds

Converts a Time to the 12 hour format

Functions

am?(time)

Returns true if provided time is AM in the twelve hour clock system. Otherwise false.

Examples

iex> {8, 10, 23} |> Calendar.Time.am?
true
iex> {20, 10, 23} |> Calendar.Time.am?
false
diff(first_time_cont, second_time_cont)

Difference in seconds between two times.

Takes two Time structs: first_time and second_time. Subtracts second_time from first_time.

iex> from_erl!({0, 0, 30}) |> diff(from_erl!({0, 0, 10}))
20
iex> from_erl!({0, 0, 10}) |> diff(from_erl!({0, 0, 30}))
-20
from_erl(arg1, microsecond \\ {0, 0})

Create a Time struct using an erlang style tuple and optionally a microsecond second.

Microsecond can either be a tuple of microsecond and precision. Or an integer with just the microsecond.

iex> from_erl({20,14,15})
{:ok, %Time{microsecond: {0, 0}, hour: 20, minute: 14, second: 15}}

iex> from_erl({20,14,15}, 123456)
{:ok, %Time{microsecond: {123456, 6}, hour: 20, minute: 14, second: 15}}

iex> from_erl({20,14,15}, {123456, 6})
{:ok, %Time{microsecond: {123456, 6}, hour: 20, minute: 14, second: 15}}

iex> from_erl({24,14,15})
{:error, :invalid_time}

iex> from_erl({-1,0,0})
{:error, :invalid_time}

iex> from_erl({20,14,15}, {1_000_000, 6})
{:error, :invalid_time}
from_erl!(time, microsecond \\ {0, 0})

Like from_erl, but will raise if the time is not valid.

iex> from_erl!({20,14,15})
%Time{microsecond: {0, 0}, hour: 20, minute: 14, second: 15}

iex> from_erl!({20,14,15}, {123456, 6})
%Time{microsecond: {123456, 6}, hour: 20, minute: 14, second: 15}
from_second_in_day(second)

Create a Time struct from an integer being the number of the second of the day.

00:00:00 being second 0 and 23:59:59 being number 86399

Examples

iex> 0 |> from_second_in_day
%Time{hour: 0, minute: 0, second: 0, microsecond: {0, 0}}
iex> 43200 |> from_second_in_day
%Time{hour: 12, minute: 0, second: 0, microsecond: {0, 0}}
iex> 86399 |> from_second_in_day
%Time{hour: 23, minute: 59, second: 59, microsecond: {0, 0}}
next_second(time)

Takes a time and returns a new time with the next second. If the provided time is 23:59:59 it returns a Time for 00:00:00.

Examples

iex> {12, 0, 0} |> next_second
%Time{hour: 12, minute: 0, second: 1, microsecond: {0, 0}}
# Preserves microseconds
iex> {12, 0, 0, 123456} |> next_second
%Time{hour: 12, minute: 0, second: 1, microsecond: {123456, 6}}
# At the end of the day it goes to 00:00:00
iex> {23, 59, 59} |> next_second
%Time{hour: 0, minute: 0, second: 0, microsecond: {0, 0}}
iex> {23, 59, 59, 300000} |> next_second
%Time{hour: 0, minute: 0, second: 0, microsecond: {300000, 6}}
pm?(time)

Returns true if provided time is AM in the twelve hour clock system. Otherwise false.

Examples

iex> {8, 10, 23} |> Calendar.Time.pm?
false
iex> {20, 10, 23} |> Calendar.Time.pm?
true
prev_second(time)

Takes a time and returns a new time with the previous second. If the provided time is 00:00:00 it returns a Time for 23:59:59.

Examples

iex> {12, 0, 0} |> prev_second
%Time{hour: 11, minute: 59, second: 59, microsecond: {0, 0}}
# Preserves microseconds
iex> {12, 0, 0, 123456} |> prev_second
%Time{hour: 11, minute: 59, second: 59, microsecond: {123456, 6}}
# At the beginning of the day it goes to 23:59:59
iex> {0, 0, 0} |> prev_second
%Time{hour: 23, minute: 59, second: 59, microsecond: {0, 0}}
iex> {0, 0, 0, 200_000} |> prev_second
%Time{hour: 23, minute: 59, second: 59, microsecond: {200_000, 6}}
second_in_day(time)

The number of the second in the day with 00:00:00 being second 1 and 23:59:59 being number 86400

Examples

iex> {0, 0, 0} |> second_in_day
0
iex> {23, 59, 59} |> second_in_day
86399
to_erl(t)

Takes a Time struct and returns an erlang style time tuple.

Examples

iex> from_erl!({10, 20, 25}, {12345, 5}) |> to_erl
{10, 20, 25}
iex> {10, 20, 25} |> to_erl
{10, 20, 25}
to_micro_erl(t)

Takes a Time struct and returns an Ecto style time four-tuple with microseconds.

If the Time struct has its usec field set to nil, 0 will be used for usec.

Examples

iex> from_erl!({10, 20, 25}, 123456) |> to_micro_erl
{10, 20, 25, 123456}
# If `usec` is nil, 0 is used instead as the last element in the tuple
iex> {10, 20, 25} |> from_erl! |> to_micro_erl
{10, 20, 25, 0}
iex> {10, 20, 25} |> to_micro_erl
{10, 20, 25, 0}
twelve_hour_time(time)

Converts a Time to the 12 hour format

Returns a five element tuple with: {hours (1-12), minutes, seconds, microseconds, :am or :pm}

Examples

iex> {13, 10, 23} |> twelve_hour_time
{1, 10, 23, {0, 0}, :pm}
iex> {0, 10, 23, 888888} |> twelve_hour_time
{12, 10, 23, {888888, 6}, :am}