DateTime

Реализация DateTime с часовым поясом.

Эта DateTime может рассматриваться как временный снимок DateTime в заданном часовом поясе. Для этих целей она также включает UTC и стандартные смещения, а также поле сокращения зоны, используемое исключительно для целей форматирования.

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

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

База данных часовых поясов

Многие функции в этом модуле требуют базу данных часовых поясов. По умолчанию используется база данных часовых поясов по умолчанию, возвращаемая функцией Calendar.get_time_zone_database/0, которая по умолчанию использует Calendar.UTCOnlyTimeZoneDatabase, которая обрабатывает только DateTime в формате "Etc/UTC" и возвращает {:error, :utc_only_time_zone_database} для любого другого часового пояса.

Также можно настроить другие базы данных часовых поясов. Например, чтобы использовать базу данных tzdata, сначала убедитесь, что она добавлена в качестве зависимости в mix.exs. Затем её можно настроить либо через конфигурацию:

config :elixir, :time_zone_database, Tzdata.TimeZoneDatabase

либо вызвав функцию Calendar.put_time_zone_database/1:

Calendar.put_time_zone_database(Tzdata.TimeZoneDatabase)

Краткое описание

Типы

t()

Функции

add(datetime, amount_to_add, unit \\ :second, time_zone_database \\ Calendar.get_time_zone_database()): Добавляет указанное количество времени к DateTime.
compare(datetime1, datetime2): Сравнивает две структуры datetime.
convert(datetime, calendar): Преобразует заданную datetime из одного календаря в другой.
convert!(datetime, calendar): Преобразует заданную datetime из одного календаря в другой.
diff(datetime1, datetime2, unit \\ :second): Вычитает datetime2 из datetime1.
from_iso8601(string, calendar \\ Calendar.ISO): Парсит расширенный формат «Дата и время суток», описанный в ISO 8601:2004.
from_naive(naive_datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database()): Преобразует заданную NaiveDateTime в DateTime.
from_naive!(naive_datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database()): Преобразует заданную NaiveDateTime в DateTime.
from_unix(integer, unit \\ :second, calendar \\ Calendar.ISO): Преобразует заданное время Unix в DateTime.
from_unix!(integer, unit \\ :second, calendar \\ Calendar.ISO): Преобразует заданное время Unix в DateTime.
now(time_zone, time_zone_database \\ Calendar.get_time_zone_database()): Возвращает текущую дату и время в указанном часовом поясе.
now!(time_zone, time_zone_database \\ Calendar.get_time_zone_database()): Возвращает текущую дату и время в указанном часовом поясе или генерирует исключение при ошибках
shift_zone(datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database()): Изменяет часовой пояс DateTime.
shift_zone!(datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database()): Изменяет часовой пояс DateTime или генерирует исключение при ошибках.
to_date(map): Преобразует DateTime в Date.
to_iso8601(datetime, format \\ :extended): Преобразует заданную datetime в формат ISO 8601:2004.
to_naive(map): Преобразует заданное datetime в NaiveDateTime.
to_string(datetime): Преобразует заданную datetime в строку в соответствии с её календарём.
to_time(map): Преобразует DateTime в Time.
to_unix(datetime, unit \\ :second): Преобразует заданную datetime в время Unix.
truncate(datetime, precision): Возвращает заданную datetime с отброшенным микросекундным полем до указанной точности (:microsecond, :millisecond или :second).
utc_now(calendar \\ Calendar.ISO): Возвращает текущую datetime в UTC.

Типы

t()

Specs

t() :: %DateTime{
  calendar: Calendar.calendar(),
  day: Calendar.day(),
  hour: Calendar.hour(),
  microsecond: Calendar.microsecond(),
  minute: Calendar.minute(),
  month: Calendar.month(),
  second: Calendar.second(),
  std_offset: Calendar.std_offset(),
  time_zone: Calendar.time_zone(),
  utc_offset: Calendar.utc_offset(),
  year: Calendar.year(),
  zone_abbr: Calendar.zone_abbr()
}

Функции

add(datetime, amount_to_add, unit \ :second, time_zone_database \ Calendar.get_time_zone_database())

Характеристики

add(
  Calendar.datetime(),
  integer(),
  System.time_unit(),
  Calendar.time_zone_database()
) :: t()

Добавляет указанное количество времени к DateTime.

Принимает amount_to_add в любом unit доступном от System.time_unit/0. Отрицательные значения сместят время назад.

