Разбор и форматирование времени

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

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

Эта функция разбирает строку времени string и возвращает соответствующую метку времени Lisp. Аргумент string должен представлять дату и время и иметь одну из форм, распознаваемых parse-time-string (см. ниже). Если в string не указаны сведения о часовом поясе, функция считает время местным; если не указаны месяц, день или время, она использует самые ранние возможные значения. Диапазон значений времени и часового пояса ограничен операционной системой.

Функция: parse-time-string string

Эта функция разбирает строку времени string и преобразует её в структуру декодированного времени (см. Преобразование времени). Аргумент string должен напоминать строку RFC 822 (или более позднюю версию) либо ISO 8601, например «Fri, 25 Mar 2016 16:24:56 +0100» или «1998-09-12T12:21:54-0200», однако функция пытается разбирать и менее корректно сформированные строки времени. Она преобразует неполную строку, например «2024-08-13», в неполную структуру, например ‘(nil nil nil 13 8 2024 nil -1 nil)’, в которой неизвестное значение летнего времени равно −1, а остальные неизвестные значения — nil.

Обратите внимание: в отличие от decode-time (см. Преобразование времени), эта функция не интерпретирует строку времени. В частности, значения летнего времени и часового пояса или смещения относительно UTC, указанные в аргументе string, не влияют на возвращаемые значения даты и времени, а влияют только на два последних элемента возвращаемой структуры декодированного времени. Например, если в string указаны сведения о часовом поясе, структура декодированного времени будет содержать эти сведения; в противном случае элемент часового пояса в возвращаемом значении будет равен nil. Иными словами, эта функция просто разбирает текстовое представление даты и времени на отдельные числовые значения и не учитывает, является ли входное время местным или временем UTC.

Если программа на Lisp передаёт возвращаемое этой функцией значение другому API, связанному со временем, она должна убедиться, что элементы nil структуры декодированного времени интерпретируются правильно. В частности, отсутствие сведений о часовом поясе должно трактоваться как время UTC или местное время в соответствии с потребностями вызывающей программы.

Функция: iso8601-parse string

Для более строгого разбора (при котором некорректные входные данные вызывают ошибку) программы на Lisp могут использовать эту функцию. Она разбирает все варианты стандарта ISO 8601, поэтому, помимо форматов, упомянутых выше, она также разбирает строки вроде «1998W45-3» (номер недели) и «1998-245» (порядковый номер дня). Для разбора длительностей используется iso8601-parse-duration, а для разбора интервалов — iso8601-parse-interval. Все эти функции возвращают структуры декодированного времени, кроме последней, которая возвращает три такие структуры (начало, конец и длительность). Как и parse-time-string, эта функция не интерпретирует строку времени. В частности, указатель часового пояса или смещение относительно UTC, содержащиеся в аргументе string, не влияют на возвращаемые значения даты и времени, а влияют только на два последних элемента возвращаемой структуры декодированного времени. Стандарт ISO 8601 предписывает считать местным временем строки даты и времени, не содержащие сведений об отношении к UTC, однако эта функция так не делает, поскольку не интерпретирует значения времени. Например, если в string указаны сведения о часовом поясе, структура декодированного времени будет содержать эти сведения; в противном случае элемент часового пояса в возвращаемом значении будет равен nil. Иными словами, эта функция просто разбирает текстовое представление даты и времени на отдельные числовые значения и не учитывает, является ли входное время местным или временем UTC.

Функция: iso8601-parse-duration string

Эта функция разбирает строку string, представляющую длительность времени в формате ISO 8601, и возвращает структуру декодированного времени.

Функция: iso8601-parse-interval string

Эта функция разбирает строку string, представляющую интервал времени в формате ISO 8601, и возвращает три структуры декодированного времени, представляющие начало, конец и длительность интервала.

Функция: format-time-string format-string &optional time zone

