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

Несколько классов ядра 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-й аргумент в это поле:

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> использует стиль форматирования, но стиль %{name} нет.

Примеры:

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