path: root/doc/format_specifications.rdoc

== Format Specifications

Several Ruby core classes have instance method +printf+ or +sprintf+:

- ARGF#printf
- IO#printf
- Kernel#printf
- Kernel#sprintf

Each of these methods takes:

- Argument +format_string+, which has zero or more
  embedded _format_ _specifications_ (see below).
- Arguments <tt>*arguments</tt>, which are zero or more objects to be formatted.

Each of these methods prints or returns the string
resulting from replacing each
format specification embedded in +format_string+ with a string form
of the corresponding argument among +arguments+.

A simple example:

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

A format specification has the form:

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

It consists of:

- A leading percent character.
- Zero or more _flags_ (each is a character).
- An optional _width_ _specifier_ (an integer).
- An optional _precision_ _specifier_ (a period followed by a non-negative integer).
- A _type_ _specifier_ (a character).

Except for the leading percent character,
the only required part is the type specifier, so we begin with that.

=== Type Specifiers

This section provides a brief explanation of each type specifier.
The links lead to the details and examples.

==== \Integer Type Specifiers

- +b+ or +B+: Format +argument+ as a binary integer.
  See {Specifiers b and B}[rdoc-ref:format_specifications.rdoc@Specifiers+b+and+B].
- +d+, +i+, or +u+ (all are identical):
  Format +argument+ as a decimal integer.
  See {Specifier d}[rdoc-ref:format_specifications.rdoc@Specifier+d].
- +o+: Format +argument+ as an octal integer.
  See {Specifier o}[rdoc-ref:format_specifications.rdoc@Specifier+o].
- +x+ or +X+: Format +argument+ as a hexadecimal integer.
  See {Specifiers x and X}[rdoc-ref:format_specifications.rdoc@Specifiers+x+and+X].

==== Floating-Point Type Specifiers

- +a+ or +A+: Format +argument+ as hexadecimal floating-point number.
  See {Specifiers a and A}[rdoc-ref:format_specifications.rdoc@Specifiers+a+and+A].
- +e+ or +E+: Format +argument+ in scientific notation.
  See {Specifiers e and E}[rdoc-ref:format_specifications.rdoc@Specifiers+e+and+E].
- +f+: Format +argument+ as a decimal floating-point number.
  See {Specifier f}[rdoc-ref:format_specifications.rdoc@Specifier+f].
- +g+ or +G+: Format +argument+ in a "general" format.
  See {Specifiers g and G}[rdoc-ref:format_specifications.rdoc@Specifiers+g+and+G].

==== Other Type Specifiers

- +c+: Format +argument+ as a character.
  See {Specifier c}[rdoc-ref:format_specifications.rdoc@Specifier+c].
- +p+: Format +argument+ as a string via <tt>argument.inspect</tt>.
  See {Specifier p}[rdoc-ref:format_specifications.rdoc@Specifier+p].
- +s+: Format +argument+ as a string via <tt>argument.to_s</tt>.
  See {Specifier s}[rdoc-ref:format_specifications.rdoc@Specifier+s].
- <tt>%</tt>: Format +argument+ (<tt>'%'</tt>) as a single percent character.
  See {Specifier %}[rdoc-ref:format_specifications.rdoc@Specifier+-25].

=== Flags

The effect of a flag may vary greatly among type specifiers.
These remarks are general in nature.
See {type-specific details}[rdoc-ref:format_specifications.rdoc@Type+Specifier+Details+and+Examples].

Multiple flags may be given with single type specifier;
order does not matter.

==== <tt>' '</tt> Flag

Insert a space before a non-negative number:

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

Insert a minus sign for negative value:

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

==== <tt>'#'</tt> Flag

Use an alternate format; varies among types:

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

==== <tt>'+'</tt> Flag

Add a leading plus sign for a non-negative number:

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

==== <tt>'-'</tt> Flag

Left justify the value in its field:

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

==== <tt>'0'</tt> Flag

Left-pad with zeros instead of spaces:

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

==== <tt>'*'</tt> Flag

Use the next argument as the field width:

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

==== <tt>'n$'</tt> Flag

Format the (1-based) <tt>n</tt>th argument into this field:

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

=== Width Specifier

In general, a width specifier determines the minimum width (in characters)
of the formatted field:

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

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

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

=== Precision Specifier

A precision specifier is a decimal point followed by zero or more
decimal digits.

For integer type specifiers, the precision specifies the minimum number of
digits to be written. If the precision is shorter than the integer, the result is
padded with leading zeros. There is no modification or truncation of the result
if the integer is longer than the precision:

  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) # => ""

For the +a+/+A+, +e+/+E+, +f+/+F+ specifiers, the precision specifies
the number of digits after the decimal point to be written:

  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"

For the +g+/+G+ specifiers, the precision specifies
the number of significant digits to be written:

  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"

For the +s+, +p+ specifiers, the precision specifies
the number of characters to write:

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

=== Type Specifier Details and Examples

==== Specifiers +a+ and +A+

Format +argument+ as hexadecimal floating-point number:

  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"

==== Specifiers +b+ and +B+

The two specifiers +b+ and +B+ behave identically
except when flag <tt>'#'</tt>+ is used.

Format +argument+ as a binary integer:

  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"

==== Specifier +c+

Format +argument+ as a single character:

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

==== Specifier +d+

Format +argument+ as a decimal integer:

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

Flag <tt>'#'</tt> does not apply.

==== Specifiers +e+ and +E+

Format +argument+ in
{scientific notation}[https://en.wikipedia.org/wiki/Scientific_notation]:

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

==== Specifier +f+

Format +argument+ as a floating-point number:

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

Flag <tt>'#'</tt> does not apply.

==== Specifiers +g+ and +G+

Format +argument+ using exponential form (+e+/+E+ specifier)
if the exponent is less than -4 or greater than or equal to the precision.
Otherwise format +argument+ using floating-point form (+f+ specifier):

  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"

==== Specifier +o+

Format +argument+ as an octal integer.
If +argument+ is negative, it will be formatted as a two's complement
prefixed with +..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"

==== Specifier +p+

Format +argument+ as a string via <tt>argument.inspect</tt>:

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

==== Specifier +s+

Format +argument+ as a string via <tt>argument.to_s</tt>:

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

Flag <tt>'#'</tt> does not apply.

==== Specifiers +x+ and +X+

Format +argument+ as a hexadecimal integer.
If +argument+ is negative, it will be formatted as a two's complement
prefixed with +..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"

==== Specifier <tt>%</tt>

Format +argument+ (<tt>'%'</tt>) as a single percent character:

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

Flags do not apply.

=== Reference by Name

For more complex formatting, Ruby supports a reference by name.
%<name>s style uses format style, but %{name} style doesn't.

Examples:

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