DateTime
Реализация DateTime с часовым поясом.
Эта дата и время можно рассматривать как снимок даты и времени в заданном часовом поясе. Для таких целей она также включает как смещение UTC, так и стандартное смещение, а также поле аббревиатуры пояса, используемое исключительно для форматирования. Обратите внимание, что будущие даты и время не обязательно гарантированы, так как часовые пояса могут меняться в любое время в будущем из-за геополитических причин. Для получения дополнительной информации см. раздел «Даты и время как снимки».
Помните, что сравнения в Elixir, используя ==/2, >/2, </2 и аналогичные функции, являются структурными и основаны на полях структуры DateTime. Для правильного сравнения дат и времени используйте функцию compare/2. Наличие функции compare/2 в этом модуле также позволяет использовать функции Enum.min/2 и Enum.max/2 для получения минимальной и максимальной даты и времени Enum. Например:
iex> Enum.min([~U[2022-01-12 00:01:00.00Z], ~U[2021-01-12 00:01:00.00Z]], DateTime) ~U[2021-01-12 00:01:00.00Z]
Разработчики должны избегать создания структуры DateTime напрямую и вместо этого полагаться на функции, предоставляемые этим модулем, а также на функции сторонних библиотек календаря.
База данных часовых поясов
Многие функции в этом модуле требуют базу данных часовых поясов. По умолчанию используется база данных часовых поясов по умолчанию, возвращаемая Calendar.get_time_zone_database/0, которая по умолчанию равна Calendar.UTCOnlyTimeZoneDatabase, которая обрабатывает только даты и время «Etc/UTC» и возвращает {:error, :utc_only_time_zone_database} для любого другого часового пояса.
Можно также настроить другие базы данных часовых поясов. Вот некоторые доступные варианты и библиотеки:
time_zone_infotztzdata-
zoneinfo— рекомендуется для встроенных устройств
Чтобы использовать их, сначала убедитесь, что она добавлена в качестве зависимости в mix.exs. Затем её можно настроить либо через конфигурацию:
config :elixir, :time_zone_database, Tz.TimeZoneDatabase
или вызвав Calendar.put_time_zone_database/1:
Calendar.put_time_zone_database(Tz.TimeZoneDatabase)
См. правильные имена в инструкциях по установке библиотеки.
Даты и время как снимки
В первом разделе мы описали даты и время как «снимок даты и времени в заданном часовом поясе». Чтобы точно понять, что мы имеем в виду, давайте рассмотрим пример.
Представьте, что кто-то в Польше хочет назначить встречу с кем-то в Бразилии в следующем году. Встреча состоится в 2:30 по польскому времени. В какое время состоится встреча в Бразилии?
Вы можете обратиться к базе данных часовых поясов сегодня, за год до этого, используя API в этом модуле, и он даст вам ответ, который действителен прямо сейчас. Однако этот ответ может быть недействителен в будущем. Почему? Потому что и Бразилия, и Польша могут изменить свои правила часовых поясов, что в конечном итоге повлияет на результат. Например, страна может выбрать введение или отмену «летнего времени», что является процессом, при котором мы переводим часы на один час вперёд или на один час назад один раз в год. В случае изменения правил точное время 2:30 по польскому времени в Бразилии может измениться.
Другими словами, при работе с будущими датами и временем нет гарантии, что полученные результаты всегда будут верными, пока событие не произойдёт. Следовательно, когда вы запрашиваете будущее время, получаемые ответы являются снимком, отражающим текущее состояние правил часовых поясов. Для дат и времени в прошлом это не проблема, потому что правила часовых поясов для прошлых событий не меняются.
Что ещё хуже, может случиться так, что 2:30 по польскому времени вообще не существует или является неоднозначным. Если определённый часовой пояс соблюдает «летнее время», они переведут свои часы вперёд один раз в год. Когда это происходит, целый час не существует. Затем, когда они переводят часы назад, определённый час произойдёт дважды. Итак, если вы хотите назначить встречу, когда происходит это смещение назад, вам нужно будет чётко указать, о каком именно 2:30 идёт речь. Приложениям, чувствительным к дате и времени, необходимо учитывать эти сценарии и правильно сообщать об этом пользователям.
Хорошая новость: Elixir содержит все необходимые инструменты для решения этих проблем. База данных часовых поясов по умолчанию, используемая Elixir, Calendar.UTCOnlyTimeZoneDatabase, работает только с UTC, который не сталкивается с этими проблемами. Как только вы используете правильную базу данных часовых поясов, функции в этом модуле будут обращаться к базе данных и возвращать соответствующую информацию. Например, обратите внимание, как DateTime.new/4 возвращает разные результаты, основанные на описанных в этом разделе сценариях.
Типы
Функции
- add(datetime, amount_to_add, unit \\ :second, time_zone_database \\ Calendar.get_time_zone_database())
Добавляет указанное количество времени к
DateTime.- after?(datetime1, datetime2)
Возвращает true, если первое значение datetime строго позже второго.
- before?(datetime1, datetime2)
Возвращает true, если первое значение datetime строго раньше второго.
- compare(datetime1, datetime2)
Сравнивает две структуры datetime.
- convert(datetime, calendar)
Преобразует заданный
datetimeиз одного календаря в другой.- convert!(datetime, calendar)
Преобразует заданный
datetimeиз одного календаря в другой.- diff(datetime1, datetime2, unit \\ :second)
Вычитает
datetime2изdatetime1.- from_gregorian_seconds(seconds, arg \\ {0, 0}, calendar \\ Calendar.ISO)
Преобразует количество грегорианских секунд в структуру
DateTime.- from_iso8601(string, format_or_calendar \\ Calendar.ISO)
Парсит расширенный формат «Дата и время суток», описанный в ISO 8601:2019.
- from_iso8601(string, calendar, format)
Преобразует в ISO8601, задавая как календарь, так и режим.
- 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.- new(date, time, time_zone \\ "Etc/UTC", time_zone_database \\ Calendar.get_time_zone_database())
Создаёт datetime из структур date и time.
- new!(date, time, time_zone \\ "Etc/UTC", time_zone_database \\ Calendar.get_time_zone_database())
Создаёт datetime из структур date и time, вызывая исключение при ошибках.
- now(time_zone, time_zone_database \\ Calendar.get_time_zone_database())
Возвращает текущее значение datetime в указанной временной зоне.
- now!(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.- shift_zone!(datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database())
Изменяет временную зону
DateTimeили генерирует исключение при ошибках.- to_gregorian_seconds(datetime)
Преобразует структуру
DateTimeв количество грегорианских секунд и микросекунд.- to_iso8601(datetime, format \\ :extended, offset \\ nil)
Преобразует заданное datetime в формат ISO 8601:2019.
- to_naive(datetime)
Преобразует заданный
datetimeвNaiveDateTime.- to_string(datetime)
Преобразует заданный
datetimeв строку в соответствии с его календарём.- to_unix(datetime, unit \\ :second)
Преобразует заданный
datetimeв время Unix.- truncate(datetime, precision)
Возвращает заданное datetime с усечённым полем микросекунд до заданной точности (
:microsecond,:millisecondили:second).- utc_now(calendar_or_time_unit \\ Calendar.ISO)
Возвращает текущее значение datetime в UTC.
- utc_no w(time_unit, calendar)
Возвращает текущее значение datetime в UTC, поддерживая определённый календарь и точность.
t()Source
@type 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())Source
@spec add( Calendar.datetime(), integer(), :day | :hour | :minute | System.time_unit(), Calendar.time_zone_database() ) :: t()
Добавляет указанное количество времени к DateTime.
Принимает amount_to_add в любом unit. unit может быть :day, :hour, :minute, :second или любой дробью секунды из System.time_unit/0. По умолчанию используется :second. Отрицательные значения будут перемещать во времени назад.
Эта функция всегда учитывает единицу измерения, вычисленную согласно Calendar.ISO.
Эта функция использует непрерывное представление времени, игнорируя текущее время и изменения часового пояса. Например, если вы добавите один день, когда есть изменения летнего/зимнего времени, время также изменится вперёд или назад на один час, так что пройдёт ровно 24 часа. Аналогично, добавление нескольких секунд к дате и времени непосредственно перед переходом на летнее время может привести к тому, что текущее время увеличится более чем на час.
Хотя это означает, что функция точна с точки зрения прошедшего времени, её результат может быть вводящим в заблуждение в определённых случаях. Например, если пользователь запрашивает встречу каждый день в 15:00, и вы используете эту функцию для вычисления всех будущих встреч, добавляя день за днём, эта функция может изменить время встречи на 14:00 или 16:00, если есть изменения текущего часового пояса. Вычисление повторяющихся дат и времени в настоящее время не поддерживается стандартной библиотекой Elixir, но доступно с помощью сторонних библиотек.
Примеры
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>
При добавлении 1 дня во время перехода на летнее время, также меняется час:
iex> dt = DateTime.from_naive!(~N[2019-03-31 01:00:00], "Europe/Copenhagen", FakeTimeZoneDatabase) iex> dt |> DateTime.add(1, :day, FakeTimeZoneDatabase) #DateTime<2019-04-01 02:00:00+02:00 CEST Europe/Copenhagen>
Эта операция объединяет точность простого даты и времени с заданной единицей измерения:
iex> result = DateTime.add(~U[2014-10-02 00:29:10Z], 21, :millisecond)
~U[2014-10-02 00:29:10.021Z]
iex> result.microsecond
{21000, 3} after?(datetime1, datetime2)Source
@spec after?(Calendar.datetime(), Calendar.datetime()) :: boolean()
Возвращает true, если первое datetime строго позже второго.
Примеры
iex> DateTime.after?(~U[2022-02-02 11:00:00Z], ~U[2021-01-01 11:00:00Z]) true iex> DateTime.after?(~U[2021-01-01 11:00:00Z], ~U[2021-01-01 11:00:00Z]) false iex> DateTime.after?(~U[2021-01-01 11:00:00Z], ~U[2022-02-02 11:00:00Z]) false
before?(datetime1, datetime2)Source
@spec before?(Calendar.datetime(), Calendar.datetime()) :: boolean()
Возвращает true, если первое datetime строго раньше второго.
Примеры
iex> DateTime.before?(~U[2021-01-01 11:00:00Z], ~U[2022-02-02 11:00:00Z]) true iex> DateTime.before?(~U[2021-01-01 11:00:00Z], ~U[2021-01-01 11:00:00Z]) false iex> DateTime.before?(~U[2022-02-02 11:00:00Z], ~U[2021-01-01 11:00:00Z]) false
compare(datetime1, datetime2)Source
@spec compare(Calendar.datetime(), Calendar.datetime()) :: :lt | :eq | :gt
Сравнивает две структуры datetime.
Возвращает :gt если первое datetime позже второго и :lt в обратном случае. Если два datetime равны, возвращается :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)Source
@spec 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)Source
@spec convert!(Calendar.datetime(), Calendar.calendar()) :: t()
Преобразует заданное datetime из одного календаря в другой.
Если не удаётся однозначно преобразовать между календарями (см. Calendar.compatible_calendars?/2), генерируется ArgumentError.
Примеры
Представьте, что кто-то реализует 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)
%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)Source
@spec diff( Calendar.datetime(), Calendar.datetime(), :day | :hour | :minute | System.time_unit() ) :: integer()
Вычисляет разницу между datetime2 и datetime1.
Результат может быть возвращён в любых :day, :hour, :minute, или любых unit единицах измерения из System.time_unit/0. Единицы измерения определяются согласно Calendar.ISO и по умолчанию равны :second.
Дробные результаты не поддерживаются и усекаются.
Примеры
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
iex> DateTime.diff(dt1, dt2, :hour)
5
iex> DateTime.diff(dt2, dt1, :hour)
-5 from_gregorian_seconds(seconds, arg \\ {0, 0}, calendar \\ Calendar.ISO)Source
@spec from_gregorian_seconds(integer(), Calendar.microsecond(), Calendar.calendar()) :: t()
Преобразует количество григорианских секунд в структуру DateTime.
Возвращаемая DateTime будет иметь часовой пояс UTC. Если вам нужен другой часовой пояс, используйте DateTime.shift_zone/3.
Примеры
iex> DateTime.from_gregorian_seconds(1)
~U[0000-01-01 00:00:01Z]
iex> DateTime.from_gregorian_seconds(63_755_511_991, {5000, 3})
~U[2020-05-01 00:26:31.005Z]
iex> DateTime.from_gregorian_seconds(-1)
~U[-0001-12-31 23:59:59Z] from_iso8601(string, format_or_calendar \\ Calendar.ISO)Source
@spec from_iso8601(String.t(), Calendar.calendar() | :extended | :basic) ::
{:ok, t(), Calendar.utc_offset()} | {:error, atom()} Парсит расширенный формат "Дата и время суток", описанный в ISO 8601:2019.
Поскольку ISO 8601 не включает правильный часовой пояс, заданная строка будет преобразована в UTC, а её смещение во времени в секундах будет возвращено как часть этой функции. Поэтому информация о смещении должна быть в строке.
Как указано в стандарте, разделитель "T" может быть опущен при необходимости, так как в этой функции нет неоднозначности.
Обратите внимание, что добавочные секунды не поддерживаются встроенным 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> {:ok, datetime, 9000} = DateTime.from_iso8601("20150123T235007.123+0230", :basic)
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_iso8601(string, calendar, format)Source
@spec from_iso8601(String.t(), Calendar.calendar(), :extended | :basic) ::
{:ok, t(), Calendar.utc_offset()} | {:error, atom()} Преобразование в ISO8601, указав календарь и режим.
См. from_iso8601/2 для получения дополнительной информации.
Примеры
iex> {:ok, datetime, 9000} = DateTime.from_iso8601("2015-01-23T23:50:07,123+02:30", Calendar.ISO, :extended)
iex> datetime
~U[2015-01-23 21:20:07.123Z]
iex> {:ok, datetime, 9000} = DateTime.from_iso8601("20150123T235007.123+0230", Calendar.ISO, :basic)
iex> datetime
~U[2015-01-23 21:20:07.123Z] from_naive(naive_datetime, time_zone, time_zone_database \\ Calendar.get_time_zone_database())Source
@spec from_naive(
Calendar.naive_datetime(),
Calendar.time_zone(),
Calendar.time_zone_database()
) ::
{:ok, t()}
| {:ambiguous, first_datetime :: t(), second_datetime :: 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())Source
@spec 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)Source
@spec from_unix(integer(), :native | System.time_unit(), Calendar.calendar()) ::
{:ok, t()} | {:error, atom()} Преобразует заданное время Unix в DateTime.
Целое число может быть задано в различных единицах в соответствии с System.convert_time_unit/3, и оно будет преобразовано во внутренние микросекунды. Поддерживается до 253402300799 секунд.
Временные метки 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]
iex> {:ok, datetime} = DateTime.from_unix(253_402_300_799)
iex> datetime
~U[9999-12-31 23:59:59Z]
iex> {:error, :invalid_unix_time} = DateTime.from_unix(253_402_300_800)
Единица также может быть целым числом, как в 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 до -377705116800 секунд:
iex> {:ok, datetime} = DateTime.from_unix(-377_705_116_800)
iex> datetime
~U[-9999-01-01 00:00:00Z]
iex> {:error, :invalid_unix_time} = DateTime.from_unix(-377_705_116_801) from_unix!(integer, unit \\ :second, calendar \\ Calendar.ISO)Source
@spec from_unix!(integer(), :native | System.time_unit(), Calendar.calendar()) :: t()
Преобразует заданное время Unix в DateTime.
Целое число может быть задано в различных единицах в соответствии с System.convert_time_unit/3, и оно будет преобразовано во внутренние микросекунды.
Временные метки 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]
new(date, time, time_zone \\ "Etc/UTC", time_zone_database \\ Calendar.get_time_zone_database())Source
@spec new(Date.t(), Time.t(), Calendar.time_zone(), Calendar.time_zone_database()) ::
{:ok, t()}
| {:ambiguous, first_datetime :: t(), second_datetime :: t()}
| {:gap, t(), t()}
| {:error,
:incompatible_calendars
| :time_zone_not_found
| :utc_only_time_zone_database} Создаёт дату и время из структур даты и времени.
Ожидается часовой пояс для помещения DateTime. Если часовой пояс не передан, он по умолчанию будет "Etc/UTC", что всегда успешно. В противном случае, DateTime проверяется по базе данных часовых поясов, указанной как time_zone_database. См. раздел «База данных часовых поясов» в документации модуля.
Примеры
iex> DateTime.new(~D[2016-05-24], ~T[13:26:08.003], "Etc/UTC")
{:ok, ~U[2016-05-24 13:26:08.003Z]}
Когда дата и время неоднозначны (например, при переходе с летнего на зимнее время), возвращаются две возможные действительные даты и время в кортеже. Первая дата и время — это также та, которая появляется раньше хронологически, а вторая — та, которая появляется позже.
iex> {:ambiguous, first_dt, second_dt} = DateTime.new(~D[2018-10-28], ~T[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.new(~D[2019-03-31], ~T[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.new(~D[2018-07-28], ~T[12:30:00], "Europe/Copenhagen", FakeTimeZoneDatabase)
iex> datetime
#DateTime<2018-07-28 12:30:00+02:00 CEST Europe/Copenhagen> new!(date, time, time_zone \\ "Etc/UTC", time_zone_database \\ Calendar.get_time_zone_database())Source
@spec new!(Date.t(), Time.t(), Calendar.time_zone(), Calendar.time_zone_database()) :: t()
Создаёт дату и время из структур даты и времени, вызывая исключение при ошибках.
Ожидается часовой пояс для помещения DateTime. Если часовой пояс не передан, он по умолчанию будет "Etc/UTC", что всегда успешно. В противном случае, DateTime проверяется по базе данных часовых поясов, указанной как time_zone_database. См. раздел «База данных часовых поясов» в документации модуля.
Примеры
iex> DateTime.new!(~D[2016-05-24], ~T[13:26:08.003], "Etc/UTC") ~U[2016-05-24 13:26:08.003Z]
Когда дата и время неоднозначны (например, при переходе с летнего на зимнее время), будет вызвано исключение.
iex> DateTime.new!(~D[2018-10-28], ~T[02:30:00], "Europe/Copenhagen", FakeTimeZoneDatabase) ** (ArgumentError) cannot build datetime with ~D[2018-10-28] and ~T[02:30:00] because such instant is ambiguous in time zone Europe/Copenhagen as there is an overlap between #DateTime<2018-10-28 02:30:00+02:00 CEST Europe/Copenhagen> and #DateTime<2018-10-28 02:30:00+01:00 CET Europe/Copenhagen>
Когда существует разрыв во времени отображения (например, весной, когда время переводят вперёд), будет вызвано исключение.
iex> DateTime.new!(~D[2019-03-31], ~T[02:30:00], "Europe/Copenhagen", FakeTimeZoneDatabase) ** (ArgumentError) cannot build datetime with ~D[2019-03-31] and ~T[02:30:00] because such instant does not exist in time zone Europe/Copenhagen as there is a gap between #DateTime<2019-03-31 01:59:59.999999+01:00 CET Europe/Copenhagen> and #DateTime<2019-03-31 03:00:00+02:00 CEST Europe/Copenhagen>
В большинстве случаев для определённой даты и времени в определённом часовом поясе существует одна и только одна действительная дата и время.
iex> datetime = DateTime.new!(~D[2018-07-28], ~T[12:30:00], "Europe/Copenhagen", FakeTimeZoneDatabase) iex> datetime #DateTime<2018-07-28 12:30:00+02:00 CEST Europe/Copenhagen>
now(time_zone, time_zone_database \\ Calendar.get_time_zone_database())Source
@spec now(Calendar.time_zone(), Calendar.time_zone_database()) ::
{:ok, t()} | {:error, :time_zone_not_found | :utc_only_time_zone_database} Возвращает текущую дату и время в заданном часовом поясе.
По умолчанию используется значение часового пояса по умолчанию, возвращаемое 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())Source
@spec 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())Source
@spec 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())Source
@spec 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(datetime)Source
@spec to_date(Calendar.datetime()) :: Date.t()
Так как 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_gregorian_seconds(datetime)Source
@spec to_gregorian_seconds(Calendar.datetime()) :: {integer(), non_neg_integer()} Преобразует структуру DateTime в количество грегорианских секунд и микросекунд.
Примеры
iex> dt = %DateTime{year: 0000, month: 1, day: 1, zone_abbr: "UTC",
...> hour: 0, minute: 0, second: 1, microsecond: {0, 0},
...> utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> DateTime.to_gregorian_seconds(dt)
{1, 0}
iex> dt = %DateTime{year: 2020, month: 5, day: 1, zone_abbr: "UTC",
...> hour: 0, minute: 26, second: 31, microsecond: {5000, 0},
...> utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> DateTime.to_gregorian_seconds(dt)
{63_755_511_991, 5000}
iex> dt = %DateTime{year: 2020, month: 5, day: 1, zone_abbr: "CET",
...> hour: 1, minute: 26, second: 31, microsecond: {5000, 0},
...> utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> DateTime.to_gregorian_seconds(dt)
{63_755_511_991, 5000} to_iso8601(datetime, format \\ :extended, offset \\ nil)Source
@spec to_iso8601(Calendar.datetime(), :basic | :extended, nil | integer()) :: String.t()
Преобразует заданную дату и время в формат ISO 8601:2019.
По умолчанию, 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"
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, 3600)
"2000-03-01T04:00:07+01: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, :extended, 0)
"2000-03-01T03:00:07+00:00"
iex> dt = %DateTime{year: 2000, month: 3, day: 01, zone_abbr: "UTC",
...> hour: 03, minute: 0, second: 7, microsecond: {0, 0},
...> utc_offset: 0, std_offset: 0, time_zone: "Etc/UTC"}
iex> DateTime.to_iso8601(dt, :extended, 0)
"2000-03-01T03:00:07Z"
iex> {:ok, dt, offset} = DateTime.from_iso8601("2000-03-01T03:00:07Z")
iex> "2000-03-01T03:00:07Z" = DateTime.to_iso8601(dt, :extended, offset) to_naive(datetime)Source
@spec 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)Source
@spec 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(datetime)Source
@spec to_time(Calendar.datetime()) :: Time.t()
Так как 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)Source
@spec 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)Source
@spec 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_or_time_unit \\ Calendar.ISO)Source
@spec utc_now(Calendar.calendar() | :native | :microsecond | :millisecond | :second) :: t()
Возвращает текущую дату и время в UTC.
Если вам нужно текущее время в секундах Unix, используйте System.os_time/1 вместо этого.
Вы также можете передать единицу измерения времени, чтобы автоматически обрезать полученную дату и время. Это доступно начиная с версии v1.15.0.
Примеры
iex> datetime = DateTime.utc_now()
iex> datetime.time_zone
"Etc/UTC"
iex> datetime = DateTime.utc_now(:second)
iex> datetime.microsecond
{0, 0} utc_now(time_unit, calendar)Source
@spec utc_now(:native | :microsecond | :millisecond | :second, Calendar.calendar()) :: t()
Возвращает текущую дату и время в UTC, поддерживая конкретный календарь и точность.
Если вам нужно текущее время в секундах Unix, используйте System.os_time/1 вместо этого.
Примеры
iex> datetime = DateTime.utc_now(:microsecond, Calendar.ISO)
iex> datetime.time_zone
"Etc/UTC"
iex> datetime = DateTime.utc_now(:second, Calendar.ISO)
iex> datetime.microsecond
{0, 0}
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.15.4/DateTime.html
