Преобразование времени

Эти функции преобразуют значения времени (см. Время суток) в временные метки Lisp или в календарную информацию и обратно.

Многие 32-битные операционные системы ограничены системным временем, содержащим 32 бита информации в компоненте секунд; эти системы обычно обрабатывают только время с 1901-12-13 20:45:52 по 2038-01-19 03:14:07 по всемирному времени. Однако 64-битные и некоторые 32-битные операционные системы имеют более крупные компоненты секунд и могут представлять время в очень далеком прошлом или будущем.

Функции календарного преобразования всегда используют григорианский календарь, даже для дат, предшествующих введению григорианского календаря. Номера лет подсчитывают количество лет, прошедших с года 1 до н.э., и не пропускают ноль, как это делают традиционные григорианские годы; например, номер года -37 представляет григорианский год 38 до н.э.

Функция: time-convert time &optional form

Эта функция преобразует значение времени во временную метку Lisp.

Необязательный аргумент form указывает форму временной метки, которая должна быть возвращена. Если form — символ integer, эта функция возвращает целое число, представляющее количество секунд. Если form — положительное целое число, оно указывает частоту часов, и эта функция возвращает временную метку в виде целочисленной пары (ticks . form).²⁹ Если form — t, эта функция обрабатывает его как положительное целое число, подходящее для представления временной метки; например, она обрабатывается как 1000000000, если time равно nil, а временная метка платформы имеет разрешение в наносекундах. Если form — list, эта функция возвращает целочисленный список (high low micro pico). Хотя опущенный или nil form в настоящее время работает как list, планируется изменить это в будущей версии Emacs, поэтому вызывающие стороны, нуждающиеся во временных метках в виде списков, должны явно передавать list.

Если time бесконечен или является NaN, эта функция сигнализирует об ошибке. В противном случае, если time не может быть представлен точно, преобразование усекает его в сторону минус бесконечности. Когда form равно t, преобразование всегда точное, поэтому усечение не происходит, и возвращаемое разрешение часов не меньше, чем разрешение time. В противоположность этому, float-time может преобразовать любое значение времени Lisp без сигнализации об ошибке, хотя результат может быть неточным. См. Время суток.

Для повышения эффективности эта функция может возвращать значение, которое является eq для time, или которое иначе разделяет структуру с time.

Хотя (time-convert nil nil) эквивалентно (current-time), последнее может быть немного быстрее.

(setq a (time-convert nil t))
⇒ (1564826753904873156 . 1000000000)

(time-convert a 100000)
⇒ (156482675390487 . 100000)