Учитываются такие изменения, как летнее/зимнее время. Это означает, что добавление времени может привести к тому, что реальное время "отступит назад" во время "перехода на зимнее время" осенью. Добавление всего нескольких секунд к дате и времени незадолго до "перехода на летнее время" может привести к увеличению реального времени более чем на час.

Точность долей секунды сохраняется аналогично NaiveDateTime.add/2.

Примеры

iex> dt = DateTime.from_naive!(~N[2018-11-15 10:00:00], "Europe/Copenhagen", FakeTimeZoneDatabase)
iex> dt |> DateTime.add(3600, :second, FakeTimeZoneDatabase)
#DateTime<2018-11-15 11:00:00+01:00 CET Europe/Copenhagen>

iex> DateTime.add(~U[2018-11-15 10:00:00Z], 3600, :second)
~U[2018-11-15 11:00:00Z]

При добавлении 3 секунд незадолго до "перехода на летнее время" мы переходим с 1:59:59 до 3:00:02

iex> dt = DateTime.from_naive!(~N[2019-03-31 01:59:59.123], "Europe/Copenhagen", FakeTimeZoneDatabase)
iex> dt |> DateTime.add(3, :second, FakeTimeZoneDatabase)
#DateTime<2019-03-31 03:00:02.123+02:00 CEST Europe/Copenhagen>

compare(datetime1, datetime2)

Характеристики

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

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

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

Обратите внимание, что при сравнении учитываются как смещения UTC, так и стандартные смещения.

Примеры

iex> dt1 = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...>                 hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                 utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> dt2 = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                 hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                 utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.compare(dt1, dt2)
:gt

convert(datetime, calendar)

Характеристики

convert(Calendar.datetime(), Calendar.calendar()) ::
  {:ok, t()} | {:error, :incompatible_calendars}

Преобразует заданную datetime из одного календаря в другой.

Если преобразование между календарями невозможно однозначно (см. Calendar.compatible_calendars?/2), возвращается кортеж {:error, :incompatible_calendars}.

Примеры

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

iex> dt1 = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...>                 hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                 utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> DateTime.convert(dt1, Calendar.Holocene)
{:ok, %DateTime{calendar: Calendar.Holocene, day: 29, hour: 23,
                microsecond: {0, 0}, minute: 0, month: 2, second: 7, std_offset: 0,
                time_zone: "America/Manaus", utc_offset: -14400, year: 12000,
                zone_abbr: "AMT"}}

convert!(datetime, calendar)

Характеристики

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

Преобразует заданную datetime из одного календаря в другой.

Если преобразование между календарями невозможно однозначно (см. Calendar.compatible_calendars?/2), генерируется исключение ArgumentError.

Примеры

iex> dt1 = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...>                 hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                 utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> DateTime.convert!(dt1, Calendar.Holocene)
%DateTime{calendar: Calendar.Holocene, day: 29, hour: 23,
          microsecond: {0, 0}, minute: 0, month: 2, second: 7, std_offset: 0,
          time_zone: "America/Manaus", utc_offset: -14400, year: 12000,
          zone_abbr: "AMT"}

diff(datetime1, datetime2, unit \ :second)

Характеристики

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

Вычисляет разницу между datetime2 и datetime1.

Результат может быть возвращён в любом unit из System.time_unit/0.

Высокоскоростные секунды не учитываются.

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

Примеры

iex> dt1 = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...>                 hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                 utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> dt2 = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                 hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                 utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.diff(dt1, dt2)
18000
iex> DateTime.diff(dt2, dt1)
-18000

from_iso8601(string, calendar \ Calendar.ISO)

Характеристики

from_iso8601(String.t(), Calendar.calendar()) ::
  {:ok, t(), Calendar.utc_offset()} | {:error, atom()}

Парсит расширенный формат "дата и время суток", описанный в ISO 8601:2004.

Так как ISO 8601 не включает правильное часовое смещение, заданная строка будет преобразована в UTC, а её смещение во секундах будет возвращено как часть этой функции. Поэтому информация о смещении должна быть в строке.

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

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

Примеры

iex> {:ok, datetime, 0} = DateTime.from_iso8601("2015-01-23T23:50:07Z")
iex> datetime
~U[2015-01-23 23:50:07Z]

iex> {:ok, datetime, 9000} = DateTime.from_iso8601("2015-01-23T23:50:07.123+02:30")
iex> datetime
~U[2015-01-23 21:20:07.123Z]

