Время

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

Структура Time содержит поля час, минута, секунда и микросекунда. Новые моменты времени можно создать с помощью функции 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/0 в своих спецификациях типов (вместо t/0).

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

Сравнение моментов времени

Сравнения в Elixir с помощью ==, >, < и аналогичных структурных и основаны на полях структуры Time. Для правильного сравнения моментов времени используйте функцию compare/2.

Резюме

Типы

t()

Функции

compare(time1, time2): Сравнивает две структуры времени
convert(time, calendar): Преобразует заданное time в другой календарь
convert!(time, calendar): Аналогично Time.convert/2, но вызывает исключение ArgumentError, если преобразование между двумя календарями невозможно
diff(time1, time2, unit \\ :second): Возвращает разницу между двумя моментами времени, учитывая только час, минуту, секунду и микросекунды
from_erl(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO): Преобразует кортеж Erlang времени в структуру Time
from_erl!(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO): Преобразует кортеж Erlang времени в структуру Time
from_iso8601(string, calendar \\ Calendar.ISO): Парсит расширенный формат «Локальное время», описанный в ISO 8601:2004
from_iso8601!(string): Парсит расширенный формат «Локальное время», описанный в ISO 8601:2004
new(hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO): Создаёт новый момент времени
to_erl(time): Преобразует заданное time в кортеж Erlang времени
to_iso8601(time, format \\ :extended): Преобразует заданный момент времени в формат ISO 8601:2004
to_string(time): Преобразует заданное time в строку
utc_now(calendar \\ Calendar.ISO): Возвращает текущее время в UTC

Типы

t()

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

Функции

compare(time1, time2)

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

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

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

Примеры

iex> Time.compare(~T[16:04:16], ~T[16:04:28])
:lt
iex> Time.compare(~T[16:04:16], ~T[16:04:16])
:eq
iex> Time.compare(~T[16:04:16.01], ~T[16:04:16.001])
:gt

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

iex> Time.compare(~N[1900-01-01 16:04:16], ~N[2015-01-01 16:04:16])
:eq
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

convert(time, calendar)

convert(Calendar.time(), Calendar.calendar()) ::
  {:ok, t()} |
  {:error, atom()}

Преобразует заданное time в другой календарь.

Возвращает {:ok, time}, если преобразование прошло успешно, или {:error, reason}, если нет, по какой-либо причине.

Примеры

Представьте, что кто-то реализовал Calendar.Holocene, календарь, основанный на григорианском календаре, который добавляет ровно 10 000 лет к текущему григорианскому году:

iex> Time.convert(~T[13:30:15], Calendar.Holocene)
{:ok, %Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}}

convert!(time, calendar)

convert!(Calendar.time(), Calendar.calendar()) :: t()

Аналогично Time.convert/2, но вызывает исключение ArgumentError, если преобразование между двумя календарями невозможно.

Примеры

iex> Time.convert!(~T[13:30:15], Calendar.Holocene)
%Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}

diff(time1, time2, unit \\ :second)

diff(Calendar.time(), Calendar.time(), System.time_unit()) :: integer()

Возвращает разницу между двумя моментами времени, учитывая только час, минуту, секунду и микросекунды.

Как и функция compare/2, могут использоваться как структуры Time, так и другие структуры, содержащие время. Например, если передаётся NaiveDateTime или DateTime, учитываются только час, минута, секунда и микросекунда. Любая дополнительная информация о дате или часовом поясе игнорируется при вычислении разницы.

Результат может быть возвращён в любом unit доступном из System.time_unit/0. Если первый параметр меньше второго, возвращается отрицательное число.

Функция возвращает разницу в секундах, где секунды измеряются согласно Calendar.ISO.

Примеры

iex> Time.diff(~T[00:29:12], ~T[00:29:10])
2

# When passing a [`NaiveDateTime`](NaiveDateTime.html) the date part is ignored.
iex> Time.diff(~N[2017-01-01 00:29:12], ~T[00:29:10])
2

# Two [`NaiveDateTime`](NaiveDateTime.html) structs could have big differences in the date
# but only the time part is considered.
iex> Time.diff(~N[2017-01-01 00:29:12], (~N[1900-02-03 00:29:10]))
2

iex> Time.diff(~T[00:29:12], ~T[00:29:10], :microsecond)
2_000_000
iex> Time.diff(~T[00:29:10], ~T[00:29:12], :microsecond)
-2_000_000

from_erl(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)

from_erl(:calendar.time(), Calendar.microsecond(), Calendar.calendar()) ::
  {: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}, calendar \\ Calendar.ISO)

from_erl!(:calendar.time(), Calendar.microsecond(), Calendar.calendar()) :: t()

Преобразует кортеж 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(string, calendar \\ Calendar.ISO)

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

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

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

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

Обратите внимание, что, хотя ISO8601 допускает представление времени 24:00:00 как нулевой час следующего дня, эта запись не поддерживается в Elixir.

Примеры

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

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

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

Примеры

iex> Time.from_iso8601!("23:50:07,123Z")
~T[23:50:07.123]
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}, calendar \\ Calendar.ISO)

new(Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond(), Calendar.calendar()) ::
  {:ok, t()} |
  {:error, atom()}

Создаёт новый момент времени.

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

Обратите внимание, что время может иметь 60 секунд в случае високосных секунд. Микросекунды также могут быть указаны с точностью, которая должна быть целым числом от 0 до 6.

Примеры

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}

# Invalid precision
Time.new(23, 59, 59, {999_999, 10})
{:error, :invalid_time}

to_erl(time)

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[2010-04-17 23:30:15.999])
{23, 30, 15}

to_iso8601(time, format \\ :extended)

to_iso8601(Calendar.time(), :extended | :basic) :: String.t()

Преобразует заданный момент времени в ISO 8601:2004.

По умолчанию Time.to_iso8601/2 возвращает время в формате «расширенном» для удобства чтения человеком. Также поддерживается формат «базовый» путём передачи :basic опции.

Примеры

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(~T[23:00:13.001], :basic)
"230013.001"

iex> Time.to_iso8601(~N[2010-04-17 23:00:13])
"23:00:13"

to_string(time)

to_string(Calendar.time()) :: String.t()

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

Примеры

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(calendar \\ Calendar.ISO)

utc_now(Calendar.calendar()) :: t()

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

Примеры

%%%CODE_BLOCK_74%%>