Модуль datetime

Начиная с: 2.10.0

Модуль datetime обеспечивает поддержку типов данных datetime и interval. Создавать значения даты и времени можно через объектный интерфейс или путем разбора строковых значений, соответствующих стандарту ISO-8601.

Ниже приведен список функций, свойств и связанных объектов datetime.

Функции

• datetime.new() — создание объекта типа datetime из таблицы единиц времени
• datetime.now() — создание объекта типа datetime с текущими датой и временем
• datetime.is_datetime() — проверка, является ли указанное значение объектом datetime
• datetime.parse() — преобразование входной строки с информацией о дате и времени в объект datetime
• datetime.interval.is_interval() — проверка, является ли указанное значение объектом interval
• datetime.interval.new() — создание объекта типа interval из таблицы единиц времени

Свойства

• datetime.TZ — Lua-таблица, сопоставляющая названия и аббревиатуры часовых поясов с их индексами и наоборот.

Методы

• datetime_object:add() — изменение существующего объекта datetime путем добавления значений входного аргумента
• datetime_object:format() — преобразование стандартного представления объекта datetime в отформатированную строку
• datetime_object:set() — обновление значений полей в существующем объекте datetime
• datetime_object:sub() — изменение существующего объекта datetime путем вычитания значений входного аргумента
• datetime_object:totable() — преобразование информации из объекта datetime в табличный формат
• interval_object:totable() — преобразование информации из объекта interval в табличный формат

Создание объекта типа datetime из таблицы единиц времени. Описание единиц времени и примеры приведены ниже.

Параметры:

• units (table) — Таблица единиц времени. Если передана пустая таблица или аргументы отсутствуют, создается объект datetime со значениями по умолчанию, соответствующими эпохе Unix: 1970-01-01T00:00:00Z.

Возвращает

объект datetime

Тип возвращаемого значения

cdata

 
tarantool> datetime.new {           >     nsec = 123456789,           >           >     sec = 20,           >     min = 25,           >     hour = 18,           >           >     day = 20,           >     month = 8,           >     year = 2021,           >           >     tzoffset  = 180           > }---- 2021-08-20T18:25:20.123456789+0300...tarantool> datetime.new {           >     nsec = 123456789,           >     sec = 20,           >     min = 25,           >     hour = 18,           >     day = 20,           >     month = 8,           >     year = 2021,           >     tzoffset = 60,           >     tz = 'Europe/Moscow'           > }---- 2021-08-20T18:25:20.123456789 Europe/Moscow...tarantool> datetime.new {           >     day = -1, month = 2, year = 2021,           > }---- 2021-02-28T00:00:00Z...tarantool> datetime.new {           >     timestamp = 1656664205.123, tz = 'Europe/Moscow'           > }---- 2022-07-01T08:30:05.122999906 Europe/Moscow...tarantool> datetime.new {           >     nsec = 123, timestamp = 1656664205, tz = 'Europe/Moscow'           > }---- 2022-07-01T08:30:05.000000123 Europe/Moscow...

Создает объект типа datetime с текущими датой и временем.

Возвращает

объект datetime

Тип возвращаемого значения

cdata

Проверяет, является ли указанное значение объектом datetime.

Параметры:

• value (any) — проверяемое значение

Возвращает

true, если указанное значение является объектом datetime; иначе false

Тип возвращаемого значения

boolean

Преобразует входную строку с информацией о дате и времени в объект datetime. Входная строка должна быть отформатирована в соответствии с одним из следующих стандартов:

• ISO 8601
• RFC 3339
• расширенный strftime — подробности см. в описании format().

По умолчанию поля, которые не указаны, равны соответствующим значениям времени Unix.

Поддержка високосных секунд реализована на базовом уровне, см. раздел високосная секунда.

Параметры:

• input_string (string) — строка с информацией о дате и времени.
• format (string) — индикатор формата input_string. Возможные значения: 'iso8601', 'rfc3339' или строка формата, подобная strptime. Если значение не задано, используется форматирование по умолчанию ("%F %T %Z"). Обратите внимание, что поддерживается только часть возможных форматов ISO 8601 и RFC 3339. Чтобы разобрать неподдерживаемые форматы, можно указать строку формата вручную, используя спецификаторы преобразования и обычные символы.
• tzoffset (number) — смещение часового пояса от UTC в минутах.

