Spec-Zone.ru › Elixir 1.4

DateTime

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

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

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

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

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

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

Обзор

Типы

t()

Функции

compare(datetime1, datetime2)

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

from_iso8601(arg1)

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

from_naive(naive_datetime, time_zone)

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

from_naive!(naive_datetime, time_zone)

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

from_unix(integer, unit \\ :second)

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

from_unix!(integer, unit \\ :second)

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

to_date(date_time)

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

to_iso8601(map)

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

to_naive(date_time)

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

to_string(map)

Преобразует заданную дату и время в строку в соответствии с ее календарем

to_time(date_time)

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

to_unix(datetime, unit \\ :second)

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

utc_now()

Возвращает текущую дату и время в 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(DateTime.t(), DateTime.t()) :: :lt | :eq | :gt

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

Возвращает :gt если первая дата и время позже второй и :lt в обратном случае. Если две даты и время равны, возвращается :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

from_iso8601(arg1) 

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

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

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

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

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

Примеры 

iex> DateTime.from_iso8601("2015-01-23T23:50:07Z")
{:ok, %DateTime{calendar: Calendar.ISO, day: 23, hour: 23, microsecond: {0, 0}, minute: 50, month: 1, second: 7, std_offset: 0,
                time_zone: "Etc/UTC", utc_offset: 0, year: 2015, zone_abbr: "UTC"}, 0}
iex> DateTime.from_iso8601("2015-01-23T23:50:07.123+02:30")
{:ok, %DateTime{calendar: Calendar.ISO, day: 23, hour: 21, microsecond: {123000, 3}, minute: 20, month: 1, second: 7, std_offset: 0,
                time_zone: "Etc/UTC", utc_offset: 0, year: 2015, zone_abbr: "UTC"}, 9000}

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, DateTime.t()}

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

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

Примеры 

iex> DateTime.from_naive(~N[2016-05-24 13:26:08.003], "Etc/UTC")
{:ok, %DateTime{calendar: Calendar.ISO, day: 24, hour: 13, microsecond: {3000, 3}, minute: 26,
                month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
                year: 2016, zone_abbr: "UTC"}}

from_naive!(naive_datetime, time_zone) 

from_naive!(non_neg_integer(), :native | System.time_unit()) :: DateTime.t()

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

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

Примеры 

iex> DateTime.from_naive!(~N[2016-05-24 13:26:08.003], "Etc/UTC")
%DateTime{calendar: Calendar.ISO, day: 24, hour: 13, microsecond: {3000, 3}, minute: 26,
          month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
          year: 2016, zone_abbr: "UTC"}

from_unix(integer, unit \\ :second) 

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

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

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

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

Примеры 

iex> DateTime.from_unix(1464096368)
{:ok, %DateTime{calendar: Calendar.ISO, day: 24, hour: 13, microsecond: {0, 0}, minute: 26,
                month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
                year: 2016, zone_abbr: "UTC"}}

iex> DateTime.from_unix(1432560368868569, :microsecond)
{:ok, %DateTime{calendar: Calendar.ISO, day: 25, hour: 13, microsecond: {868569, 6}, minute: 26,
                month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
                year: 2015, zone_abbr: "UTC"}}

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

iex> DateTime.from_unix(1432560368868569, 1024)
{:ok, %DateTime{calendar: Calendar.ISO, day: 23, hour: 22, microsecond: {211914, 3}, minute: 53,
                month: 1, second: 43, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
                year: 46302, zone_abbr: "UTC"}}

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

iex> DateTime.from_unix(-12345678910)
{:ok, %DateTime{calendar: Calendar.ISO, day: 13, hour: 4, microsecond: {0, 0}, minute: 44,
                month: 10, second: 50, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
                year: 1578, zone_abbr: "UTC"}}

Когда в from_unix/2 передаётся время Unix до этого момента, возвращается :error.

from_unix!(integer, unit \\ :second) 

from_unix!(non_neg_integer(), :native | System.time_unit()) :: DateTime.t()

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

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

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

Примеры 

iex> DateTime.from_unix!(1464096368)
%DateTime{calendar: Calendar.ISO, day: 24, hour: 13, microsecond: {0, 0}, minute: 26,
          month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
          year: 2016, zone_abbr: "UTC"}

iex> DateTime.from_unix!(1432560368868569, :microsecond)
%DateTime{calendar: Calendar.ISO, day: 25, hour: 13, microsecond: {868569, 6}, minute: 26,
          month: 5, second: 8, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
          year: 2015, zone_abbr: "UTC"}

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

iex> DateTime.from_unix(-12345678910)
{:ok, %DateTime{calendar: Calendar.ISO, day: 13, hour: 4, microsecond: {0, 0}, minute: 44,
                month: 10, second: 50, std_offset: 0, time_zone: "Etc/UTC", utc_offset: 0,
                year: 1578, zone_abbr: "UTC"}}

При передаче в from_unix!/2 времени Unix до этого момента будет выброшено исключение ArgumentError.

to_date(date_time)

Преобразует 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(map) 

to_iso8601(DateTime.t()) :: String.t()

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

Поддерживает преобразование только дат и времени, которые находятся в календаре 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)
"2000-02-29T23:00:07-04:00"

to_naive(date_time)

Преобразует 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(map) 

to_string(DateTime.t()) :: String.t()

Преобразует заданную дату и время в строку в соответствии с её календарем.

Примеры 

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)

Преобразует 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(DateTime.t(), System.time_unit()) :: non_neg_integer()

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

Ожидается, что 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() 

utc_now() :: DateTime.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.4.5/DateTime.html

Spec-Zone.ru

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