ruby--ruby/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:doc/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:doc/format_specifications.rdoc@Specifier+d].
- +o+: Format +argument+ as an octal integer.
  See {Specifier o}[rdoc-ref:doc/format_specifications.rdoc@Specifier+o].
- +x+ or +X+: Format +argument+ as a hexadecimal integer.
  See {Specifiers x and X}[rdoc-ref:doc/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:doc/format_specifications.rdoc@Specifiers+a+and+A].
- +e+ or +E+: Format +argument+ in
  {scientific notation}[https://en.wikipedia.org/wiki/Scientific_notation].
  See {Specifiers e and E}[rdoc-ref:doc/format_specifications.rdoc@Specifiers+e+and+E].
- +f+: Format +argument+ as a decimal floating-point number.
  See {Specifier f}[rdoc-ref:doc/format_specifications.rdoc@Specifier+f].
- +g+ or +G+: Format +argument+ in a "general" format.
  See {Specifiers g and G}[rdoc-ref:doc/format_specifications.rdoc@Specifiers+g+and+G].

==== Other Type Specifiers

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

=== Flags

The effect of a flag may vary greatly among type specifiers.
These remarks are general in nature.

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"

=== Type Specifier Details and Examples

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

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

Type-specific modifier:

- '#' flag' (use alternate format):

    sprintf('%#b', 1)  # => "0b1"
    sprintf('%#B', 1)  # => "0B1"
    sprintf('%#b', 4)  # => "0b100"

==== Specifier +c+

==== Specifier +d+

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

==== Specifier +f+

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

==== Specifier +o+

==== Specifier +p+

==== Specifier +s+

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

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