Возвращает

объект datetime

Тип возвращаемого значения

cdata

Возвращает

количество разобранных символов

Тип возвращаемого значения

number

Особенности реализации:

• Для форматов с десятичной долей секунды ([1], 5.3.1.4, a) остаток после 9 дробных цифр усекается.

   
  tarantool> datetime.parse('2024-07-31T17:30:00.123456789999', {format = 'iso8601'})---- 2024-07-31T17:30:00.123456789Z- 32...

• Для форматов с десятичной долей часа ([1], 5.3.1.4, c) или минуты ([1], 5.3.1.4, b) доли усекаются до точности секунд. Если требуются доли секунды, необходимо использовать явное представление (формат a).

   
  tarantool> datetime.parse('2024-07-31T17,333333333', {format = 'iso8601'})---- 2024-07-31T17:19:59Z- 23...tarantool> datetime.parse('2024-07-31T17:30.333333333', {format = 'iso8601'})---- 2024-07-31T17:30:19Z- 26...

Пример:

 
tarantool> datetime.parse('1970-01-01T00:00:00Z')---- 1970-01-01T00:00:00Z- 20...tarantool> t = datetime.parse('1970-01-01T00:00:00', {format =           > 'iso8601', tzoffset = 180})---tarantool> t---- 1970-01-01T00:00:00+0300...tarantool> t = datetime.parse('2017-12-27T18:45:32.999999-05:00',           > {format = 'rfc3339'})---tarantool> t---- 2017-12-27T18:45:32.999999-0500...tarantool> T = datetime.parse('Thu Jan 1 03:00:00 1970', {format =           > '%c'})---tarantool> T---- 1970-01-01T03:00:00Z...tarantool> T = datetime.parse('12/31/2020', {format = '%m/%d/%y'})---tarantool> T---- 2020-12-31T00:00:00Z...tarantool> T = datetime.parse('1970-01-01T03:00:00.125000000+0300',           > {format = '%FT%T.%f%z'})---tarantool> T---- 1970-01-01T03:00:00.125+0300...tarantool> dt = datetime.parse('01:01:01 MSK', {format ='%H:%M:%S %Z'})---tarantool> dt.year---- 1970...tarantool> dt.month---- 1...tarantool> dt.wday---- 5...tarantool> dt.tz---- MSK...

Начиная с: 3.2.0

Проверяет, является ли указанное значение объектом interval.

Параметры:

• value (any) — значение для проверки

Возвращает

true, если указанное значение является объектом interval; иначе false

Тип возвращаемого значения

boolean

Примеры:

Если в is_interval() передано числовое значение, возвращается false:

 
tarantool> datetime = require('datetime')---tarantool> datetime.interval.is_interval(123)---- false...

Если в is_interval() передать объект интервала, возвращается true:

 
tarantool> datetime.interval.is_interval(datetime.interval.new())---- true...

Создает объект типа interval из таблицы единиц времени. Описание единиц времени см. в описании единиц, примеры — в примерах ниже.

Параметры:

• input (table) — Таблица с единицами времени и параметрами. Для всех возможных единиц времени значения не ограничены. Если передана пустая таблица или аргументы отсутствуют, создается объект interval со значением по умолчанию 0 seconds.

Возвращает

interval_object

Тип возвращаемого значения

cdata

 
tarantool> datetime.interval.new()---- 0 секунд...tarantool> datetime.interval.new {           >     month = 6, year = 1           > }---- +1 год, 6 месяцев...tarantool> datetime.interval.new {           >     day = -1           > }---- `-1 days`...

Начиная с: 2.11.0

Lua-таблица, которая сопоставляет названия часовых поясов (например, Europe/Moscow) и аббревиатуры часовых поясов (например, MSK) с их индексами и наоборот. См. раздел timezone.

 
tarantool> datetime.TZ['Europe/Moscow']---- 947...tarantool> datetime.TZ[947]---- Europe/Moscow...

Объект datetime.

Изменяет существующий объект datetime, добавляя значения входного аргумента. См. также: interval_arithm. Сложение выполняется с учетом tzdata, если заданы поля tzoffset или tz (см. timezone).

Параметры:

