format

Данная команда генерирует отформатированную строку аналогично процедуре ANSI C sprintf. строкаФормата указывает, как отформатировать результат, используя спецификаторы преобразования %, как в sprintf, а дополнительные аргументы, если они есть, предоставляют значения, которые будут подставлены в результат. Возвращаемое значение из format — это отформатированная строка.

Детали форматирования

Команда работает, сканируя строкаФормата слева направо. Каждый символ из строки формата добавляется в строку результата, если это не знак процента. Если символ — %, то он не копируется в строку результата. Вместо этого символы, следующие за символом %, обрабатываются как спецификатор преобразования. Спецификатор преобразования управляет преобразованием следующего арг в определённый формат, и результат добавляется в строку результата вместо спецификатора преобразования. Если в строке формата несколько спецификаторов преобразования, каждый из них управляет преобразованием одного дополнительного арг. Команде format необходимо предоставить достаточно арг, чтобы удовлетворить требованиям всех спецификаторов преобразования в строкаФормата.

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

Необязательный позиционный спецификатор

Если % следует за десятичным числом и $, как в “%2$d”, то значение для преобразования берется не из следующего аргумента. Вместо этого оно берется из аргумента, указанного числом, где 1 соответствует первому арг. Если спецификатору преобразования требуются несколько аргументов из-за символов * в спецификаторе, то используются последовательные аргументы, начиная с аргумента, заданного числом. Это соответствует соглашениям XPG3 для позиционных спецификаторов. Если в строкаФормата есть позиционные спецификаторы, то все спецификаторы должны быть позиционными.

Необязательные флаги

Вторая часть спецификатора преобразования может содержать любые из следующих символов флагов в любом порядке:

-: Указывает, что преобразованный аргумент должен быть выровнен слева в своём поле (числа обычно выравниваются справа с ведущими пробелами при необходимости).
+: Указывает, что число всегда должно печататься со знаком, даже если оно положительное.
пробел: Указывает, что пробел должен быть добавлен в начало числа, если первый символ не является знаком.
0: Указывает, что число должно быть дополнено слева нулями вместо пробелов.
#: Запрашивает альтернативную форму вывода. Для преобразований o и O гарантируется, что первая цифра всегда равна 0. Для преобразований x или X, 0x или 0X (соответственно) будут добавлены в начало результата, если он не равен нулю. Для преобразований b, 0b будет добавлен в начало результата, если он не равен нулю. Для всех преобразований чисел с плавающей запятой (e, E, f, g и G) гарантируется, что результат всегда имеет десятичную точку. Для преобразований g и G это указывает, что заключительные нули не должны удаляться.

Необязательная ширина поля

Третья часть спецификатора преобразования — это десятичное число, определяющее минимальную ширину поля для этого преобразования. Обычно используется для выравнивания столбцов в таблицах. Если преобразованный аргумент содержит меньше символов, чем минимальная ширина поля, он дополняется, чтобы иметь ширину, равную минимальной ширине поля. Дополнение обычно выполняется путём добавления дополнительных пробелов слева от преобразованного аргумента, но флаги 0 и - могут быть использованы для задания дополнения нулями слева или пробелами справа соответственно. Если минимальная ширина поля задана как * вместо числа, то следующий аргумент команды format определяет минимальную ширину поля; он должен иметь целочисленное значение.

Необязательная точность/граница

