Time

Time

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.

Summary

Types

t()

Functions

compare(time1, time2)

Compares two Time structs

from_erl(arg, microsecond \\ {0, 0})

Converts an Erlang time tuple to a Time struct

from_erl!(tuple, microsecond \\ {0, 0})

Converts an Erlang time tuple to a Time struct

from_iso8601(arg)

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

from_iso8601!(string)

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

new(hour, minute, second, microsecond \\ {0, 0})

Builds a new time

to_erl(map)

Converts a Time struct to an Erlang time tuple

to_iso8601(map)

Converts the given time to ISO 8601:2004

to_string(map)

Converts the given time to a string

utc_now()

Returns the current time in UTC

Types

t()

t() :: %Time{hour: Calendar.hour, microsecond: Calendar.microsecond, minute: Calendar.minute, second: Calendar.second}

Functions

compare(time1, time2)

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])
:gt

This 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])
:gt

from_erl(arg, microsecond \\ {0, 0})

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

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_time

from_iso8601(arg)

from_iso8601(String.t) :: {:ok, t} | {:error, atom}

Parses 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}

from_iso8601!(string)

from_iso8601!(String.t) :: t | no_return

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_format

new(hour, minute, second, microsecond \\ {0, 0})

new(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}

to_erl(map)

to_erl(Calendar.time) :: :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}

iex> Time.to_erl(~N[2015-01-01 23:30:15.999])
{23, 30, 15}

to_iso8601(map)

to_iso8601(Calendar.time) :: String.t

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"

to_string(map)

to_string(Calendar.time) :: String.t

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"

utc_now()

utc_now() :: t

Returns the current time in UTC.

Examples

iex> time = Time.utc_now()
iex> time.hour >= 0
true

© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.4.5/Time.html

在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号

意见反馈
返回顶部