[DOC] Format specs (#5857)

This new document would eventually replace the format spec discussion at Kernel#sprintf.

1 files changed, 196 insertions, 0 deletions

diff --git a/doc/format_specifications.rdoc b/doc/format_specifications.rdoc
new file mode 100644
index 0000000000..03de6a375d
--- /dev/null
+++ b/doc/format_specifications.rdoc
@@ -0,0 +1,196 @@
+== 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+: Convert +argument+ as a binary integer.
+  See {Specifiers b and B}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifiers+b+and+B].
+- +d+, +i+, or +u+ (all are identical):
+  Convert +argument+ as a decimal integer.
+  See {Specifier d}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifier+d].
+- +o+: Convert +argument+ as an octal integer.
+  See {Specifier o}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifier+o].
+- +x+ or +X+: Convert +argument+ as a hexadecimal integer.
+  See {Specifiers x and X}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifiers+x+and+X].
+
+==== Floating-Point Type Specifiers
+
+- +a+ or +A+: Convert +argument+ as hexadecimal floating-point number.
+  See {Specifiers a and A}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifiers+a+and+A].
+- +e+ or +E+: Convert +argument+ as
+  {scientific notation}[https://en.wikipedia.org/wiki/Scientific_notation].
+  See {Specifiers e and E}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifiers+e+and+E].
+- +f+: Convert +argument+ as a decimal floating-point number.
+  See {Specifier f}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifier+f].
+- +g+ or +G+: Convert +argument+ to a "general" format.
+  See {Specifiers g and G}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifiers+g+and+G].
+
+==== Other Type Specifiers
+
+- +c+: Convert +argument+ to a character.
+  See {Specifier c}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifier+c].
+- +p+: Convert +argument+ to a string via <tt>argument.inspect</tt>.
+  See {Specifier p}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifier+p].
+- +s+: Convert +argument+ to a string via <tt>argument.to_s</tt>.
+  See {Specifier s}[rdoc-ref:doc/kernel/format_specifications.rdoc@Specifier+s].
+- <tt>%</tt>: Convert a single percent character.
+  See {Specifier %}[rdoc-ref:doc/kernel/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
+
+Convert the (1-based) +n+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.
+
+Convert +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>
+