Спецификации формата

У нескольких основных классов Ruby есть методы экземпляра printf или sprintf:

Каждый из этих методов принимает:

Аргумент format_string, содержащий ноль или более встроенных спецификаций формата (см. ниже).
Аргументы *arguments — ноль или более объектов для форматирования.

Каждый из этих методов выводит или возвращает строку, полученную заменой каждой спецификации формата, встроенной в format_string, строковым представлением соответствующего аргумента из arguments.

Простой пример:

sprintf('Name: %s; value: %d', 'Foo', 0) # => "Name: Foo; value: 0"

Спецификация формата имеет вид:

%[flags][width][.precision]type

Она состоит из следующих частей:

Начальный символ процента.
Ноль или более флагов (каждый — это символ).
Необязательный спецификатор ширины (целое число или *).
Необязательный спецификатор точности (точка, за которой следует неотрицательное целое число, или *).
Спецификатор типа (символ).

За исключением начального символа процента, обязательной является только часть со спецификатором типа, поэтому начнём с неё.

Спецификаторы типа

В этом разделе кратко описан каждый спецификатор типа. По ссылкам можно перейти к подробному описанию и примерам.

Спецификаторы целочисленного типа

b или B: форматирует argument как двоичное целое число. См. Спецификаторы b и B.
d, i или u (все они идентичны): форматирует argument как десятичное целое число. См. Спецификатор d.
o: форматирует argument как восьмеричное целое число. См. Спецификатор o.
x или X: форматирует argument как шестнадцатеричное целое число. См. Спецификаторы x и X.

Спецификаторы типа с плавающей точкой

a или A: форматирует argument как шестнадцатеричное число с плавающей точкой. См. Спецификаторы a и A.
e или E: форматирует argument в экспоненциальной записи. См. Спецификаторы e и E.
f: форматирует argument как десятичное число с плавающей точкой. См. Спецификатор f.
g или G: форматирует argument в «общем» формате. См. Спецификаторы g и G.

Другие спецификаторы типа

c: форматирует argument как символ. См. Спецификатор c.
p: форматирует argument как строку с помощью argument.inspect. См. Спецификатор p.
s: форматирует argument как строку с помощью argument.to_s. См. Спецификатор s.
%: форматирует argument ('%') как один символ процента. См. Спецификатор %.

Флаги

Действие флага может сильно различаться в зависимости от спецификатора типа. Ниже приведены общие замечания. См. подробное описание для конкретных типов.

Для одного спецификатора типа можно указать несколько флагов; порядок не имеет значения.

Флаг `' '`

Добавляет пробел перед неотрицательным числом:

sprintf('%d', 10)  # => "10"
sprintf('% d', 10) # => " 10"

Добавляет знак минус перед отрицательным значением:

sprintf('%d', -10)  # => "-10"
sprintf('% d', -10) # => "-10"

Флаг `'#'`

Использует альтернативный формат; действие зависит от типа:

sprintf('%x', 100)  # => "64"
sprintf('%#x', 100) # => "0x64"

Флаг `'+'`

Добавляет знак плюса перед неотрицательным числом:

sprintf('%x', 100)  # => "64"
sprintf('%+x', 100) # => "+64"

Флаг `'-'`

Выравнивает значение по левому краю поля:

sprintf('%6d', 100)  # => "   100"
sprintf('%-6d', 100) # => "100   "

Флаг `'0'`

Заполняет поле слева нулями вместо пробелов:

sprintf('%6d', 100)  # => "   100"
sprintf('%06d', 100) # => "000100"

Флаг `'n$'`

Форматирует аргумент под номером n (отсчёт начинается с 1) в это поле:

sprintf("%s %s", 'world', 'hello')     # => "world hello"
sprintf("%2$s %1$s", 'world', 'hello') # => "hello world"

Спецификатор ширины

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

sprintf('%10d', 100)  # => "       100"

# Left-justify if negative.
sprintf('%-10d', 100) # => "100       "

# Ignore if too small.
sprintf('%1d', 100)   # => "100"

Если вместо целого числа указан '*', минимальная ширина берётся из списка аргументов:

sprintf('%*d', 20, 14) # => "                  14"

Спецификатор точности

Спецификатор точности — это десятичная точка, за которой следует ноль или более десятичных цифр.

Для спецификаторов целочисленного типа точность задаёт минимальное количество выводимых цифр. Если точность меньше длины целого числа, результат дополняется ведущими нулями. Если целое число длиннее значения точности, результат не изменяется и не усекается:

sprintf('%.3d', 1)    # => "001"
sprintf('%.3d', 1000) # => "1000"

# If the precision is 0 and the value is 0, nothing is written
sprintf('%.d', 0)  # => ""
sprintf('%.0d', 0) # => ""

Для спецификаторов a/A, e/E, f/F точность задаёт количество цифр после десятичной точки:

sprintf('%.2f', 3.14159)  # => "3.14"
sprintf('%.10f', 3.14159) # => "3.1415900000"

# With no precision specifier, defaults to 6-digit precision.
sprintf('%f', 3.14159)    # => "3.141590"

Для спецификаторов g/G точность задаёт количество значащих цифр:

sprintf('%.2g', 123.45)  # => "1.2e+02"
sprintf('%.3g', 123.45)  # => "123"
sprintf('%.10g', 123.45) # =>  "123.45"