• input (table) — объект интервала или эквивалентная таблица (см. Пример #1)
• adjust (string) — определяет, как округлять дни в месяце после арифметической операции. Возможные значения: none, last, excess (см. Пример #2). По умолчанию none.

Возвращает

datetime_object

Тип возвращаемого значения

cdata

Пример #1:

 
tarantool> dt = datetime.new {           >     day = 26,           >     month = 8,           >     year = 2021,           >     tzoffset  = 180           > }---tarantool> iv = datetime.interval.new {day = 7}---tarantool> dt, iv---- 2021-08-26T00:00:00+0300- +7 daystarantool> dt:add(iv)---- 2021-09-02T00:00:00+0300tarantool> dt:add{ day = 7 }---- 2021-09-09T00:00:00+0300

 
tarantool> dt = datetime.new {           >     day = 29,           >     month = 2,           >     year = 2020           > }---tarantool> dt:add{month = 1, adjust = 'none'}---- 2020-03-29T00:00:00Ztarantool> dt = datetime.new {           >     day = 29, month = 2, year = 2020           > }---tarantool> dt:add{month = 1, adjust = 'last'}---- 2020-03-31T00:00:00Ztarantool> dt = datetime.new {           >     day = 31, month = 1, year = 2020           > }---tarantool> dt:add{month = 1, adjust = 'excess'}---- 2020-03-02T00:00:00Z

Преобразование стандартного представления объекта datetime в отформатированную строку. Спецификации преобразования такие же, как в функции strftime. Дополнительная спецификация для наносекунд — %f, которая также позволяет использовать модификатор для управления точностью вывода дробной части: %5f (см. пример ниже). Если аргументы метода не заданы, используются преобразования по умолчанию: '%FT%T.%f%z' (см. пример ниже).

Параметры:

• input_string (string) — строка, состоящая из нуля или более спецификаций преобразования и обычных символов

Возвращает

строка с отформатированной информацией о дате и времени

Тип возвращаемого значения

string

Пример:

 
tarantool> dt = datetime.new {           >     nsec = 123456789,           >           >     sec = 20,           >     min = 25,           >     hour = 18,           >           >     day = 20,           >     month = 8,           >     year = 2021,           >           >     tzoffset  = 180           > }---tarantool> dt:format('%d.%m.%y %H:%M:%S.%5f')---- 20.08.21 18:25:20.12345tarantool> dt:format()---- 2021-08-20T18:25:20.123456789+0300tarantool> dt:format('%FT%T.%f%z')---- 2021-08-20T18:25:20.123456789+0300

Обновление значений полей в существующем объекте datetime.

Параметры:

• units (table) — таблица единиц времени. Единицы времени такие же, как для функции datetime.new().

Возвращает

обновленный datetime_object

Тип возвращаемого значения

cdata

Пример:

 
tarantool> dt = datetime.new {           >     nsec = 123456789,           >           >     sec = 20,           >     min = 25,           >     hour = 18,           >           >     day = 20,           >     month = 8,           >     year = 2021,           >           >     tzoffset  = 180           > }---tarantool> dt:set {msec = 567}---- 2021-08-20T18:25:20.567+0300tarantool> dt:set {tzoffset = 60}---- 2021-08-20T18:25:20.567+0100

Изменение существующего объекта datetime путем вычитания значений входного аргумента. См. также: interval_arithm. Вычитание выполняется с учетом tzdata, если заданы поля tzoffset или tz (см. timezone).

Параметры:

• input (table) — объект интервала или эквивалентная таблица (см. Пример)
• adjust (string) — определяет, как округлять дни в месяце после арифметической операции. Возможные значения: none, last, excess. По умолчанию none. Логика аналогична методу :add() – см. Пример #2.

Возвращает

datetime_object

Тип возвращаемого значения

cdata

Пример:

 
tarantool> dt = datetime.new {           >     day = 26,           >     month = 8,           >     year = 2021,           >     tzoffset  = 180           > }---tarantool> iv = datetime.interval.new {day = 5}---tarantool> dt, iv---- 2021-08-26T00:00:00+0300- +5 daystarantool> dt:sub(iv)---- 2021-08-21T00:00:00+0300tarantool> dt:sub{ day = 1 }---- 2021-08-20T00:00:00+0300

Преобразование информации из объекта datetime в табличный формат. Результирующая таблица содержит следующие поля:

Возвращает

таблица с параметрами даты и времени

Тип возвращаемого значения

table

Пример:

 
tarantool> dt = datetime.new {           >     sec = 20,           >     min = 25,           >     hour = 18,           >           >     day = 20,           >     month = 8,           >     year = 2021,           >     tz = 'MAGT',           > }---tarantool> dt:totable()---- tz: 'MAGT'  sec: 20 min: 25 yday: 232 day: 20 nsec: 0 isdst: false wday: 6  tzoffset: 600 month: 8 year: 2021 hour: 18

Объект interval.

Преобразование данных из объекта interval в формат таблицы. Результирующая таблица содержит следующие поля:

Возвращает

таблица с параметрами даты и времени

Тип возвращаемого значения

table

Пример:

 
tarantool> iv = datetime.interval.new{month = 1, adjust = 'last'}---tarantool> iv:totable()---- adjust: last  sec: 0 nsec: 0 day: 0 week: 0 hour: 0 month: 1 year: 0 min: 0

Модуль datetime позволяет создавать объекты двух типов: datetime и interval.

Если требуется сдвинуть значения объекта datetime, можно использовать методы-модификаторы, а именно datetime_object:add() или datetime_object:sub(), либо применить интервальную арифметику с помощью перегруженных операторов + (__add) или - (__sub).

Методы datetime_object:add()/datetime_object:sub() изменяют текущий объект, а операторы +/- создают копию объекта как результат операции.

При выполнении интервальной операции каждый из подкомпонентов интервала последовательно вычисляется от наибольшего (year) к наименьшему (nsec):

• year – годы
• month – месяцы
• week – недели
• day – дни
• hour – часы
• min – минуты
• sec – секунды
• nsec – наносекунды

Если результат операции превышает допустимый диапазон для любого из компонентов, возникает исключение.

Объекты datetime и interval могут участвовать в арифметических операциях:

• Сумма двух интервалов — это объект интервала, поля которого являются суммой каждого отдельного компонента операндов.
• Результат вычитания двух интервалов аналогичен: это объект интервала, в котором каждый подкомпонент является результатом вычитания соответствующих полей исходных операндов.
• При сложении объектов datetime и интервала результатом является объект datetime. Сложение выполняется в определённом порядке — от наибольшего компонента (year) к наименьшему (nsec).
• Вычитание двух объектов datetime создаёт объект интервала. Разность двух значений времени вычисляется не как разность секунд эпохи, а как разность всех подкомпонентов, то есть лет, месяцев, дней, часов, минут и секунд.
• Нетипизированный объект таблицы может использоваться в любом контексте, где используются типизированные объекты datetime или интервала, если левый операнд является типизированным объектом с перегруженной операцией + или -.

Матрица допустимых операндов для сложения и типов их результатов:

Матрица допустимых операндов для вычитания и типов их результатов:

Сложение и вычитание объектов datetime выполняются с учётом tzdata, если заданы поля tzoffset или tz:

 
tarantool> datetime.new({tz='MSK'}) - datetime.new({tz='UTC'})---- -180 minutes

Если нужно сравнить значения объектов datetime и interval, можно использовать стандартные операторы сравнения Lua: ==, ~=, >, <, >= и <=. Эти операторы используют перегруженные метаметоды __eq, __lt и __le для сравнения значений.

Поддержка операторов сравнения для объектов interval добавлена начиная с 2.11.0.

Пример 1:

 
tarantool> dt1 = datetime.new({ year = 2010 })---tarantool> dt2 = datetime.new({ year = 2024 })---tarantool> dt1 == dt2---- falsetarantool> dt1 < dt2---- true

Пример 2:

 
tarantool> iv1 = datetime.interval.new({month = 1})---tarantool> iv2 = datetime.interval.new({month = 2})---tarantool> iv1 < iv2---- true

Секунды координации — это периодическая корректировка координированного всемирного времени (UTC) на одну секунду для того, чтобы системное время суток оставалось близким к среднему солнечному времени. Однако скорость вращения Земли меняется в зависимости от климатических и геологических событий, и из-за этого секунды координации UTC распределены нерегулярно и непредсказуемо.

В Tarantool включена база данных часовых поясов, которая помимо файлов описания часовых поясов содержит также файл с данными о секундах координации. Используйте Lua-модуль tarantool, чтобы получить используемую версию tzdata.

Модуль datetime поддерживает секунды координации на базовом уровне:

• Функция datetime.parse() корректно обрабатывает входную строку со значением 60 секунд:

   
  tarantool> datetime.parse('23:12:60', {format ='%H:%M:%S'})---- 1970-01-01T23:13:00Z- 8...

• Функция datetime.new() и метод datetime_object:set() принимают таблицу с ключом sec, равным 60 секундам:

   
  tarantool> datetime.new({ sec = 60 })---- 1970-01-01T00:01:00Z...

Между тем следующие случаи НЕ поддерживаются модулем datetime:

• При использовании функции datetime.new() 60 високосных секунд в ключе sec добавляют дополнительную минуту как обычные секунды, а результат представляется в обычном виде, без високосных секунд:

   
  tarantool> datetime.new({ year = 1998, month = 12, day = 31, hour = 23, min = 59, sec = 60})---- 1999-01-01T00:00:00Z...

• Функция datetime.parse() возвращает ошибку при разборе входной строки с високосной секундой (60 секунд) и форматом, поддерживающим високосные секунды ('rfc3339', 'iso8601'):

   
  tarantool> datetime.parse('1998-12-31T23:59:60Z', {format='rfc3339'})---- error: 'builtin/datetime.lua:885: could not parse  ''1998-12-31T23:59:60Z'''...

Полная поддержка добавлена начиная с версии 2.11.0.

Tarantool использует базу данных часовых поясов (также известную как базу данных Олсона и поддерживаемую IANA) для поддержки часовых поясов. Для получения используемой версии tzdata можно воспользоваться Lua-модулем tarantool.

Каждый объект datetime содержит три поля, связанных с поддержкой часовых поясов: tz, tzoffset и isdst:

• Поле isdst вычисляется с использованием tzindex и атрибутов выбранного часового пояса из базы данных Олсона.

   
  tarantool> require('datetime').parse('2004-06-01T00:00 Europe/Moscow').isdst---- true...

• Поле tz может принимать название или аббревиатуру часового пояса. Название часового пояса — это человекочитаемое имя, основанное на базе данных часовых поясов (Time Zone Database), например, "Europe/Moscow". Аббревиатуры часовых поясов представляют часовые пояса в виде алфавитных аббревиатур, таких как "EST", "WST" и "F". Как названия, так и аббревиатуры часовых поясов доступны через двунаправленный массив datetime.TZ.

• Поле tzoffset вычисляется автоматически с использованием текущего правила Олсона (Olson rule). Это означает, что при заданном названии часового пояса учитывается информация о летнем времени, високосных годах и секундах координации. Тем не менее, полю tzoffset можно задать значение вручную, если подходящий часовой пояс недоступен. Задать значения полей tz и tzoffset можно в datetime.new(), datetime.parse() и datetime_object:set(). Арифметические операции с объектами datetime выполняются с учетом tzdata, если заданы поля tzoffset или tz (см. раздел interval_arithm).

• Поддерживаемый диапазон дат — от -5879610-06-22 до +5879611-07-11.

• В истории были периоды, когда местное среднее время в некоторых часовых поясах использовало смещение, выражаемое не в целых минутах, а в секундах. Например, в Москве до 1918 года использовалось смещение +2 часа 31 минута 19 секунд. См. дамп Olson для этого периода:

   
  $ zdump -c1880,1918 -i Europe/MoscowTZ="Europe/Moscow"- +023017 MMT 1916-07-03 00:01:02 +023119 MMT 1917-07-02 00 +033119 MST 1 1917-12-27 23 +023119 MMT

  Современные правила tzdata не используют такие малые доли, и все часовые пояса отличаются от UTC на величину, кратную минутам, а не секундам. Модуль datetime в Tarantool использует минуты в качестве внутренних единиц для tzoffset. Поэтому возможна некоторая потеря точности при работе с такими старыми временными метками.

• [1] ISO 8601-1:2019: Дата и время — Представления для обмена информацией. Часть 1: Основные правила
• RFC 3339: Дата и время в Интернете: Метки времени
• ISO 8601: Формат даты и времени
• Lua 5.1 Справочное руководство: 5.8 – Средства операционной системы
• Lua Программирование на Lua: 22.1 – Дата и время