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

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

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

Функция: format string &rest objects

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

Символы в string, за исключением спецификаций формата, копируются непосредственно в выходную строку вместе со своими текстовыми свойствами, если они есть. Текстовые свойства спецификаций формата копируются в созданные строковые представления аргументов objects.

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

Функция: format-message string &rest objects

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

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

Спецификация формата — это последовательность символов, начинающаяся с «%». Поэтому, если в string есть «%d», функция format заменяет его печатным представлением одного из форматируемых значений (одного из аргументов objects). Например:

(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 — см. раздел Функции вывода). Таким образом, строки заключаются в символы «"», а перед специальными символами при необходимости ставятся символы «\».

«%b»

«%B»

Заменяет спецификацию двоичным представлением целого числа. Если число отрицательное, представление начинается с «-»; чтобы получить беззнаковое дополнительное представление числа, которое может быть отрицательным, n, отформатируйте (logand n mask), где mask соответствует требуемой разрядности слова. Хотя обычные «%b» и «%B» идентичны, «%#b» добавляет в начало строчную запись «0b», а «%#B» — прописную. Объектом также может быть число с плавающей точкой, которое форматируется как целое число с отбрасыванием дробной части.

«%o»

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

«%d»

«%i»

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

«%x»

«%X»

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

«%c»

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

«%e»

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

«%f»

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

«%g»

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

«%%»

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

Любой другой символ формата приводит к ошибке «Invalid format operation».

Ниже приведено несколько примеров, предполагающих типичные настройки 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’."

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

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

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

После символа «%» и номера поля, если он есть, можно указать некоторые символы-флаги.

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

Флаг «#» задаёт альтернативную форму, зависящую от используемого формата. Для «%o» он гарантирует, что результат начинается с «0». Для «%x», «%X», «%b» и «%B» он добавляет перед ненулевыми результатами соответственно «0x», «0X», «0b» или «0B». Для «%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» выводит только первые три символа представления object. Для остальных символов спецификации эффект точности соответствует результату работы локальных библиотечных функций семейства printf.

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

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