Spec-Zone.ru › Elixir 1.17

Исходный код Время

Структура и функции времени.

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

Резюме

Типы

t()

Функции

add(time, amount_to_add, unit \\ :second)

Добавляет amount_to_add unit к заданному 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)

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

shift(time, duration)

Смещает данное time на duration в соответствии с его календарём.

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, millisecond или :second).

utc_now(calendar \\ Calendar.ISO)

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

Типы

t()Исходный код 

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

Функции

add(время, добавляемое_значение, единица \\ :секунда)Источник 

@spec add(Calendar.time(), integer(), :hour | :minute | System.time_unit()) :: t()

Добавляет указанное amount_to_add к заданному time.

Принимает amount_to_add в любой unit. unit может быть :hour, :minute, :second или любой точностью долей секунды из System.time_unit/0. По умолчанию :second. Отрицательные значения будут смещать во времени назад.

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

Обратите внимание, что значение результата представляет время суток, что означает, что оно циклическое, например, оно никогда не превысит 24 часа для календаря ISO.

Примеры 

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}

Чтобы сдвинуть время на Duration и в соответствии с его базовым календарем, используйте Time.shift/2.

after?(время1, время2)Источник 

@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?(время1, время2)Источник 

@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(время1, время2)Источник 

@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(время, календарь)Источник 

@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!(время, календарь)Источник 

@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(время1, время2, единица \\ :секунда)Источник 

@spec diff(Calendar.time(), Calendar.time(), :hour | :minute | System.time_unit()) ::
  integer()

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

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

Результат может быть возвращен в любой :hour, :minute, :second или любой точности долей секунды из 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(кортеж, микросекунда \\ {0, 0}, календарь \\ Calendar.ISO)Источник 

@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!(кортеж, микросекунда \\ {0, 0}, календарь \\ Calendar.ISO)Источник 

@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(строка, календарь \\ Calendar.ISO)Источник 

@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!(строка, календарь \\ Calendar.ISO)Источник 

@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(секунды, микросекунда \\ {0, 0}, календарь \\ Calendar.ISO)Источник 

@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(час, минута, секунда, микросекунда \\ {0, 0}, календарь \\ Calendar.ISO)Источник 

@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!(час, минута, секунда, микросекунда \\ {0, 0}, календарь \\ Calendar.ISO)Источник 

@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

shift(time, duration)Source 

@spec shift(Calendar.time(), Duration.t() | [unit_pair]) :: t()
when unit_pair:
       {:hour, integer()}
       | {:minute, integer()}
       | {:second, integer()}
       | {:microsecond, {integer(), 0..6}}

Смещает заданное time на duration в соответствии с его календарём.

Доступные единицы измерения продолжительности: :hour, :minute, :second, :microsecond.

При использовании по умолчанию календаря ISO, продолжительности сводятся ко секундам и микросекундам перед применением.

Вызывает исключение ArgumentError при вызове с единицами масштаба дат.

Примеры 

iex> Time.shift(~T[01:00:15], hour: 12)
~T[13:00:15]
iex> Time.shift(~T[01:35:00], hour: 6, minute: -15)
~T[07:20:00]
iex> Time.shift(~T[01:15:00], second: 125)
~T[01:17:05]
iex> Time.shift(~T[01:00:15], microsecond: {100, 6})
~T[01:00:15.000100]
iex> Time.shift(~T[01:15:00], Duration.new!(second: 65))
~T[01:16:05]

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 возвращает отформатированное время в "расширенном" формате для лучшей читабельности. Также поддерживается "базовый" формат, передав :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

Скачать версию ePub

Создано с помощью ExDoc (v0.34.1) для языка программирования Elixir

© 2012-2024 The Elixir Team
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.17.2/Time.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API