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

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

Принимает 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}

@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 или с любой точностью до долей секунды из 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(), 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}

@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

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