Четвёртая часть спецификатора преобразования — это точность, которая состоит из точки, за которой следует число. Число используется по-разному для различных преобразований. Для преобразований e, E и f оно задаёт количество цифр, которые должны появляться справа от десятичной точки. Для преобразований g и G оно задаёт общее количество цифр, включая те, что с обеих сторон десятичной точки (однако заключительные нули после десятичной точки всё ещё будут опущены, если не задан флаг #). Для целочисленных преобразований он задаёт минимальное количество цифр для печати (если необходимо, будут добавлены ведущие нули). Для преобразований s он задаёт максимальное количество печатаемых символов; если строка длиннее этого значения, то заключительные символы будут отброшены. Если точность задана с * вместо числа, то следующий аргумент команды format определяет точность; он должен быть строкой с числовым значением.

Необязательный модификатор размера

Пятая часть спецификатора преобразования — это модификатор размера, который должен быть ll, h или l. Если это ll, то это указывает, что целочисленное значение берётся без усечения для преобразования в отформатированную подстроку. Если это h, то это указывает, что целочисленное значение усекается до диапазона 16 бит перед преобразованием. Этот вариант редко используется. Если это l, то это указывает, что целочисленное значение усекается до диапазона, аналогичного тому, что генерируется функцией wide() команды expr (по крайней мере, диапазон 64 бит). Если ни h, ни l не присутствуют, целочисленное значение усекается до диапазона, аналогичного тому, что генерируется функцией int() команды expr (по крайней мере, диапазон 32 бит, но определяется значением элемента wordSize массива tcl_platform).

Обязательный тип преобразования

Последнее в спецификаторе преобразования — это буквенный символ, который определяет тип выполняемого преобразования. В настоящее время поддерживаются следующие символы преобразования:

d: Преобразует целое число в строку со знаком в десятичном формате.
u: Преобразует целое число в строку без знака в десятичном формате.
i: Преобразует целое число в строку со знаком в десятичном формате (эквивалентно d).
o: Преобразует целое число в строку без знака в восьмеричном формате.
x или X: Преобразует целое число в строку без знака в шестнадцатеричном формате, используя цифры «0123456789abcdef» для x и «0123456789ABCDEF» для X).
b: Преобразует целое число в двоичную строку, используя цифры 0 и 1.
c: Преобразует целое число в представляющий его Unicode-символ.
s: Нет преобразования; просто вставка строки.
f: Преобразует число в строку со знаком в десятичном формате вида xx.yyy, где количество y определяется точностью (по умолчанию: 6). Если точность равна 0, то десятичная точка не выводится.
e или E: Преобразует число в экспоненциальную форму в формате x.yyye±zz, где количество y определяется точностью (по умолчанию: 6). Если точность равна 0, то десятичная точка не выводится. Если используется форма E, то выводится E вместо e.
g или G: Если экспонента меньше -4 или больше или равна точности, то преобразует число как для %e или %E. В противном случае преобразует как для %f. Заключительные нули и заключительная десятичная точка опускаются.
%: Нет преобразования: просто вставка %.

Отличия от ansi sprintf

Поведение команды format аналогично процедуре ANSI C sprintf, за исключением следующих различий:

Tcl гарантирует, что он будет работать с символами UNICODE.
Спецификаторы %p и %n не поддерживаются.
Для преобразований %c аргумент должен быть целочисленным значением, которое затем будет преобразовано в соответствующее значение символа.
Модификаторы размера игнорируются при форматировании чисел с плавающей запятой. Модификатор ll не имеет аналога в sprintf. Спецификатор b не имеет аналога в sprintf.

Примеры

Преобразовать числовое значение символа Юникода в сам символ:

set value 120
set char [format %c $value]

Преобразовать результат time в секунды с точностью до сотых долей секунды:

set us [lindex [time $someTclCode] 0]
puts [format "%.2f seconds to execute" [expr {$us / 1e6}]]

Создать упакованное цветовое описание X11:

# Each color-component should be in range (0..255)
set color [format "#%02x%02x%02x" $r $g $b]

Использовать коды формата XPG3 для переупорядочивания полей (метод, часто используемый в локализованных каталогах сообщений; см. msgcat) без переупорядочивания значений данных, передаваемых в format:

set fmt1 "Today, %d shares in %s were bought at $%.2f each"
puts [format $fmt1 123 "Global BigCorp" 19.37]

set fmt2 "Bought %2\$s equity ($%3$.2f x %1\$d) today"
puts [format $fmt2 123 "Global BigCorp" 19.37]

Вывести небольшую таблицу степеней тройки:

# Set up the column widths
set w1 5
set w2 10

# Make a nice header (with separator) for the table first
set sep +-[string repeat - $w1]-+-[string repeat - $w2]-+
puts $sep
puts [format "| %-*s | %-*s |" $w1 "Index" $w2 "Power"]
puts $sep

# Print the contents of the table
set p 1
for {set i 0} {$i<=20} {incr i} {
    puts [format "| %*d | %*ld |" $w1 $i $w2 $p]
    set p [expr {wide($p) * 3}]
}

# Finish off by printing the separator again
puts $sep

См. также

scan, sprintf, string

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TclCmd/format.htm