Elixir v1.3.3 Time View Source

A Time struct and functions.

The Time struct contains the fields hour, minute, second and microseconds. New times can be built with the new/4 function or using the ~T sigil:

iex> ~T[23:00:07.001]
~T[23:00:07.001]

Both new/4 and sigil return a struct where the time fields can be accessed directly:

iex> time = ~T[23:00:07.001]
iex> time.hour
23
iex> time.microsecond
{1000, 3}

Developers should avoid creating the Time struct directly and instead rely on the functions provided by this module as well as the ones in 3rd party calendar libraries.

Link to this section Summary

Functions

Converts an Erlang time tuple to a Time struct

Converts an Erlang time tuple to a Time struct

Parses the extended “Local time” format described by ISO8601:2004

Parses the extended “Local time” format described by ISO8601:2004

Converts a Time struct to an Erlang time tuple

Converts the given time to ISO8601

Converts the given time to a string

Link to this section Types

Link to this section Functions

Link to this function from_erl(arg, microsecond \\ {0, 0}) View Source
from_erl(:calendar.time, Calendar.microsecond) ::
  {:ok, Time.t} |
  {:error, atom}

Converts an Erlang time tuple to a Time struct.

Examples

iex> Time.from_erl({23, 30, 15}, {5000, 3})
{:ok, ~T[23:30:15.005]}
iex> Time.from_erl({24, 30, 15})
{:error, :invalid_time}
Link to this function from_erl!(tuple, microsecond \\ {0, 0}) View Source
from_erl!(:calendar.time, Calendar.microsecond) ::
  Time.t |
  no_return

Converts an Erlang time tuple to a Time struct.

Examples

iex> Time.from_erl!({23, 30, 15})
~T[23:30:15]
iex> Time.from_erl!({23, 30, 15}, {5000, 3})
~T[23:30:15.005]
iex> Time.from_erl!({24, 30, 15})
** (ArgumentError) cannot convert {24, 30, 15} to time, reason: :invalid_time
Link to this function from_iso8601(arg) View Source
from_iso8601(String.t) :: {:ok, Time.t} | {:error, atom}

Parses the extended “Local time” format described by ISO8601:2004.

Timezone offset may be included in the string but they will be simply discarded as such information is not included in times.

As specified in the standard, the separator “T” may be omitted if desired as there is no ambiguity within this function.

Time representations with reduced accuracy are not supported.

Examples

iex> Time.from_iso8601("23:50:07")
{:ok, ~T[23:50:07]}
iex> Time.from_iso8601("23:50:07Z")
{:ok, ~T[23:50:07]}
iex> Time.from_iso8601("T23:50:07Z")
{:ok, ~T[23:50:07]}

iex> Time.from_iso8601("23:50:07.0123456")
{:ok, ~T[23:50:07.012345]}
iex> Time.from_iso8601("23:50:07.123Z")
{:ok, ~T[23:50:07.123]}

iex> Time.from_iso8601("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> Time.from_iso8601("23:50:07A")
{:error, :invalid_format}
iex> Time.from_iso8601("23:50:07.")
{:error, :invalid_format}
iex> Time.from_iso8601("23:50:61")
{:error, :invalid_time}
Link to this function from_iso8601!(string) View Source
from_iso8601!(String.t) :: Time.t | no_return

Parses the extended “Local time” format described by ISO8601:2004.

Raises if the format is invalid.

Examples

iex> Time.from_iso8601!("23:50:07.123Z")
~T[23:50:07.123]
iex> Time.from_iso8601!("2015:01:23 23-50-07")
** (ArgumentError) cannot parse "2015:01:23 23-50-07" as time, reason: :invalid_format
Link to this function new(hour, minute, second, microsecond \\ {0, 0}) View Source

Builds a new time.

Expects all values to be integers. Returns {:ok, time} if each entry fits its appropriate range, returns {:error, reason} otherwise.

Note a time may have 60 seconds in case of leap seconds.

Examples

iex> Time.new(0, 0, 0, 0)
{:ok, ~T[00:00:00.000000]}
iex> Time.new(23, 59, 59, 999_999)
{:ok, ~T[23:59:59.999999]}
iex> Time.new(23, 59, 60, 999_999)
{:ok, ~T[23:59:60.999999]}

# Time with microseconds and their precision
iex> Time.new(23, 59, 60, {10_000, 2})
{:ok, ~T[23:59:60.01]}

iex> Time.new(24, 59, 59, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 60, 59, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 59, 61, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 59, 59, 1_000_000)
{:error, :invalid_time}
Link to this function to_erl(time) View Source
to_erl(Time.t) :: :calendar.time

Converts a Time struct to an Erlang time tuple.

WARNING: Loss of precision may occur, as Erlang time tuples only contain hours/minutes/seconds.

Examples

iex> Time.to_erl(~T[23:30:15.999])
{23, 30, 15}

Converts the given time to ISO8601.

Examples

iex> Time.to_iso8601(~T[23:00:13])
"23:00:13"

iex> Time.to_iso8601(~T[23:00:13.001])
"23:00:13.001"

Converts the given time to a string.

Examples

iex> Time.to_string(~T[23:00:00])
"23:00:00"
iex> Time.to_string(~T[23:00:00.001])
"23:00:00.001"
iex> Time.to_string(~T[23:00:00.123456])
"23:00:00.123456"