[DOC] More on format specs (#5877)

* Update doc/format_specifications.rdoc

Co-authored-by: Peter Zhu <peter@peterzhu.ca>

1 files changed, 151 insertions, 9 deletions

diff --git a/doc/format_specifications.rdoc b/doc/format_specifications.rdoc
index e081f87eb7..323d6c9e0b 100644
--- a/doc/format_specifications.rdoc
+++ b/doc/format_specifications.rdoc
@@ -58,8 +58,7 @@ The links lead to the details and examples.
 
 - +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}[https://en.wikipedia.org/wiki/Scientific_notation].
+- +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].
@@ -75,12 +74,13 @@ The links lead to the details and examples.
 - +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+%].
+  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.
@@ -145,15 +145,70 @@ 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
@@ -163,34 +218,121 @@ 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:
+  # Alternate format.
+  sprintf('%#b', 4)  # => "0b100"
+  sprintf('%#B', 4)  # => "0B100"
 
-- '#' flag' (use alternate format):
+==== Specifier +c+
 
-    sprintf('%#b', 1)  # => "0b1"
-    sprintf('%#B', 1)  # => "0B1"
-    sprintf('%#b', 4)  # => "0b100"
+Format +argument+ as a single character:
 
-==== Specifier +c+
+  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.