Время

Структура Time и функции.

Структура Time содержит поля hour, minute, second и microseconds. Новые времена можно создать с помощью функции new/4 или используя сигил ~T:

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

Оба new/4 и сигил возвращают структуру, где к полям времени можно получить доступ напрямую:

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

Функции в этом модуле работают со структурой Time, а также с любой структурой, содержащей те же поля, что и структура Time, такие как NaiveDateTime и DateTime. Такие функции ожидают Calendar.time в своих типах (вместо t).

Разработчики должны избегать непосредственного создания структуры Time и вместо этого полагаться на функции, предоставляемые этим модулем, а также на функции из библиотек календарей сторонних разработчиков.

Краткое описание

Типы

t()

Функции

compare(time1, time2)

Сравнивает две структуры Time.

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

Преобразует кортеж времени Erlang в структуру Time.

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

Преобразует кортеж времени Erlang в структуру Time.

from_iso8601(arg)

Парсит расширенный формат «Локального времени», описанный в ISO 8601:2004.

from_iso8601!(string)

Парсит расширенный формат «Локального времени», описанный в ISO 8601:2004.

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

Создает новое время.

to_erl(map)

Преобразует структуру Time в кортеж времени Erlang.

to_iso8601(map)

Преобразует данное время в формат ISO 8601:2004.

to_string(map)

Преобразует данное время в строку.

utc_now()

Возвращает текущее время в UTC.

Типы

t()

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

Функции

compare(time1, time2)

compare(Calendar.time(), Calendar.time()) :: :lt | :eq | :gt

Сравнивает две структуры Time.

Возвращает :gt если первое время позже второго и :lt в обратном случае. Если два времени равны, возвращается :eq

Примеры

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

Эта функция также может использоваться для сравнения более сложных типов календаря, учитывая только поля времени:

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

Преобразует кортеж времени Erlang в структуру Time.

Примеры

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

Преобразует кортеж времени Erlang в структуру Time.

Примеры

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

Парсит расширенный формат «Локального времени», описанный в ISO 8601:2004.

Смещение часового пояса может быть включено в строку, но оно будет просто проигнорировано, так как такая информация не включается во время.

Как указано в стандарте, разделитель «T» можно опустить, если это необходимо, так как это не приводит к неоднозначности в рамках этой функции.

Представления времени с пониженной точностью не поддерживаются.

Примеры

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

Парсит расширенный формат «Локального времени», описанный в ISO 8601:2004.

Вызывает исключение, если формат некорректен.

Примеры

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

Создает новое время.

Ожидает, что все значения будут целыми числами. Возвращает {:ok, time} если каждое значение находится в соответствующем диапазоне, возвращает {:error, reason} в противном случае.

Обратите внимание, что время может иметь 60 секунд в случае високосных секунд.

Примеры

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

Преобразует структуру Time в кортеж времени Erlang.

ПРЕДУПРЕЖДЕНИЕ: Может произойти потеря точности, так как кортежи времени Erlang содержат только часы/минуты/секунды.

Примеры

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

Преобразует данное время в формат ISO 8601:2004.

Примеры

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

Преобразует данное время в строку.

Примеры

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

Возвращает текущее время в UTC.

Примеры

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