Время
Структура Time и функции.
Структура Time содержит поля hour, minute, second и microseconds. Новое время можно создать с помощью функции new/4 или используя сигил ~T (см. sigil_T/2):
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 с использованием ==/2, >/2, </2 и аналогичных структурных, основанные на полях структуры Time. Для правильного сравнения времён используйте функцию compare/2. Наличие функции compare/2 в этом модуле также позволяет использовать функции Enum.min/2 и Enum.max/2 для получения минимального и максимального времени из Enum. Например:
iex> Enum.min([~T[23:00:07.001], ~T[10:00:07.001]], Time) ~T[10:00:07.001]
Типы
Функции
- add(time, amount_to_add, unit \\ :second)
Добавляет
amount_to_addunitк заданномуtime.- after?(time1, time2)
Возвращает true, если первое время строго позже второго.
- before?(time1, time2)
Возвращает true, если первое время строго раньше второго.
- 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:2019.
- from_iso8601!(string, calendar \\ Calendar.ISO)
Парсит расширенный формат «Локальное время», описанный в ISO 8601:2019.
- from_seconds_after_midnight(seconds, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)
Преобразует количество секунд после полуночи в структуру
Time.- new(hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)
Создаёт новое время.
- new!(hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)
Создаёт новое время.
- to_erl(time)
Преобразует заданное
timeв кортеж Erlang времени.- to_iso8601(time, format \\ :extended)
Преобразует заданное время в ISO 8601:2019.
- to_seconds_after_midnight(time)
Преобразует структуру
Timeв количество секунд после полуночи.- to_string(time)
Преобразует заданное
timeв строку.- truncate(time, precision)
Возвращает заданное время с полем microsecond, усечённым до заданной точности (
:microsecond,millisecondили:second).- utc_now(calendar \\ Calendar.ISO)
Возвращает текущее время в UTC.
t()Source
@type t() :: %Time{
calendar: Calendar.calendar(),
hour: Calendar.hour(),
microsecond: Calendar.microsecond(),
minute: Calendar.minute(),
second: Calendar.second()
} add(time, amount_to_add, unit \\ :second)Source
@spec add(Calendar.time(), integer(), :hour | :minute | System.time_unit()) :: t()
Добавляет заданное amount_to_add количества unit к заданному time.
Принимает amount_to_add в любом unit. unit может быть :hour, :minute, :second или любой точностью до доли секунды из System.time_unit/0. По умолчанию используется :second. Отрицательные значения будут перемещать во времени назад.
Эта функция всегда учитывает единицы измерения, вычисляемые в соответствии с Calendar.ISO.
Обратите внимание, что возвращаемое значение представляет время суток, что означает цикличность. Например, для календаря ISO оно никогда не превысит 24 часа.
Примеры
iex> Time.add(~T[10:00:00], 27000) ~T[17:30:00] iex> Time.add(~T[11:00:00.005], 2400) ~T[11:40:00.005] iex> Time.add(~T[00:00:00.000], 86_399_999, :millisecond) ~T[23:59:59.999]
Разрешены отрицательные значения:
iex> Time.add(~T[23:00:00], -60) ~T[22:59:00]
Обратите внимание, что время циклическое:
iex> Time.add(~T[17:10:05], 86400) ~T[17:10:05]
Также поддерживаются часы и минуты:
iex> Time.add(~T[17:10:05], 2, :hour) ~T[19:10:05] iex> Time.add(~T[17:10:05], 30, :minute) ~T[17:40:05]
Эта операция объединяет точность времени с заданными единицами:
iex> result = Time.add(~T[00:29:10], 21, :millisecond)
~T[00:29:10.021]
iex> result.microsecond
{21000, 3} after?(time1, time2)Source
@spec after?(Calendar.time(), Calendar.time()) :: boolean()
Возвращает true, если первое время строго позже второго.
Примеры
iex> Time.after?(~T[16:04:28], ~T[16:04:16]) true iex> Time.after?(~T[16:04:16], ~T[16:04:16]) false iex> Time.after?(~T[16:04:16.001], ~T[16:04:16.01]) false
before?(time1, time2)Source
@spec before?(Calendar.time(), Calendar.time()) :: boolean()
Возвращает true, если первое время строго раньше второго.
Примеры
iex> Time.before?(~T[16:04:16], ~T[16:04:28]) true iex> Time.before?(~T[16:04:16], ~T[16:04:16]) false iex> Time.before?(~T[16:04:16.01], ~T[16:04:16.001]) false
compare(time1, time2)Source
@spec 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)Source
@spec 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)Source
@spec convert!(Calendar.time(), Calendar.calendar()) :: t()
Аналогично Time.convert/2, но генерирует исключение ArgumentError, если преобразование между двумя календарями невозможно.
Примеры
Представьте, что кто-то реализовал Calendar.Holocene, календарь, основанный на григорианском календаре, который добавляет ровно 10 000 лет к текущему григорианскому году:
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)Source
@spec diff(Calendar.time(), Calendar.time(), :hour | :minute | System.time_unit()) :: integer()
Возвращает разницу между двумя временами, учитывая только часы, минуты, секунды и микросекунды.
Как и в функции compare/2, могут использоваться как структуры Time, так и другие структуры, содержащие время. Например, если переданы NaiveDateTime или DateTime, учитываются только часы, минуты, секунды и микросекунды. Любая дополнительная информация о дате или часовом поясе игнорируется при расчете разницы.
Результат может быть возвращён в любых :hour, :minute, :second или любой точности до доли секунды unit из System.time_unit/0. Если первое значение времени раньше второго, возвращается отрицательное число.
Единицы измерения определяются по Calendar.ISO и по умолчанию составляют :second. Дробные результаты не поддерживаются и усекаются.
Примеры
iex> Time.diff(~T[00:29:12], ~T[00:29:10]) 2 # When passing a `NaiveDateTime` the date part is ignored. iex> Time.diff(~N[2017-01-01 00:29:12], ~T[00:29:10]) 2 # Two `NaiveDateTime` 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 iex> Time.diff(~T[02:29:10], ~T[00:29:10], :hour) 2 iex> Time.diff(~T[02:29:10], ~T[00:29:11], :hour) 1
from_erl(tuple, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)Source
@spec 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)Source
@spec 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)Source
@spec from_iso8601(String.t(), Calendar.calendar()) :: {:ok, t()} | {:error, atom()} Парсит расширенный формат «Локальное время», описанный в ISO 8601:2019.
Смещение часового пояса может быть включено в строку, но оно будет просто проигнорировано, так как такая информация не включена во времени.
Как указано в стандарте, разделитель «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.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, calendar \\ Calendar.ISO)Source
@spec from_iso8601!(String.t(), Calendar.calendar()) :: t()
Парсит расширенный формат «Локальное время», описанный в ISO 8601:2019.
Вызывает исключение, если формат недействителен.
Примеры
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 from_seconds_after_midnight(seconds, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)Source
@spec from_seconds_after_midnight( integer(), Calendar.microsecond(), Calendar.calendar() ) :: t()
Преобразует количество секунд после полуночи в структуру Time.
Примеры
iex> Time.from_seconds_after_midnight(10_000)
~T[02:46:40]
iex> Time.from_seconds_after_midnight(30_000, {5000, 3})
~T[08:20:00.005]
iex> Time.from_seconds_after_midnight(-1)
~T[23:59:59]
iex> Time.from_seconds_after_midnight(100_000)
~T[03:46:40] new(hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)Source
@spec new(
Calendar.hour(),
Calendar.minute(),
Calendar.second(),
Calendar.microsecond() | non_neg_integer(),
Calendar.calendar()
) :: {:ok, t()} | {:error, atom()} Создаёт новую структуру времени.
Ожидаются все целочисленные значения. Возвращает {:ok, time} если каждое значение попадает в свой диапазон, возвращает {:error, reason} в противном случае.
Микросекунды также могут быть заданы с точностью, которая должна быть целым числом от 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(24, 59, 59, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 60, 59, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 59, 60, 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} new!(hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)Source
@spec new!( Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond() | non_neg_integer(), Calendar.calendar() ) :: t()
Создаёт новую структуру времени.
Ожидаются все целочисленные значения. Возвращает time если каждое значение попадает в свой диапазон, генерирует исключение, если время недействительно.
Микросекунды также могут быть заданы с точностью, которая должна быть целым числом от 0 до 6.
Встроенный календарь не поддерживает високосные секунды.
Примеры
iex> Time.new!(0, 0, 0, 0) ~T[00:00:00.000000] iex> Time.new!(23, 59, 59, 999_999) ~T[23:59:59.999999] iex> Time.new!(24, 59, 59, 999_999) ** (ArgumentError) cannot build time, reason: :invalid_time
to_erl(time)Source
@spec 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)Source
@spec to_iso8601(Calendar.time(), :extended | :basic) :: String.t()
Преобразует заданное время в формат ISO 8601:2019.
По умолчанию, Time.to_iso8601/2 возвращает отформатированное время в формате "extended" для удобочитаемости. Также поддерживается формат "basic" посредством передачи опции :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_seconds_after_midnight(time)Source
@spec to_seconds_after_midnight(Calendar.time()) :: {integer(), non_neg_integer()} Преобразует структуру Time в количество секунд после полуночи.
Возвращаемое значение — кортеж из двух элементов: количество секунд и микросекунд.
Примеры
iex> Time.to_seconds_after_midnight(~T[23:30:15])
{84615, 0}
iex> Time.to_seconds_after_midnight(~N[2010-04-17 23:30:15.999])
{84615, 999000} to_string(time)Source
@spec 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"
truncate(time, precision)Source
@spec truncate(t(), :microsecond | :millisecond | :second) :: t()
Возвращает заданное время с усечённым полем микросекунд до указанной точности (:microsecond, millisecond или :second).
Заданное время возвращается без изменений, если оно уже имеет меньшую точность, чем заданная.
Примеры
iex> Time.truncate(~T[01:01:01.123456], :microsecond) ~T[01:01:01.123456] iex> Time.truncate(~T[01:01:01.123456], :millisecond) ~T[01:01:01.123] iex> Time.truncate(~T[01:01:01.123456], :second) ~T[01:01:01]
utc_now(calendar \\ Calendar.ISO)Source
@spec utc_now(Calendar.calendar()) :: t()
Возвращает текущее время в UTC.
Примеры
iex> time = Time.utc_now() iex> time.hour >= 0 true
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.15.4/Time.html
