@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.

@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

@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

@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

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

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

@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

@spec from_erl(
  :calendar.time(),
  Calendar.microsecond() | non_neg_integer(),
  Calendar.calendar()
) :: {:ok, t()} | {:error, atom()}

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

Примеры

iex> Time.from_erl({23, 30, 15})
{:ok, ~T[23:30:15]}
iex> Time.from_erl({23, 30, 15}, 5000)
{:ok, ~T[23:30:15.005000]}
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}

@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)
~T[23:30:15.005000]
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

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

@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

@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]

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

@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

@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]

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

@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"

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

@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"

@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]

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

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

Примеры

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