Форматирование строк

Форматирование означает построение строки путем подстановки вычисленных значений в различные места в постоянной строке. Эта постоянная строка управляет тем, как выводятся другие значения, а также тем, где они появляются; она называется строкой формата.

Форматирование часто полезно для вычисления сообщений, которые нужно отобразить. Фактически, функции message и error предоставляют ту же функцию форматирования, что и описанная здесь; они отличаются от format-message только тем, как они используют результат форматирования.

Функция: format строка &rest объекты

Эта функция возвращает строку, равную строке, заменяя любые спецификации формата кодировками соответствующих объектов. Аргументы объекты — это вычисленные значения, которые нужно отформатировать.

Символы в строке, отличные от спецификаций формата, копируются непосредственно в выходной поток, включая их текстовые свойства, если таковые имеются. Любые текстовые свойства спецификаций формата копируются в сгенерированные строковые представления аргумента объекты.

Выходная строка не обязательно должна быть вновь выделена. Например, если x — это строка "foo", выражения (eq x (format x)) и (eq x (format "%s" x)) могут оба дать t.

Функция: format-message строка &rest объекты

Эта функция действует так же, как format, за исключением того, что она также преобразует все гравные ударения (`) и апострофы (') в строке в соответствии со значением text-quoting-style.

Обычно гравные ударения и апострофы в формате переводятся в соответствующие криволинейные кавычки, например, "Не хватает `%s'" может привести к "Не хватает ‘foo’". См. Стиль цитирования текста для того, как влиять на этот перевод или запретить его.

Спецификация формата — это последовательность символов, начинающаяся с символа ‘%’. Таким образом, если в строке есть ‘%d’, функция format заменяет ее печатным представлением одного из значений для форматирования (одного из аргументов объекты). Например:

(format "The value of fill-column is %d." fill-column)
     ⇒ "The value of fill-column is 72."

Поскольку format интерпретирует символы ‘%’ как спецификации формата, вы никогда не должны передавать произвольную строку в качестве первого аргумента. Это особенно верно, когда строка генерируется каким-либо кодом Lisp. Если только строка не известна как не содержащая символов ‘%’, передайте "%s", описанную ниже, в качестве первого аргумента, а строку — в качестве второго, например так:

  (format "%s" arbitrary-string)

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

Вот таблица допустимых спецификаций формата:

‘%s’

Замените спецификацию печатным представлением объекта, созданным без кавычек (то есть, используя princ, а не prin1 — см. Функции вывода). Таким образом, строки представляются своим содержимым, без символов ‘"’, а символы отображаются без символов ‘\’.

Если объект является строкой, его текстовые свойства копируются в выходной поток. Текстовые свойства самого ‘%s’ также копируются, но свойства объекта имеют приоритет.

‘%S’

Замените спецификацию печатным представлением объекта, созданным с кавычками (то есть, используя prin1 — см. Функции вывода). Таким образом, строки заключаются в символы ‘"’, а символы ‘\’ появляются по мере необходимости перед специальными символами.

‘%o’

Замените спецификацию представлением числа в восьмеричной системе счисления. Отрицательные числа форматируются зависящим от платформы способом. Объект также может быть числом с плавающей точкой, которое форматируется как целое число, отбрасывая дробную часть.

‘%d’

Замените спецификацию представлением целого числа в десятичной системе счисления со знаком. Объект также может быть числом с плавающей точкой, которое форматируется как целое число, отбрасывая дробную часть.

‘%x’

‘%X’

Замените спецификацию представлением целого числа в шестнадцатеричной системе счисления. Отрицательные целые числа форматируются зависящим от платформы способом. ‘%x’ использует строчные буквы, а ‘%X’ — заглавные. Объект также может быть числом с плавающей точкой, которое форматируется как целое число, отбрасывая дробную часть.

‘%c’

Замените спецификацию символом, который является заданным значением.

‘%e’

Замените спецификацию экспоненциальной записью для числа с плавающей точкой.

‘%f’

Замените спецификацию десятичной записью для числа с плавающей точкой.

‘%g’

Замените спецификацию записью для числа с плавающей точкой, используя либо экспоненциальную, либо десятичную запись. Экспоненциальная запись используется, если показатель степени будет меньше -4 или больше или равен точности (по умолчанию: 6). По умолчанию хвостовые нули удаляются из дробной части результата, и символ десятичной точки появляется только в том случае, если за ним следует цифра.

‘%%’

Замените спецификацию одиночным символом ‘%’. Эта спецификация формата необычна тем, что ее единственная форма — это просто ‘%%’, и она не использует значение. Например, (format "%% %d" 30) возвращает "% 30".

Любой другой символ формата приводит к ошибке ‘Недопустимая операция форматирования’.

Вот несколько примеров, предполагающих типичные text-quoting-style настройки:

(format "The octal value of %d is %o,
         and the hex value is %x." 18 18 18)
     ⇒ "The octal value of 18 is 22,
         and the hex value is 12."

(format-message
 "The name of this buffer is ‘%s’." (buffer-name))
     ⇒ "The name of this buffer is ‘strings.texi’."

(format-message
 "The buffer object prints as `%s'." (current-buffer))
     ⇒ "The buffer object prints as ‘strings.texi’."

По умолчанию спецификации формата соответствуют последовательным значениям из объектов. Таким образом, первая спецификация формата в строке использует первое такое значение, вторая спецификация формата — второе и так далее. Любые дополнительные спецификации формата (для которых нет соответствующих значений) вызывают ошибку. Любые дополнительные значения для форматирования игнорируются.

Спецификация формата может иметь номер поля, который представляет собой десятичное число, сразу после начального ‘%’, за которым следует буквальный символ «$». Это приводит к тому, что спецификация формата преобразует аргумент с заданным номером вместо следующего аргумента. Номера полей начинаются с 1. Формат может содержать либо пронумерованные, либо непронумерованные спецификации формата, но не оба типа одновременно, за исключением того, что ‘%%’ можно смешивать с пронумерованными спецификациями.

(format "%2$s, %3$s, %%, %1$s" "x" "y" "z")
     ⇒ "y, z, %, x"

После символа ‘%’ и любого номера поля можно поместить определенные флаговые символы.

Флаг ‘+’ вставляет знак «плюс» перед неотрицательным числом, так что у него всегда есть знак. Пробел в качестве флага вставляет пробел перед неотрицательным числом. (В противном случае неотрицательные числа начинаются с первой цифры.) Эти флаги полезны для обеспечения того, что неотрицательные и отрицательные числа используют одинаковое количество столбцов. Они игнорируются за исключением ‘%d’, ‘%e’, ‘%f’, ‘%g’, и если используются оба флага, ‘+’ имеет приоритет.

Флаг ‘#’ задает альтернативную форму, которая зависит от используемого формата. Для ‘%o’ он гарантирует, что результат начинается с ‘0’. Для ‘%x’ и ‘%X’ он добавляет префикс ‘0x’ или ‘0X’ к ненулевым результатам. Для ‘%e’ и ‘%f’ флаг ‘#’ означает включение десятичной точки даже если точность равна нулю. Для ‘%g’ он всегда включает десятичную точку и также заставляет хвостовые нули после десятичной точки оставаться на месте, где они в противном случае были бы удалены.

Флаг ‘0’ гарантирует, что заполнение состоит из символов ‘0’ вместо пробелов. Этот флаг игнорируется для нечисловых символов спецификации, таких как ‘%s’, ‘%S’ и ‘%c’. Эти символы спецификации принимают флаг ‘0’, но все же заполняют пробелами.

Флаг ‘-’ заставляет любое заполнение, вставленное шириной, если указано, вставляться справа, а не слева. Если присутствуют и ‘-’, и ‘0’, флаг ‘0’ игнорируется.

(format "%06d is padded on the left with zeros" 123)
     ⇒ "000123 is padded on the left with zeros"

(format "'%-6d' is padded on the right" 123)
     ⇒ "'123   ' is padded on the right"

(format "The word '%-7s' actually has %d letters in it."
        "foo" (length "foo"))
     ⇒ "The word 'foo    ' actually has 3 letters in it."

Спецификация может иметь ширину, которая представляет собой десятичное число, появляющееся после любого номера поля и флагов. Если печатное представление объекта содержит меньше символов, чем эта ширина, format расширяет его, используя заполнение. Любое заполнение, введенное шириной, обычно состоит из пробелов, вставленных слева:

(format "%5d is padded on the left with spaces" 123)
     ⇒ "  123 is padded on the left with spaces"

Если ширина слишком мала, format не обрезает печатное представление объекта. Таким образом, вы можете использовать ширину для задания минимального интервала между столбцами без риска потери информации. В следующих двух примерах ‘%7s’ задает минимальную ширину 7. В первом случае строка, вставленная вместо ‘%7s’, имеет только 3 буквы и требует 4 пробела в качестве заполнения. Во втором случае строка "specification" имеет ширину 13 букв, но не обрезается.

(format "The word '%7s' has %d letters in it."
        "foo" (length "foo"))
     ⇒ "The word '    foo' has 3 letters in it."
(format "The word '%7s' has %d letters in it."
        "specification" (length "specification"))
     ⇒ "The word 'specification' has 13 letters in it."

Все символы спецификации допускают необязательную точность после номера поля, флагов и ширины, если они присутствуют. Точность — это десятичная точка ‘.’, за которой следует строка цифр. Для спецификаций чисел с плавающей точкой (‘%e’ и ‘%f’), точность определяет количество цифр после десятичной точки, которые нужно показать; если нуль, десятичная точка также пропускается. Для ‘%g’, точность определяет количество значащих цифр (значащие цифры — это первая цифра перед десятичной точкой и все цифры после нее). Если точность для %g равна нулю или не указана, она обрабатывается как 1. Для ‘%s’ и ‘%S’ точность обрезает строку до заданной ширины, поэтому ‘%.3s’ показывает только первые три символа представления объекта. Для других символов спецификации эффект точности определяется локальными библиотечными функциями семейства printf.

Если вы планируете использовать read позже в отформатированной строке для получения копии отформатированного значения, используйте спецификацию, которая позволяет read восстановить значение. Для форматирования чисел таким обратимым способом можно использовать ‘%s’ и ‘%S’, для форматирования только целых чисел также можно использовать ‘%d’, а для форматирования только неотрицательных целых чисел также можно использовать ‘#x%x’ и ‘#o%o’. Другие форматы могут быть проблематичными; например, ‘%d’ и ‘%g’ могут неправильно обрабатывать NaNs и могут потерять точность и тип, а ‘#x%x’ и ‘#o%o’ могут неправильно обрабатывать отрицательные целые числа. См. Функции ввода.

Функции, описанные в этом разделе, принимают фиксированный набор символов спецификации. В следующем разделе описывается функция format-spec, которая может принимать пользовательские символы спецификации, такие как ‘%a’ или ‘%z’.