Spec-Zone.ru › Elixir 1.3

DateTime

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

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

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

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

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

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

Обзор

Типы

t()

Функции

from_unix(целое число, единица \\ :секунды)

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

from_unix!(целое число, единица \\ :секунды)

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

precision_for_unit(единица)
to_date(date_time)

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

to_iso8601(dt)

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

to_naive(date_time)

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

to_string(dt)

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

to_time(date_time)

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

to_unix(datetime, единица \\ :секунды)

Преобразует заданную 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}

Функции

from_unix(целое число, единица \\ :секунды) 

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

Преобразует заданное время 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, :microseconds)
{: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:

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!(целое число, единица \\ :секунды) 

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, :microseconds)
%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.

precision_for_unit(единица)

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

to_iso8601(DateTime.t) :: String.t

Преобразует заданную дату и время в ISO8601.

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

ПРЕДУПРЕЖДЕНИЕ: ISO8601 не содержит часового пояса ни его сокращения, что означает потерю информации при преобразовании в этот формат. Также по этой причине этот модуль не предоставляет функцию from_iso8601/1, так как невозможно построить правильную DateTime только из информации в строке ISO8601.

Примеры

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

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, единица \\ :секунды) 

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.3.4/DateTime.html

Spec-Zone.ru

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