Elixir v1.4.4 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}The functions on this module work with the Time struct as well
as any struct that contains the same fields as the Time struct,
such as NaiveDateTime and DateTime. Such functions expect
Calendar.time in their typespecs (instead of t).
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
Compares two Time structs
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 ISO 8601:2004
Parses the extended “Local time” format described by ISO 8601:2004
Builds a new time
Converts a Time struct to an Erlang time tuple
Converts the given time to ISO 8601:2004
Converts the given time to a string
Returns the current time in UTC
Link to this section Types
t() :: %Time{hour: Calendar.hour, microsecond: Calendar.microsecond, minute: Calendar.minute, second: Calendar.second}
Link to this section Functions
compare(Calendar.time, Calendar.time) :: :lt | :eq | :gt
Compares two Time structs.
Returns :gt if first time is later than the second
and :lt for vice versa. If the two times are equal
:eq is returned
Examples
iex> Time.compare(~T[16:04:16], ~T[16:04:28])
:lt
iex> Time.compare(~T[16:04:16.01], ~T[16:04:16.001])
:gtThis function can also be used to compare across more complex calendar types by considering only the time fields:
iex> Time.compare(~N[2015-01-01 16:04:16], ~N[2015-01-01 16:04:28])
:lt
iex> Time.compare(~N[2015-01-01 16:04:16.01], ~N[2000-01-01 16:04:16.001])
:gtfrom_erl(:calendar.time, Calendar.microsecond) :: {:ok, 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}from_erl!(:calendar.time, Calendar.microsecond) :: 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_timeParses the extended “Local time” format described by ISO 8601: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}Parses the extended “Local time” format described by ISO 8601: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_formatnew(Calendar.hour, Calendar.minute, Calendar.second, Calendar.microsecond) :: {:ok, Time.t} | {:error, atom}
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}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}
iex> Time.to_erl(~N[2015-01-01 23:30:15.999])
{23, 30, 15}Converts the given time to ISO 8601:2004.
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"
iex> Time.to_iso8601(~N[2015-01-01 23:00:13])
"23:00:13"
iex> Time.to_iso8601(~N[2015-01-01 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"
iex> Time.to_string(~N[2015-01-01 23:00:00.001])
"23:00:00.001"
iex> Time.to_string(~N[2015-01-01 23:00:00.123456])
"23:00:00.123456"