# With no precision specifier, defaults to 6 significant digits.
sprintf('%g', 123.456789) # => "123.457"

Для спецификаторов s, p точность задаёт количество выводимых символов:

sprintf('%s', Time.now)    # => "2022-05-04 11:59:16 -0400"
sprintf('%.10s', Time.now) # => "2022-05-04"

Если вместо неотрицательного целого числа в спецификаторе точности указан '*', фактическое значение точности берётся из списка аргументов:

sprintf('%.*d', 20, 1)    # => "00000000000000000001"

Подробное описание спецификаторов типа и примеры

Спецификаторы `a` и `A`

Форматирует argument как шестнадцатеричное число с плавающей точкой:

sprintf('%a', 3.14159)   # => "0x1.921f9f01b866ep+1"
sprintf('%a', -3.14159)  # => "-0x1.921f9f01b866ep+1"
sprintf('%a', 4096)      # => "0x1p+12"
sprintf('%a', -4096)     # => "-0x1p+12"

# Capital 'A' means that alphabetical characters are printed in upper case.
sprintf('%A', 4096)      # => "0X1P+12"
sprintf('%A', -4096)     # => "-0X1P+12"

Спецификаторы `b` и `B`

Два спецификатора b и B ведут себя одинаково, за исключением случаев, когда используется флаг '#'+.

Форматирует argument как двоичное целое число:

sprintf('%b', 1)  # => "1"
sprintf('%b', 4)  # => "100"

# Prefix '..' for negative value.
sprintf('%b', -4) # => "..100"

# Alternate format.
sprintf('%#b', 4)  # => "0b100"
sprintf('%#B', 4)  # => "0B100"

Спецификатор `c`

Форматирует argument как один символ:

sprintf('%c', 'A') # => "A"
sprintf('%c', 65)  # => "A"

Работает как String#<<, но вместо RangeError вызывает ArgumentError.

Спецификатор `d`

Форматирует argument как десятичное целое число:

sprintf('%d', 100)  # => "100"
sprintf('%d', -100) # => "-100"

Флаг '#' не применяется.

Спецификаторы `e` и `E`

Форматирует argument в экспоненциальной записи:

sprintf('%e', 3.14159)  # => "3.141590e+00"
sprintf('%E', -3.14159) # => "-3.141590E+00"

Спецификатор `f`

Форматирует argument как число с плавающей точкой:

sprintf('%f', 3.14159)  # => "3.141590"
sprintf('%f', -3.14159) # => "-3.141590"

Флаг '#' не применяется.

Спецификаторы `g` и `G`

Форматирует argument в экспоненциальной форме (спецификатор e/E), если показатель степени меньше -4 или больше либо равен точности. В противном случае форматирует argument в форме с плавающей точкой (спецификатор f):

sprintf('%g', 100)  # => "100"
sprintf('%g', 100.0)  # => "100"
sprintf('%g', 3.14159)  # => "3.14159"
sprintf('%g', 100000000000)  # => "1e+11"
sprintf('%g', 0.000000000001)  # => "1e-12"

# Capital 'G' means use capital 'E'.
sprintf('%G', 100000000000)  # => "1E+11"
sprintf('%G', 0.000000000001)  # => "1E-12"

# Alternate format.
sprintf('%#g', 100000000000)  # => "1.00000e+11"
sprintf('%#g', 0.000000000001)  # => "1.00000e-12"
sprintf('%#G', 100000000000)  # => "1.00000E+11"
sprintf('%#G', 0.000000000001)  # => "1.00000E-12"

Спецификатор `o`

Форматирует argument как восьмеричное целое число. Если argument отрицательно, оно форматируется в дополнительном коде с префиксом ..7:

sprintf('%o', 16)   # => "20"

# Prefix '..7' for negative value.
sprintf('%o', -16)  # => "..760"

# Prefix zero for alternate format if positive.
sprintf('%#o', 16)  # => "020"
sprintf('%#o', -16) # => "..760"

Спецификатор `p`

Форматирует argument как строку с помощью argument.inspect:

t = Time.now
sprintf('%p', t)   # => "2022-05-01 13:42:07.1645683 -0500"

Спецификатор `s`

Форматирует argument как строку с помощью argument.to_s:

t = Time.now
sprintf('%s', t) # => "2022-05-01 13:42:07 -0500"

Флаг '#' не применяется.

Спецификаторы `x` и `X`

Форматирует argument как шестнадцатеричное целое число. Если argument отрицательно, оно форматируется в дополнительном коде с префиксом ..f:

sprintf('%x', 100)   # => "64"

# Prefix '..f' for negative value.
sprintf('%x', -100)  # => "..f9c"

# Use alternate format.
sprintf('%#x', 100)  # => "0x64"

# Alternate format for negative value.
sprintf('%#x', -100) # => "0x..f9c"

Спецификатор `%`

Форматирует argument ('%') как один символ процента:

sprintf('%d %%', 100) # => "100 %"

Флаги не применяются.

Обращение по имени

Для более сложного форматирования Ruby поддерживает обращение по имени. В стиле %<name>s используется стиль форматирования, а в стиле %{name} — нет.

Примеры:

sprintf("%<foo>d : %<bar>f", { :foo => 1, :bar => 2 }) # => 1 : 2.000000
sprintf("%{foo}f", { :foo => 1 })                      # => "1f"

Ruby Core © 1993–2025 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.