Spec-Zone.ru › Elixir 1.5

DateTime

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

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

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

Функции в этом модуле работают со структурой DateTime, а также с любой структурой, содержащей те же поля, что и структура DateTime. Такие функции ожидают Calendar.datetime/0 в своих типовдекларациях (вместо t/0).

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

Где мои функции?

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

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

Резюме

Типы

t()

Функции

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)

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

from_naive!(naive_datetime, time_zone)

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

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

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

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

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

to_date(date_time)

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

to_iso8601(datetime, format \\ :extended)

Преобразует заданный datetime в формат ISO 8601:2004

to_naive(date_time)

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

to_string(datetime)

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

to_time(date_time)

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

to_unix(datetime, unit \\ :second)

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

utc_now(calendar \\ Calendar.ISO)

Возвращает текущее datetime в UTC

Типы

t() 

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()}

Функции

compare(datetime1, datetime2) 

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

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

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

Примеры 

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() |
  no_return()

Преобразует заданный 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)

Вычисляет разницу между 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.

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

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

Представления времени с пониженной точностью не поддерживаются.

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

Примеры 

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

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

iex> {:ok, datetime, 9000} = DateTime.from_iso8601("2015-01-23T23:50:07,123+02:30")
iex> datetime
#DateTime<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-23 23:50:07A")
{: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}
iex> DateTime.from_iso8601("2015-01-23T23:50:07.123-00:60")
{:error, :invalid_format}

from_naive(naive_datetime, time_zone) 

from_naive(NaiveDateTime.t(), Calendar.time_zone()) :: {:ok, t()}

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

Требуется часовой пояс для размещения NaiveDateTime. В настоящее время поддерживается только «Etc/UTC».

Примеры 

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

from_naive!(naive_datetime, time_zone) 

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

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

Требуется часовой пояс для размещения NaiveDateTime. В настоящее время поддерживается только «Etc/UTC».

Примеры 

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

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(1464096368)
iex> datetime
#DateTime<2016-05-24 13:26:08Z>

iex> {:ok, datetime} = DateTime.from_unix(1432560368868569, :microsecond)
iex> datetime
#DateTime<2015-05-25 13:26:08.868569Z>

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

iex> {:ok, datetime} = DateTime.from_unix(143256036886856, 1024)
iex> datetime
#DateTime<6403-03-17 07:05:22.320Z>

Поддерживаются отрицательные 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.

Целое число может быть задано в разных единицах измерения в соответствии с 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)
#DateTime<1970-01-01 00:00:00Z>

iex> DateTime.from_unix!(1464096368)
#DateTime<2016-05-24 13:26:08Z>

iex> DateTime.from_unix!(1432560368868569, :microsecond)
#DateTime<2015-05-25 13:26:08.868569Z>

to_date(date_time) 

to_date(t()) :: 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(date_time) 

to_naive(t()) :: 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"

to_time(date_time) 

to_time(t()) :: 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 time.

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

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

Примеры 

iex> 1464096368 |> 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

utc_now(calendar \\ Calendar.ISO) 

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

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

Примеры 

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

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.5.3/DateTime.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API