Эта функция преобразует time (которое должно быть меткой времени Lisp; если time не указано или равно nil, используется текущее время) в строку согласно format-string. При преобразовании используется правило часового пояса zone, по умолчанию — текущее правило часового пояса. См. Правила часовых поясов. Аргумент format-string может содержать последовательности «%», указывающие, какие части времени следует подставить. Ниже приведена таблица значений последовательностей «%»:

‘%a’

Сокращённое название дня недели.

‘%A’

Полное название дня недели.

‘%b’

Сокращённое название месяца.

‘%B’

Полное название месяца.

‘%c’

Синоним «%x %X».

‘%C’

Век, то есть год, делённый на 100 с усечением в сторону нуля. Ширина поля по умолчанию — 2.

‘%d’

День месяца, дополненный нулями слева.

‘%D’

Синоним «%m/%d/%y».

‘%e’

День месяца, дополненный пробелами слева.

‘%F’

Формат даты ISO 8601, аналогичный «%+4Y-%m-%d», за исключением того, что любые флаги или ширина поля переопределяют «+» и (после вычитания 6) «4».

‘%g’

Год без указания века (00–99), соответствующий текущему номеру недели ISO. Недели ISO начинаются в понедельник и заканчиваются в воскресенье. Если неделя ISO начинается в одном году, а заканчивается в другом, правила, определяющие, какой год выдаст «%g», сложны и здесь не описываются; однако в общем случае, если большая часть дней недели приходится на год её окончания, «%g» выдаст этот год.

‘%G’

Год с указанием века, соответствующий текущему номеру недели ISO.

‘%h’

Синоним «%b».

‘%H’

Час (00–23).

‘%I’

Час (01–12).

‘%j’

День года (001–366).

‘%k’

Час (0–23), дополненный пробелами слева.

‘%l’

Час (1–12), дополненный пробелами слева.

‘%m’

Месяц (01–12).

‘%M’

Минута (00–59).

‘%n’

Символ новой строки.

‘%N’

Наносекунды (000000000–999999999). Чтобы вывести меньше цифр, используйте «%3N» для миллисекунд, «%6N» для микросекунд и т. д. Лишние цифры отбрасываются без округления.

‘%p’

«AM» или «PM» в зависимости от времени.

‘%q’

Календарный квартал (1–4).

‘%r’

Синоним «%I:%M:%S %p».

‘%R’

Синоним «%H:%M».

‘%s’

Целое число секунд, прошедших с начала эпохи.

‘%S’

Секунда (00–59 или 00–60 на платформах, поддерживающих високосные секунды).

‘%t’

Символ табуляции.

‘%T’

Синоним «%H:%M:%S».

‘%u’

Числовой день недели (1–7). Понедельник — день 1.

‘%U’

Неделя года (01–52), если считать, что неделя начинается в воскресенье. Если 1 января приходится не на воскресенье, первая неполная неделя считается нулевой.

‘%V’

Неделя года согласно ISO 8601. Обратите внимание: в отличие от «%U» и «%W», номер недели по ISO 8601 не сбрасывается до 1 января, а сохраняет свой последний номер.

‘%w’

Числовой день недели (0–6). Воскресенье — день 0.

‘%W’

Неделя года (01–52), если считать, что неделя начинается в понедельник. Если 1 января приходится не на понедельник, первая неполная неделя считается нулевой.

‘%x’

Значение зависит от локали. В локали по умолчанию (с именем «C») эквивалентно «%D».

‘%X’

Значение зависит от локали. В локали по умолчанию (с именем «C») эквивалентно «%T».

‘%y’

Год без указания века (00–99).

‘%Y’

Год с указанием века.

‘%Z’

Аббревиатура часового пояса (например, «EST»).

‘%z’

Числовое смещение часового пояса. Перед «z» может стоять одна, две или три двоеточия; если обычная последовательность «%z» выводит «-0500», то «%:z» выводит «-05:00», «%::z» выводит «-05:00:00», а «%:::z» действует как «%::z», но удаляет завершающие фрагменты «:00», поэтому в том же примере выводит «-05».