iex> {:ok, datetime, 9000} = DateTime.from_iso8601("2015-01-23T23:50:07,123+02:30")
iex> datetime
~U[2015-01-23 21:20:07.123Z]

iex> {:ok, datetime, 0} = DateTime.from_iso8601("-2015-01-23T23:50:07Z")
iex> datetime
~U[-2015-01-23 23:50:07Z]

iex> {:ok, datetime, 9000} = DateTime.from_iso8601("-2015-01-23T23:50:07,123+02:30")
iex> datetime
~U[-2015-01-23 21:20:07.123Z]

iex> DateTime.from_iso8601("2015-01-23P23:50:07")
{:error, :invalid_format}
iex> DateTime.from_iso8601("2015-01-23T23:50:07")
{:error, :missing_offset}
iex> DateTime.from_iso8601("2015-01-23 23:50:61")
{:error, :invalid_time}
iex> DateTime.from_iso8601("2015-01-32 23:50:07")
{:error, :invalid_date}
iex> DateTime.from_iso8601("2015-01-23T23:50:07.123-00:00")
{:error, :invalid_format}

from_naive(naive_datetime, time_zone, time_zone_database \ Calendar.get_time_zone_database())

Характеристики

from_naive(
  Calendar.naive_datetime(),
  Calendar.time_zone(),
  Calendar.time_zone_database()
) ::
  {:ok, t()}
  | {:ambiguous, t(), t()}
  | {:gap, t(), t()}
  | {:error,
     :incompatible_calendars
     | :time_zone_not_found
     | :utc_only_time_zone_database}

Преобразует данную NaiveDateTime в DateTime.

Ожидается часовой пояс для помещения NaiveDateTime в. Если часовой пояс — "Etc/UTC", преобразование всегда выполняется успешно. В противном случае NaiveDateTime проверяется с помощью базы данных часовых поясов, переданной как time_zone_database. См. раздел «База данных часовых поясов» в документации модуля.

Примеры

iex> DateTime.from_naive(~N[2016-05-24 13:26:08.003], "Etc/UTC")
{:ok, ~U[2016-05-24 13:26:08.003Z]}

Если дата и время неоднозначны — например, во время перехода с летнего на зимнее время — возвращаются две возможные допустимые даты и время. Сначала та, которая происходит раньше, затем та, которая происходит позже.

iex> {:ambiguous, first_dt, second_dt} = DateTime.from_naive(~N[2018-10-28 02:30:00], "Europe/Copenhagen", FakeTimeZoneDatabase)
iex> first_dt
#DateTime<2018-10-28 02:30:00+02:00 CEST Europe/Copenhagen>
iex> second_dt
#DateTime<2018-10-28 02:30:00+01:00 CET Europe/Copenhagen>

Когда в реальном времени есть разрыв — например, весной, когда часы переводились вперёд — возвращаются самая поздняя допустимая дата и время непосредственно перед разрывом и самая ранняя допустимая дата и время сразу после разрыва.

iex> {:gap, just_before, just_after} = DateTime.from_naive(~N[2019-03-31 02:30:00], "Europe/Copenhagen", FakeTimeZoneDatabase)
iex> just_before
#DateTime<2019-03-31 01:59:59.999999+01:00 CET Europe/Copenhagen>
iex> just_after
#DateTime<2019-03-31 03:00:00+02:00 CEST Europe/Copenhagen>

Большинство времени для определённой даты и времени в определённом часовом поясе существует одна и только одна допустимая дата и время.

iex> {:ok, datetime} = DateTime.from_naive(~N[2018-07-28 12:30:00], "Europe/Copenhagen", FakeTimeZoneDatabase)
iex> datetime
#DateTime<2018-07-28 12:30:00+02:00 CEST Europe/Copenhagen>

Эта функция принимает любую карту или структуру, содержащую как минимум те же поля, что и структура NaiveDateTime. Наиболее распространённый пример — DateTime. В этом случае информация о часовом поясе этого DateTime полностью игнорируется. Это тот же принцип, что и передача DateTime в Date.to_iso8601/2. Date.to_iso8601/2 извлекает только поля, относящиеся к дате (календарь, год, месяц и день) заданной структуры и игнорирует все остальные.

Таким образом, если у вас есть DateTime в одном часовом поясе, вы можете получить то же реальное время в другом часовом поясе. Например, если у вас есть 2018-08-24 10:00:00 в Копенгагене и вам нужна DateTime для 2018-08-24 10:00:00 в UTC, вы можете сделать:

iex> cph_datetime = DateTime.from_naive!(~N[2018-08-24 10:00:00], "Europe/Copenhagen", FakeTimeZoneDatabase)
iex> {:ok, utc_datetime} = DateTime.from_naive(cph_datetime, "Etc/UTC", FakeTimeZoneDatabase)
iex> utc_datetime
~U[2018-08-24 10:00:00Z]

Если вместо этого вы хотите DateTime для той же точки времени в другом часовом поясе, см. функцию DateTime.shift_zone/3, которая преобразует 2018-08-24 10:00:00 в Копенгагене в 2018-08-24 08:00:00 в UTC.

from_naive!(naive_datetime, time_zone, time_zone_database \ Calendar.get_time_zone_database())

Характеристики

from_naive!(
  NaiveDateTime.t(),
  Calendar.time_zone(),
  Calendar.time_zone_database()
) :: t()

Преобразует данную NaiveDateTime в DateTime.

Ожидается часовой пояс для помещения NaiveDateTime в. Если часовой пояс — "Etc/UTC", преобразование всегда выполняется успешно. В противном случае NaiveDateTime проверяется с помощью базы данных часовых поясов, переданной как time_zone_database. См. раздел «База данных часовых поясов» в документации модуля.

Примеры

iex> DateTime.from_naive!(~N[2016-05-24 13:26:08.003], "Etc/UTC")
~U[2016-05-24 13:26:08.003Z]

iex> DateTime.from_naive!(~N[2018-05-24 13:26:08.003], "Europe/Copenhagen", FakeTimeZoneDatabase)
#DateTime<2018-05-24 13:26:08.003+02:00 CEST Europe/Copenhagen>

from_unix(integer, unit \ :second, calendar \ Calendar.ISO)

Характеристики

