Вычисления времени

Эти функции выполняют календарные вычисления, используя значения времени (см. Время суток). Как и для любого значения времени, значение nil для любого из их аргументов-значений времени обозначает текущее системное время, а конечное число обозначает количество секунд, прошедших с начала эпохи.

Функция: time-less-p t1 t2

Возвращает t, если значение времени t1 меньше значения времени t2.

Функция: time-equal-p t1 t2

Возвращает t, если значения времени t1 и t2 равны. Результатом будет nil, если любой из аргументов является NaN. Для сравнения аргумент nil представляет текущее время с бесконечным разрешением, поэтому эта функция возвращает nil, если один аргумент равен nil, а другой — нет. Таким образом, вызывающий код может использовать nil для представления неизвестного значения времени, которое не равно ни одной отметке времени.

Функция: time-subtract t1 t2

Возвращает разность времени t1 − t2 между двумя значениями времени в виде временной метки Lisp. Результат является точным, а разрешение его часов не хуже, чем у аргумента с худшим разрешением. Если разность нужна в единицах прошедших секунд, её можно преобразовать с помощью time-convert или float-time. См. Преобразование времени.

Функция: time-add t1 t2

Возвращает сумму двух значений времени, используя те же правила преобразования, что и time-subtract. Один из аргументов должен представлять разность времени, а не момент времени, например значение времени, состоящее только из количества прошедших секунд. Вот как прибавить к значению времени заданное количество секунд:

(time-add time seconds)

Функция: time-to-days time-value

Эта функция возвращает количество дней между началом первого года и time-value, исходя из часового пояса по умолчанию. Операционная система ограничивает диапазон значений времени и часового пояса.

Функция: days-to-time days

Эта функция не совсем является обратной к функции time-to-days, поскольку по историческим причинам она использует эпоху Emacs (а не первый год). Чтобы получить обратное преобразование, вычтите (time-to-days 0) из days; в этом случае days-to-time может вернуть nil, если days отрицательно.

Функция: time-to-day-in-year time-value

Возвращает номер дня в году, соответствующий time-value, исходя из часового пояса по умолчанию. Операционная система ограничивает диапазон значений времени и часового пояса.

Функция: date-leap-year-p year

Эта функция возвращает t, если year является високосным годом.

Функция: date-days-in-month year month

Возвращает количество дней в месяце month года year. Например, в феврале 2020 года 29 дней.

Функция: date-ordinal-to-time year ordinal

Возвращает дату, соответствующую дню ordinal года year, в виде декодированной структуры времени. Например, 120-й день 2004 года — это 29 апреля.

Функция: seconds-to-string delay &optional readable abbrev precision

Возвращает строку с описанием заданной задержки delay (в секундах). По умолчанию эта функция форматирует возвращаемую строку как число с плавающей точкой в единицах, выбранных в зависимости от значения delay. Например, задержка в 9861,5 секунды даст ‘2,74 ч’, поскольку значение delay больше 1 часа, но меньше 1 дня. Форматирование вывода можно дополнительно настроить с помощью необязательных аргументов, если необязательный аргумент readable не равен nil. Если значение readable равно expanded, возвращаемая строка будет описывать delay с помощью двух единиц измерения; например, задержка в 9861,5 секунды при значении символа expanded для readable даст ‘2 часа 44 минуты’, а если readable равно t, функция вернёт ‘3 часа’. Необязательный аргумент abbrev, если он не равен nil, означает, что единицы измерения нужно сокращать: использовать ‘ч’ вместо ‘часов’, ‘м’ вместо ‘минут’ и т. д. Если precision — целое число, функция округляет значение наименьшей из выводимых единиц до указанного количества цифр после десятичной запятой; например, для 9861,5 при значении precision, равном 3, результатом будет ‘2,739 часа’. Если precision — неотрицательное число с плавающей точкой меньше 1, округление выполняется до этого значения.