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

Несколько основных классов 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$'

Форматировать (с индексом 1) 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"

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