Эти функции преобразуют значения времени в текстовую строку и обратно. Значения времени представляются либо как метка времени Lisp (см. Время суток), либо как декодированная структура времени (см. Преобразование времени).
Эта функция разбирает строку времени string и возвращает
соответствующую метку времени Lisp. Аргумент string должен представлять
дату-время и должен быть в одной из форм, распознаваемых
parse-time-string (см. ниже). Эта функция предполагает всемирное время,
если в string отсутствует явная информация о часовом поясе,
и предполагает наименьшие значения, если в string отсутствуют месяц, день или время.
Операционная система ограничивает диапазон значений времени и часового пояса.
Эта функция разбирает строку времени string в декодированную структуру времени (см. Преобразование времени). Аргумент string должен напоминать строку RFC 822 (или более позднюю) или ISO 8601, например “Fri, 25 Mar 2016 16:24:56 +0100” или “1998-09-12T12:21:54-0200”, но эта функция будет пытаться разбирать и менее правильные строки времени.
Обратите внимание, что, в отличие от decode-time (см. Преобразование времени), эта
функция не интерпретирует строку времени, и в частности
значения частей, касающихся перехода на летнее время и часового пояса или смещения UTC,
аргумента string не влияют на возвращаемые значения даты и времени,
они влияют только на последние два члена возвращаемой декодированной структуры
времени. Например, если информация о часовом поясе присутствует в
string, декодированная структура времени будет включать её; в противном случае
член, отвечающий за часовой пояс, в возвращаемом значении будет nil.
Иными словами, эта функция просто разбирает текстовое представление даты
и времени на отдельные числовые значения и не заботится о том,
является ли входное время местным или всемирным (UTC).
Если программа на Lisp передаёт возвращаемое значение этой функции другому
API, связанному со временем, она должна убедиться, что члены
декодированной структуры времени, равные nil, интерпретируются правильно,
и в частности отсутствие информации о часовом поясе интерпретируется как UTC
или местное время в соответствии с потребностями вызывающей программы.
Для более строгой функции (которая будет вызывать ошибку при неверных входных данных)
программы на Lisp могут использовать эту функцию вместо неё. Она может разбирать все варианты
стандарта ISO 8601, поэтому в дополнение к форматам, упомянутым выше,
она также разбирает такие вещи, как “1998W45-3” (номер недели) и “1998-245”
(порядковый день года). Для разбора длительностей существует
iso8601-parse-duration, а для разбора интервалов —
iso8601-parse-interval. Все эти функции возвращают декодированные структуры
времени, за исключением последней, которая возвращает три из них
(начало, конец и длительность).
Как и parse-time-string, эта функция не интерпретирует строку
времени, и в частности обозначение часового пояса или смещение UTC, которое является
частью аргумента string, не влияет на возвращаемое значение
даты и времени, оно влияет только на последние два члена возвращаемой
декодированной структуры времени. Стандарт ISO 8601 определяет, что строки даты/времени,
не содержащие информацию об отношении к UTC, считаются относящимися к местному
времени, но эта функция не делает этого, потому что она
не интерпретирует значения времени. Например, если информация о часовом поясе
присутствует в string, декодированная структура времени будет включать
её; в противном случае член, отвечающий за часовой пояс, в возвращаемом значении будет
nil. Иными словами, эта функция просто разбирает текстовое
представление даты и времени на отдельные числовые значения и
не заботится о том, является ли входное время местным или всемирным (UTC).
Эта функция преобразует time (которая должна быть меткой времени Lisp
и по умолчанию равна текущему времени, если time опущена или равна
nil) в строку в соответствии с format-string. При
преобразовании используется правило часового пояса zone, которое по умолчанию
равно текущему правилу часового пояса. См. Правила часовых поясов. Аргумент
format-string может содержать ‘%’-последовательности, которые
указывают на подстановку частей времени. Вот таблица того, что означают
‘%’-последовательности:
Сокращённое название дня недели.
Полное название дня недели.
Сокращённое название месяца.
Полное название месяца.
Синоним ‘%x %X’.
Век, то есть год, делённый на 100, с округлением в сторону нуля. Ширина поля по умолчанию — 2.
День месяца, дополненный нулями.
Синоним ‘%m/%d/%y’.
День месяца, дополненный пробелами.
Формат даты по ISO 8601, который выглядит как ‘%+4Y-%m-%d’, за исключением того, что любые флаги или ширина поля переопределяют ‘+’ и (после вычитания 6) ‘4’.
Год без века (00–99), соответствующий текущему номеру недели по ISO. Недели по ISO начинаются в понедельник и заканчиваются в воскресенье. Если неделя по ISO начинается в одном году и заканчивается в другом, правила, определяющие, какой год выдаст ‘%g’, сложны и не будут здесь описаны; однако, в общем случае, если большинство дней недели приходятся на заканчивающийся год, ‘%g’ выдаст этот год.
Год с веком, соответствующий текущему номеру недели по ISO.
Синоним ‘%b’.
Час (00–23).
Час (01–12).
День года (001–366).
Час (0–23), дополненный пробелами.
Час (1–12), дополненный пробелами.
Месяц (01–12).
Минута (00–59).
Символ новой строки.
Наносекунды (000000000–999999999). Чтобы запросить меньше цифр, используйте ‘%3N’ для миллисекунд, ‘%6N’ для микросекунд и т. д. Любые лишние цифры отбрасываются без округления.
‘AM’ или ‘PM’ в зависимости от ситуации.
Номер квартала календарного года (1–4).
Синоним ‘%I:%M:%S %p’.
Синоним ‘%H:%M’.
Целое число секунд с начала эпохи.
Секунда (00–59 или 00–60 на платформах, поддерживающих високосные секунды).
Символ табуляции.
Синоним ‘%H:%M:%S’.
Числовой день недели (1–7). Понедельник — день 1.
Неделя года (01–52), при условии, что недели начинаются с воскресенья. Если 1 января — не воскресенье, первая неполная неделя имеет номер ноль.
Неделя года по ISO 8601. Обратите внимание, что, в отличие от ‘%U’ и ‘%W’, неделя по ISO 8601 не переходит на 1 января, а сохраняет свой последний номер.
Числовой день недели (0–6). Воскресенье — день 0.
Неделя года (01–52), при условии, что недели начинаются с понедельника. Если 1 января — не понедельник, первая неполная неделя имеет номер ноль.
Имеет значение, зависящее от локали. В локали по умолчанию (с именем ‘C’) эквивалентно ‘%D’.
Имеет значение, зависящее от локали. В локали по умолчанию (с именем ‘C’) эквивалентно ‘%T’.
Год без века (00–99).
Год с веком.
Сокращённое название часового пояса (например, ‘EST’).
Числовое смещение часового пояса. Перед ‘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 результирующей строки
эта функция декодирует строку с использованием той же системы кодирования.
Эта функция преобразует свой аргумент seconds в строку, содержащую годы, дни, часы и т. д., в соответствии с format-string. Аргумент format-string может содержать ‘%’-последовательности, которые управляют преобразованием. Вот таблица того, что означают ‘%’-последовательности:
Целое число лет по 365 дней.
Целое число дней.
Целое число часов.
Целое число минут.
Количество секунд. Если используется необязательный параметр ‘,’, то это число с плавающей запятой, а число после ‘,’ указывает, сколько десятичных знаков использовать. ‘%,2s’ означает «использовать два десятичных знака».
Управляющий флаг без вывода. При его использовании другие спецификаторы должны
указываться в порядке убывания размера, то есть годы перед днями, часы
перед минутами и т. д. В результирующей строке слева от ‘%z’ ничего не
будет выведено, пока не встретится первое ненулевое преобразование.
Например, формат по умолчанию, используемый
emacs-uptime (см. emacs-uptime)
"%Y, %D, %H, %M, %z%S" означает, что количество секунд
будет выводиться всегда, а годы, дни, часы и минуты будут
показаны, только если они не равны нулю.
Управляющий флаг без вывода, который работает аналогично ‘%z’, но вместо этого подавляет вывод конечных нулевых элементов времени.
Выводит буквальный символ ‘%’.
Последовательности формата в верхнем регистре выводят единицы измерения вместе с числами, форматы в нижнем регистре выводят только числа.
Вы также можете указать ширину поля, поставив после ‘%’ число;
более короткие числа будут дополнены пробелами. Необязательная
точка перед шириной указывает на дополнение нулями вместо пробелов. Например,
"%.3Y" может выдать "004 years".