‘%%’

Один символ «%».

Сразу после «%» может стоять один или несколько символов флагов. «0» дополняет значение нулями, «+» дополняет значение нулями и также ставит «+» перед неотрицательными номерами года, состоящими более чем из четырёх цифр, «_» дополняет значение пробелами, «-» отключает дополнение, «^» переводит буквы в верхний регистр, а «#» меняет регистр букв на противоположный.

Для любой из этих последовательностей «%» также можно указать ширину поля и тип дополнения. Это работает так же, как в printf: ширина поля задаётся цифрами в последовательности «%» после всех флагов. Например, «%S» задаёт число секунд с начала минуты; «%03S» означает дополнить это значение нулями до 3 позиций, а «%_3S» — пробелами до 3 позиций. Обычная последовательность «%3S» дополняет значение нулями, поскольку именно так «%S» обычно дополняет его до двух позиций.

Символы «E» и «O», используемые после любых флагов и ширины поля в последовательности «%», выступают в роли модификаторов. «E» указывает использовать альтернативный вариант даты и времени для текущей локали. Например, в японской локали %Ex может выдать формат даты, основанный на периодах правления японских императоров. «E» допускается в последовательностях «%Ec», «%EC», «%Ex», «%EX», «%Ey» и «%EY».

«O» указывает использовать альтернативное представление чисел для текущей локали вместо обычных десятичных цифр. Этот модификатор допускается с большинством букв, соответствующих числовому выводу.

Для отладки программ нераспознанные последовательности «%» выводятся без изменений. Программам не следует полагаться на это поведение, поскольку в будущих версиях Emacs могут распознаваться новые последовательности «%» в качестве расширений.

Для выполнения большей части работы эта функция использует функцию библиотеки C strftime (см. Форматирование календарного времени в Справочном руководстве библиотеки GNU C). Чтобы взаимодействовать с этой функцией, сначала она преобразует time и zone во внутреннее представление; диапазон значений времени и часового пояса ограничен операционной системой. Эта функция также кодирует format-string с помощью кодировки, заданной в locale-coding-system (см. Локали); после того как strftime возвращает результирующую строку, эта функция декодирует её с помощью той же кодировки.

Функция: format-seconds format-string seconds

Эта функция преобразует аргумент seconds в строку, содержащую годы, дни, часы и т. д., согласно format-string. Аргумент format-string может содержать последовательности «%», управляющие преобразованием. Ниже приведена таблица значений последовательностей «%»:

‘%y’

‘%Y’

Целое число лет по 365 дней.

‘%d’

‘%D’

Целое число дней.

‘%h’

‘%H’

Целое число часов.

‘%m’

‘%M’

Целое число минут.

‘%s’

‘%S’

Количество секунд. Если используется необязательный параметр «,», значение выводится как число с плавающей точкой, а число после «,» задаёт количество десятичных знаков. «%,2s» означает «использовать два десятичных знака».

‘%z’

Непечатаемый управляющий флаг. При его использовании остальные спецификаторы должны задаваться в порядке убывания величины: годы перед днями, часы перед минутами и т. д. В результирующую строку не выводится ничего левее «%z», пока не встретится первое ненулевое значение. Например, формат по умолчанию, используемый emacs-uptime (см. emacs-uptime), "%Y, %D, %H, %M, %z%S" означает, что число секунд выводится всегда, а годы, дни, часы и минуты отображаются только в том случае, если они ненулевые.

‘%x’

Непечатаемый управляющий флаг, работающий аналогично «%z», но подавляющий вывод завершающих элементов времени с нулевым значением.

‘%%’

Выводит символ «%».

Последовательности формата в верхнем регистре выводят единицы измерения вместе с числами, а в нижнем регистре — только числа.

Ширину поля также можно указать, поставив число после «%»; более короткие числа будут дополнены пробелами. Если перед шириной поставить точку, значение будет дополнено нулями. Например, "%.3Y" может выдать "004 years".