from_unix(integer(), :native | System.time_unit(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

Преобразует заданное время Unix в DateTime.

Целое число может быть задано в разных единицах измерения согласно System.convert_time_unit/3, и оно будет преобразовано во внутренние микросекунды.

Временные метки Unix всегда находятся в UTC, поэтому DateTime будет возвращаться в UTC.

Примеры

iex> {:ok, datetime} = DateTime.from_unix(1_464_096_368)
iex> datetime
~U[2016-05-24 13:26:08Z]

iex> {:ok, datetime} = DateTime.from_unix(1_432_560_368_868_569, :microsecond)
iex> datetime
~U[2015-05-25 13:26:08.868569Z]

Единица также может быть целым числом, как в System.time_unit/0:

iex> {:ok, datetime} = DateTime.from_unix(143_256_036_886_856, 1024)
iex> datetime
~U[6403-03-17 07:05:22.320312Z]

Поддерживаются отрицательные значения времени Unix до -62167219200 секунд, что эквивалентно "0000-01-01T00:00:00Z" или 0 григорианских секунд.

from_unix!(integer, unit \ :second, calendar \ Calendar.ISO)

Характеристики

from_unix!(integer(), :native | System.time_unit(), Calendar.calendar()) :: t()

Преобразует заданное время Unix в DateTime.

Временные метки Unix всегда находятся в UTC, поэтому DateTime будет возвращаться в UTC.

Примеры

# An easy way to get the Unix epoch is passing 0 to this function
iex> DateTime.from_unix!(0)
~U[1970-01-01 00:00:00Z]

iex> DateTime.from_unix!(1_464_096_368)
~U[2016-05-24 13:26:08Z]

iex> DateTime.from_unix!(1_432_560_368_868_569, :microsecond)
~U[2015-05-25 13:26:08.868569Z]

iex> DateTime.from_unix!(143_256_036_886_856, 1024)
~U[6403-03-17 07:05:22.320312Z]

now(time_zone, time_zone_database \ Calendar.get_time_zone_database())

Характеристики

now(Calendar.time_zone(), Calendar.time_zone_database()) ::
  {:ok, t()} | {:error, :time_zone_not_found | :utc_only_time_zone_database}

Возвращает текущее значение datetime в заданном часовом поясе.

По умолчанию используется значение по умолчанию для часового пояса, возвращаемое Calendar.get_time_zone_database/0, которое по умолчанию равно Calendar.UTCOnlyTimeZoneDatabase, обрабатывающему только даты и время "Etc/UTC". Другие базы данных часовых поясов могут быть переданы в качестве аргумента или установлены глобально. См. раздел «База данных часовых поясов» в документации модуля.

Примеры

iex> {:ok, datetime} = DateTime.now("Etc/UTC")
iex> datetime.time_zone
"Etc/UTC"

iex> DateTime.now("Europe/Copenhagen")
{:error, :utc_only_time_zone_database}

iex> DateTime.now("bad timezone", FakeTimeZoneDatabase)
{:error, :time_zone_not_found}

now!(time_zone, time_zone_database \ Calendar.get_time_zone_database())

Характеристики

now!(Calendar.time_zone(), Calendar.time_zone_database()) :: t()

Возвращает текущую дату и время в указанном часовом поясе, или вызывает исключение при ошибках

См. now/2 для получения дополнительной информации.

Примеры

iex> datetime = DateTime.now!("Etc/UTC")
iex> datetime.time_zone
"Etc/UTC"

iex> DateTime.now!("Europe/Copenhagen")
** (ArgumentError) cannot get current datetime in "Europe/Copenhagen" time zone, reason: :utc_only_time_zone_database

iex> DateTime.now!("bad timezone", FakeTimeZoneDatabase)
** (ArgumentError) cannot get current datetime in "bad timezone" time zone, reason: :time_zone_not_found

shift_zone(datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database())

Характеристики

shift_zone(t(), Calendar.time_zone(), Calendar.time_zone_database()) ::
  {:ok, t()} | {:error, :time_zone_not_found | :utc_only_time_zone_database}

Изменяет часовой пояс DateTime.

Возвращает DateTime для той же точки во времени, но в указанном часовом поясе. Предполагается, что DateTime является допустимым и существует в заданном часовом поясе и календаре.

По умолчанию используется базовая база данных часовых поясов, возвращаемая Calendar.get_time_zone_database/0, которая по умолчанию установлена в Calendar.UTCOnlyTimeZoneDatabase, обрабатывающая только даты/время «Etc/UTC». Другие базы данных часовых поясов могут быть переданы в качестве аргумента или установлены глобально. Смотрите раздел «База данных часовых поясов» в документации модуля.

Примеры

iex> {:ok, pacific_datetime} = DateTime.shift_zone(~U[2018-07-16 10:00:00Z], "America/Los_Angeles", FakeTimeZoneDatabase)
iex> pacific_datetime
#DateTime<2018-07-16 03:00:00-07:00 PDT America/Los_Angeles>

iex> DateTime.shift_zone(~U[2018-07-16 10:00:00Z], "bad timezone", FakeTimeZoneDatabase)
{:error, :time_zone_not_found}

shift_zone!(datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database())

Характеристики

shift_zone!(t(), Calendar.time_zone(), Calendar.time_zone_database()) :: t()

Изменяет часовой пояс DateTime или вызывает ошибку при проблемах.

См. shift_zone/3 для дополнительной информации.

Примеры

iex> DateTime.shift_zone!(~U[2018-07-16 10:00:00Z], "America/Los_Angeles", FakeTimeZoneDatabase)
#DateTime<2018-07-16 03:00:00-07:00 PDT America/Los_Angeles>

iex> DateTime.shift_zone!(~U[2018-07-16 10:00:00Z], "bad timezone", FakeTimeZoneDatabase)
** (ArgumentError) cannot shift ~U[2018-07-16 10:00:00Z] to "bad timezone" time zone, reason: :time_zone_not_found

to_date(map)

Характеристики

to_date(Calendar.datetime()) :: Date.t()

Преобразует DateTime в Date.

Поскольку Date не содержит информации о времени или часовом поясе, данные будут потеряны при преобразовании.

Примеры

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_date(dt)
~D[2000-02-29]

to_iso8601(datetime, format \\ :extended)

Характеристики

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

Преобразует заданную дату/время в формат ISO 8601:2004.

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

Поддерживает только преобразование дат/времени, находящихся в календаре ISO. Попытка преобразования дат/времени из других календарей вызовет ошибку.

ПРЕДУПРЕЖДЕНИЕ: формат даты/времени ISO 8601 не содержит часовой пояс ни его сокращенного обозначения, что означает потерю информации при преобразовании в такой формат.

Примеры

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_iso8601(dt)
"2000-02-29T23:00:07+01:00"

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "UTC",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> DateTime.to_iso8601(dt)
"2000-02-29T23:00:07Z"

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> DateTime.to_iso8601(dt, :extended)
"2000-02-29T23:00:07-04:00"

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> DateTime.to_iso8601(dt, :basic)
"20000229T230007-0400"

to_naive(map)

Характеристики

to_naive(Calendar.datetime()) :: NaiveDateTime.t()

Преобразует заданный datetime в NaiveDateTime.

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

Примеры

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 1},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_naive(dt)
~N[2000-02-29 23:00:07.0]

to_string(datetime)

Характеристики

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

Преобразует заданное datetime в строку в соответствии с его календарем.

Примеры

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_string(dt)
"2000-02-29 23:00:07+01:00 CET Europe/Warsaw"

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "UTC",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> DateTime.to_string(dt)
"2000-02-29 23:00:07Z"

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "AMT",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: -14400, std_offset: 0, time_zone: "America/Manaus"}
iex> DateTime.to_string(dt)
"2000-02-29 23:00:07-04:00 AMT America/Manaus"

