Источник DateTime
Реализация datetime с часовым поясом.
Этот datetime можно рассматривать как снимок даты и времени в заданном часовом поясе. Для этого он также включает в себя как смещения UTC, так и стандартные смещения, а также поле сокращения зоны, используемое исключительно для форматирования. Обратите внимание, что будущие datetime не гарантированно существуют, так как часовые пояса могут измениться в любое время в будущем по геополитическим причинам. Дополнительную информацию см. в разделе «Datetime как снимки».
Помните, что сравнения в Elixir с помощью ==/2, >/2, </2 и аналогичных функций структурные и основаны на полях структуры DateTime. Для правильного сравнения datetime используйте функцию compare/2. Наличие функции compare/2 в этом модуле также позволяет использовать функции Enum.min/2 и Enum.max/2 для получения минимальной и максимальной datetime из 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 и вместо этого полагаться на функции, предоставляемые этим модулем, а также на функции сторонних библиотек календарей.
База данных часовых поясов
Многие функции в этом модуле требуют базы данных часовых поясов. База данных часовых поясов — это запись смещений UTC, которые использовались её регионами в разное время в прошлом, используются сейчас и ожидается, что будут использоваться в будущем. Поскольку эти планы могут измениться, её необходимо периодически обновлять.
По умолчанию DateTime использует базу данных часовых поясов по умолчанию, возвращаемую Calendar.get_time_zone_database/0, которая по умолчанию устанавливается на Calendar.UTCOnlyTimeZoneDatabase, которая обрабатывает только datetime «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)
См. правильные имена в инструкциях по установке библиотеки.
Datetime как снимки
В первом разделе мы описали datetime как «снимок даты и времени в заданном часовом поясе». Чтобы точно понять, что мы имеем в виду, давайте рассмотрим пример.
Представьте, что кто-то в Польше хочет назначить встречу с кем-то в Бразилии в следующем году. Встреча состоится в 2:30 утра по польскому времени. В какое время встреча состоится в Бразилии?
Вы можете обратиться к базе данных часовых поясов на сегодняшний день, за год до этого, используя API в этом модуле, и он даст вам ответ, который справедлив прямо сейчас. Однако этот ответ может недействителен в будущем. Почему? Потому что как Бразилия, так и Польша могут изменить правила своего часового пояса, в конечном итоге влияя на результат. Например, страна может выбрать включить или отказаться от «летнего времени», что является процессом, при котором мы корректируем часы на один час вперёд или назад один раз в год. Всякий раз, когда правила меняются, точное время 2:30 по польскому времени в Бразилии может измениться.
Другими словами, при работе с будущими datetime нет гарантии, что полученные результаты всегда будут правильными, до тех пор, пока событие не произойдёт. Таким образом, когда вы запрашиваете будущее время, ответы, которые вы получаете, — это снимок, отражающий текущее состояние правил часовых поясов. Для datetime в прошлом это не проблема, потому что правила часовых поясов не меняются для прошлых событий.
Что ещё хуже, может оказаться, что 2:30 по польскому времени вообще не существует или оно неоднозначно. Если определённый часовой пояс использует «летнее время», они переведут свои часы вперёд один раз в год. Когда это происходит, целый час не существует. Затем, когда они переводят часы назад, определённый час произойдёт дважды. Таким образом, если вы хотите назначить встречу, когда произойдёт это смещение назад, вам нужно будет явно указать, о какой интерпретации 2:30 вы имеете в виду: о той, которая в «летнее время», которая происходит до смещения, или о той, которая в «зимнее время», которая происходит после него. Приложениям, чувствительным к датам и времени, необходимо учитывать эти сценарии и правильно сообщать об этом пользователям.
Хорошая новость: Elixir содержит все необходимые инструменты для решения этих проблем. База данных часовых поясов по умолчанию, используемая Elixir, Calendar.UTCOnlyTimeZoneDatabase, работает только с UTC, который не сталкивается с этими проблемами. После того, как вы загрузите надлежащую базу данных часовых поясов, функции в этом модуле обратятся к базе данных и вернут соответствующую информацию. Например, посмотрите, как DateTime.new/4 возвращает разные результаты в зависимости от сценариев, описанных в этом разделе.
Преобразование между часовыми поясами
Учитывая вышеизложенные предостережения и предполагая, что вы загрузили полную базу данных часовых поясов, вот несколько примеров распространённых смещений между часовыми поясами.
# Local time to UTC new_york = DateTime.from_naive!(~N[2023-06-26T09:30:00], "America/New_York") #=> #DateTime<2023-06-26 09:30:00-04:00 EDT America/New_York> utc = DateTime.shift_zone!(new_york, "Etc/UTC") #=> ~U[2023-06-26 13:30:00Z] # UTC to local time DateTime.shift_zone!(utc, "Europe/Paris") #=> #DateTime<2023-06-26 15:30:00+02:00 CEST Europe/Paris>
Краткое описание
Типы
Функции
- 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())
Возвращает текущую дату и время в предоставленной временной зоне.
- now!(time_zone, time_zone_database \ Calendar.get_time_zone_database())
Возвращает текущую дату и время в предоставленной временной зоне, или генерирует исключение при ошибках.
- shift(datetime, duration, time_zone_database \ Calendar.get_time_zone_database())
Смещает заданное значение
datetimeнаdurationв соответствии с его календарём.- 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)
Преобразует заданную дату и время в формат ISO 8601:2019.
- to_naive(datetime)
Преобразует заданное значение
datetimeвNaiveDateTime.- to_string(datetime)
Преобразует заданное значение
datetimeв строку в соответствии с его календарём.- to_unix(datetime, unit \ :second)
Преобразует заданное значение
datetimeв время Unix.- truncate(datetime, precision)
Возвращает заданную дату и время с микросекундным полем, усечённым до заданной точности (
:microsecond,:millisecondили:second).- utc_now(calendar_or_time_unit \ Calendar.ISO)
Возвращает текущую дату и время по UTC.
- utc_now(time_unit, calendar)
Возвращает текущую дату и время по 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}
Чтобы сдвинуть дату и время на Duration и в соответствии с её базовым календарём, используйте DateTime.shift/3.
after?(datetime1, datetime2)Source
@spec after?(Calendar.datetime(), Calendar.datetime()) :: boolean()
Возвращает true , если первая дата и время строго позже второй.
Примеры
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 , если первая дата и время строго раньше второй.
Примеры
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
Сравнивает две структуры дат и времени.
Возвращает :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)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> DateTime.diff(~U[2024-01-15 10:00:10Z], ~U[2024-01-15 10:00:00Z]) 10
Эта функция также учитывает смещения часовых поясов:
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>
Эта функция принимает любой map или struct, содержащий по крайней мере те же поля, что и 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 из структур date и time.
Ожидается часовой пояс для размещения 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 из структур date и time, генерируя исключение при ошибках.
Ожидается часовой пояс для размещения 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(datetime, duration, time_zone_database \\ Calendar.get_time_zone_database())Source
@spec shift(Calendar.datetime(), Duration.duration(), Calendar.time_zone_database()) :: t()
Смещает заданный datetime на duration согласно его календарю.
Допустимые единицы измерения: :year, :month, :week, :day, :hour, :minute, :second, :microsecond.
Эта операция эквивалентна смещению часового пояса даты и времени (то есть значения, как его увидит человек в этом часовом поясе на своих часах), затем применению смещения часового пояса для преобразования его в UTC и, наконец, вычислению нового часового пояса в случае смещения. Это гарантирует, что shift/3 всегда возвращает допустимую дату и время.
С другой стороны, часовые пояса, которые соблюдают «летнее время» или другие изменения, в летнее/зимнее время будут добавлять/удалять часы из результирующей даты и времени:
dt = DateTime.new!(~D[2019-03-31], ~T[01:00:00], "Europe/Copenhagen") DateTime.shift(dt, hour: 1) #=> #DateTime<2019-03-31 03:00:00+02:00 CEST Europe/Copenhagen> dt = DateTime.new!(~D[2018-11-04], ~T[00:00:00], "America/Los_Angeles") DateTime.shift(dt, hour: 2) #=> #DateTime<2018-11-04 01:00:00-08:00 PST America/Los_Angeles>
В случае, если вы не хотите, чтобы эти изменения происходили автоматически, или хотите отобразить конфликты часовых поясов пользователю, вы можете сместить дату и время как дату и время без часового пояса, а затем использовать from_naive/2:
dt |> NaiveDateTime.shift(duration) |> DateTime.from_naive(dt.time_zone)
При использовании по умолчанию календаря ISO, продолжительности сжимаются и применяются в порядке месяцев, затем секунд и микросекунд:
- при смещении на 1 год и 2 месяца дата фактически смещается на 14 месяцев
- недели, дни и меньшие единицы сжимаются в секунды и микросекунды
При смещении на месяц, дни округляются вниз до ближайшей допустимой даты.
Примеры
iex> DateTime.shift(~U[2016-01-01 00:00:00Z], month: 2)
~U[2016-03-01 00:00:00Z]
iex> DateTime.shift(~U[2016-01-01 00:00:00Z], year: 1, week: 4)
~U[2017-01-29 00:00:00Z]
iex> DateTime.shift(~U[2016-01-01 00:00:00Z], minute: -25)
~U[2015-12-31 23:35:00Z]
iex> DateTime.shift(~U[2016-01-01 00:00:00Z], minute: 5, microsecond: {500, 4})
~U[2016-01-01 00:05:00.0005Z]
# leap years
iex> DateTime.shift(~U[2024-02-29 00:00:00Z], year: 1)
~U[2025-02-28 00:00:00Z]
iex> DateTime.shift(~U[2024-02-29 00:00:00Z], year: 4)
~U[2028-02-29 00:00:00Z]
# rounding down
iex> DateTime.shift(~U[2015-01-31 00:00:00Z], month: 1)
~U[2015-02-28 00:00:00Z] 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» путём передачи :basic параметра.
Также можно дополнительно указать смещение для отформатированной строки. Если не указано, используется смещение в указанном datetime.
Поддерживает преобразование только дат и времени в календаре ISO. Если задан другой календарь, он автоматически преобразуется в 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 в строку согласно его календарю.
К сожалению, нет стандарта, который определяет отображение даты и времени с полной информацией о часовом поясе, поэтому Elixir использует пользовательское (но достаточно общее) представление, которое добавляет аббревиатуру и полное имя часового пояса к дате и времени.
Примеры
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(), :native | 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.
Единица измерения по умолчанию, если не указана, — :native, что приводит к разрешению по умолчанию в микросекундах.
Примеры
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-2024 The Elixir Team
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.18.1/DateTime.html