(time-convert a 'integer)
⇒ 1564826753

(time-convert a 'list)
⇒ (23877 23681 904873 156000)

Функция: decode-time &optional time zone form

Эта функция преобразует значение времени в календарную информацию. Если вы не укажете time, она декодирует текущее время, и аналогично zone по умолчанию устанавливается на текущее правило часового пояса. См. Правила часовых поясов. Операционная система ограничивает диапазон значений времени и часового пояса.

Аргумент form управляет формой возвращаемого элемента seconds, как описано ниже. Возвращаемое значение представляет собой список из девяти элементов, как показано ниже:

(seconds minutes hour day month year dow dst utcoff)

Вот что означают элементы:

seconds

Количество секунд, прошедших с начала минуты, с формой, описанной ниже.

minutes

Количество минут, прошедших с начала часа, целое число от 0 до 59.

hour

Час, целое число от 0 до 23.

day

День месяца, целое число от 1 до 31.

month

Месяц года, целое число от 1 до 12.

year

Год, целое число, обычно больше 1900.

dow

День недели, целое число от 0 до 6, где 0 соответствует воскресенью.

dst

t если летнее время действует, nil если оно не действует, и -1, если эта информация недоступна.

utcoff

Целое число, указывающее смещение по всемирному времени в секундах, т.е. количество секунд к востоку от Гринвича.

Элемент seconds представляет собой временную метку Lisp, которая неотрицательна и меньше 61; она меньше 60 за исключением положительных високосных секунд (предполагая, что операционная система поддерживает високосные секунды). Если необязательный аргумент form равен t, seconds использует точность, такую же, как time; если form равен integer, seconds усекается до целого числа. Например, если time — временная метка (1566009571321 . 1000), которая представляет 2019-08-17 02:39:31.321 UTC на типичных системах без високосных секунд, то (decode-time time t t) возвращает ((31321 . 1000) 39 2 17 8 2019 6 nil 0), а (decode-time time t 'integer) возвращает (31 39 2 17 8 2019 6 nil 0). Если form опущен или nil, он в настоящее время по умолчанию равен integer, но это значение по умолчанию может измениться в будущих выпусках Emacs, поэтому вызывающие стороны, требующие конкретной формы, должны указать form.

Примечание для Common Lisp: Common Lisp имеет другое значение для dow и utcoff, а его second — целое число от 0 до 59 включительно.

Для доступа (или изменения) элементов в значении времени можно использовать функции-аксессоры decoded-time-second, decoded-time-minute, decoded-time-hour, decoded-time-day, decoded-time-month, decoded-time-year, decoded-time-weekday, decoded-time-dst и decoded-time-zone.

Например, чтобы увеличить год в декодированном времени, можно сказать:

(setf (decoded-time-year decoded-time)
      (+ (decoded-time-year decoded-time) 4))

См. также следующие функции.

Функция: decoded-time-add time delta

Эта функция принимает структуру декодированного времени и добавляет к ней delta (также структуру декодированного времени). Элементы в delta, которые являются nil, игнорируются.

Например, если вы хотите «то же время следующего месяца», вы можете сказать:

(let ((time (decode-time nil nil t))
      (delta (make-decoded-time :month 2)))
   (encode-time (decoded-time-add time delta)))

Если эта дата не существует (если вы выполняете это 31 января, например), то дата будет сдвигаться назад до тех пор, пока вы не получите действительную дату (это будет 28 или 29 февраля в зависимости от ситуации).

Поля добавляются в порядке от наиболее к наименее значащим, поэтому если происходит описанное выше изменение, это происходит до добавления дней, часов, минут или секунд.

Значения в delta могут быть отрицательными для вычитания значений вместо добавления.

Возвращаемое значение — структура декодированного времени.

Функция: make-decoded-time &key second minute hour day month year dst zone

Возвращает структуру декодированного времени, в которой заполнены только указанные ключевые слова, оставив остальные nil. Например, чтобы получить структуру, представляющую «два месяца», вы можете сказать:

(make-decoded-time :month 2)

Функция: encode-time time &rest obsolescent-arguments

Эта функция преобразует time во временную метку Lisp. Она может служить обратной функцией к decode-time.

Обычно первым аргументом является список (second minute hour day month year ignored dst zone), который указывает декодированное время в стиле decode-time, так что (encode-time (decode-time ...)) работает. Значения этих элементов списка см. в таблице под decode-time.

Как устаревшая соглашение о вызове, эта функция может принимать шесть или более аргументов. Первые шесть аргументов second, minute, hour, day, month и year указывают большинство компонентов декодированного времени. Если аргументов больше шести, последний аргумент используется как zone, а все остальные дополнительные аргументы игнорируются, так что (apply #'encode-time (decode-time ...)) работает. В этой устаревшей соглашении zone по умолчанию устанавливается на текущее правило часового пояса (см. Правила часовых поясов), а dst обрабатывается так, как если бы он был равен -1.

Года с числом меньше 100 не обрабатываются специально. Если вы хотите, чтобы они обозначали годы после 1900 или после 2000, вы должны изменить их сами перед вызовом encode-time. Операционная система ограничивает диапазон значений времени и часового пояса.

Функция encode-time действует как грубая обратная функция к decode-time. Например, вы можете передать результат последней функции первой следующим образом:

(encode-time (decode-time …))

Вы можете выполнить простые арифметические операции с датами, используя значения вне диапазона для seconds, minutes, hour, day и month; например, день 0 означает день, предшествующий данному месяцу.