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

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

• ARGF#printf

• IO#printf

• Kernel#printf

• Kernel#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"

Флаг '*'

Использует следующий аргумент в качестве ширины поля:

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

Флаг '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('%.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"

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

Спецификаторы 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#<<, но вызывает ArgumentError вместо RangeError.

Спецификатор 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"