Parsing and Formatting Times — Elisp

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

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

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

Функция: parse-time-string строка

Эта функция анализирует строку времени строка в список следующего вида:

(sec min hour day mon year dow dst tz)

Формат этого списка такой же, как и тот, который принимает decode-time (см. Преобразование времени), и там он описан более подробно. Любой dst элемент, который не может быть определен из входных данных, устанавливается в -1, а любой другой неизвестный элемент устанавливается в nil. Аргумент строка должен напоминать строку RFC 822 (или более позднюю) или ISO 8601, например, «Пт, 25 мар 2016 16:24:56 +0100» или «1998-09-12T12:21:54-0200», но эта функция также попытается проанализировать менее хорошо сформированные строки времени.

Функция: iso8601-parse строка: Для более строгой функции (которая выдаст ошибку при неверном вводе), можно использовать эту функцию вместо нее. Она может анализировать все варианты стандарта ISO 8601, поэтому помимо вышеупомянутых форматов, она также анализирует такие вещи, как «1998N45-3» (номер недели) и «1998-245» (порядковый номер дня). Для анализа интервалов времени есть iso8601-parse-duration, а для анализа интервалов времени есть iso8601-parse-interval. Все эти функции возвращают декодированные временные структуры, за исключением последней, которая возвращает три из них (начало, конец и длительность).

Функция: format-time-string строка_формата &опционально часовой пояс

Эта функция преобразует время (или текущее время, если время опущено или nil) в строку в соответствии со строкой_формата. Преобразование использует правило часового пояса пояс, которое по умолчанию равно текущему правилу часового пояса. См. Правила часовых поясов. Аргумент строка_формата может содержать последовательности ‘%’, которые указывают на замену частей времени. Вот таблица того, что означают последовательности ‘%’:

‘%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), предполагая, что недели начинаются с воскресенья.
‘%V’: Обозначает неделю года в соответствии с ISO 8601.
‘%w’: Обозначает числовой день недели (0–6). Воскресенье — день 0.
‘%W’: Обозначает неделю года (01–52), предполагая, что недели начинаются с понедельника.
‘%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 Library) для выполнения большей части работы. Для взаимодействия с этой функцией она сначала преобразует время и пояс во внутренний формат; операционная система ограничивает диапазон значений времени и часовых поясов. Эта функция также кодирует строку_формата с помощью кодировки, указанной в 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" означает, что количество секунд всегда будет выведено, но годы, дни, часы и минуты будут показаны только если они ненулевые.
‘%%’: Выводит буквенный символ ‘%’.

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

Вы также можете указать ширину поля, поставив после ‘%’ число; более короткие числа будут дополнены пробелами. Необязательная точка перед шириной запрашивает нулевое заполнение вместо этого. Например, "%.3Y" может вывести "004 years".