iex> dt = %DateTime{year: -100, month: 12, day: 19, zone_abbr: "CET",
...>                hour: 3, minute: 20, second: 31, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Stockholm"}
iex> DateTime.to_string(dt)
"-0100-12-19 03:20:31+01:00 CET Europe/Stockholm"

to_time(map)

Характеристики

to_time(Calendar.datetime()) :: Time.t()

Преобразует DateTime в Time.

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

Примеры

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 1},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_time(dt)
~T[23:00:07.0]

to_unix(datetime, unit \\ :second)

Характеристики

to_unix(Calendar.datetime(), System.time_unit()) :: integer()

Преобразует заданное datetime в время Unix.

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

Будет возвращено целое число с указанным типом, согласно System.convert_time_unit/3.

Примеры

iex> 1_464_096_368 |> DateTime.from_unix!() |> DateTime.to_unix()
1464096368

iex> dt = %DateTime{calendar: Calendar.ISO, day: 20, hour: 18, microsecond: {273806, 6},
...>                minute: 58, month: 11, second: 19, time_zone: "America/Montevideo",
...>                utc_offset: -10800, std_offset: 3600, year: 2014, zone_abbr: "UYST"}
iex> DateTime.to_unix(dt)
1416517099

iex> flamel = %DateTime{calendar: Calendar.ISO, day: 22, hour: 8, microsecond: {527771, 6},
...>                minute: 2, month: 3, second: 25, std_offset: 0, time_zone: "Etc/UTC",
...>                utc_offset: 0, year: 1418, zone_abbr: "UTC"}
iex> DateTime.to_unix(flamel)
-17412508655

truncate(datetime, precision)

Характеристики

truncate(Calendar.datetime(), :microsecond | :millisecond | :second) :: t()

Возвращает заданную дату/время с усечённой микросекундной частью до заданной точности (:microsecond, :millisecond или :second).

Заданная дата/время возвращается без изменений, если она уже имеет меньшую точность, чем заданная.

Примеры

iex> dt1 = %DateTime{year: 2017, month: 11, day: 7, zone_abbr: "CET",
...>                 hour: 11, minute: 45, second: 18, microsecond: {123456, 6},
...>                 utc_offset: 3600, std_offset: 0, time_zone: "Europe/Paris"}
iex> DateTime.truncate(dt1, :microsecond)
#DateTime<2017-11-07 11:45:18.123456+01:00 CET Europe/Paris>

iex> dt2 = %DateTime{year: 2017, month: 11, day: 7, zone_abbr: "CET",
...>                 hour: 11, minute: 45, second: 18, microsecond: {123456, 6},
...>                 utc_offset: 3600, std_offset: 0, time_zone: "Europe/Paris"}
iex> DateTime.truncate(dt2, :millisecond)
#DateTime<2017-11-07 11:45:18.123+01:00 CET Europe/Paris>

iex> dt3 = %DateTime{year: 2017, month: 11, day: 7, zone_abbr: "CET",
...>                 hour: 11, minute: 45, second: 18, microsecond: {123456, 6},
...>                 utc_offset: 3600, std_offset: 0, time_zone: "Europe/Paris"}
iex> DateTime.truncate(dt3, :second)
#DateTime<2017-11-07 11:45:18+01:00 CET Europe/Paris>

utc_now(calendar \\ Calendar.ISO)

Характеристики

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

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

Примеры

iex> datetime = DateTime.utc_now()
iex> datetime.time_zone
"Etc/UTC"