Improve docs about numeric formatting patterns (to_char/to_number).

The explanation about "0" versus "9" format characters was confusing
and arguably wrong; the discussion of sign handling wasn't very good
either.  Notably, while it's accurate to say that "FM" strips leading
zeroes in date/time values, what it really does with numeric values
is to strip *trailing* zeroes, and then only if you wrote "9" rather
than "0".  Per gripes from Erwin Brandstetter.

Discussion: https://postgr.es/m/CAGHENJ7jgRbTn6nf48xNZ=FHgL2WQ4X8mYsUAU57f-vq8PubEw@mail.gmail.com
Discussion: https://postgr.es/m/CAGHENJ45ymd=GOCu1vwV9u7GmCR80_5tW0fP9C_gJKbruGMHvQ@mail.gmail.com

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 28eda972739105683fea6372646bf1ea52c480ba..641b3b8f4e4cc6d9009d71a2df922e08919200d8 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -6351,11 +6351,11 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
       <tbody>
        <row>
         <entry><literal>9</literal></entry>
-        <entry>value with the specified number of digits</entry>
+        <entry>digit position (can be dropped if insignificant)</entry>
        </row>
        <row>
         <entry><literal>0</literal></entry>
-        <entry>value with leading zeros</entry>
+        <entry>digit position (will not be dropped, even if insignificant)</entry>
        </row>
        <row>
         <entry><literal>.</literal> (period)</entry>
@@ -6363,7 +6363,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
        </row>
        <row>
         <entry><literal>,</literal> (comma)</entry>
-        <entry>group (thousand) separator</entry>
+        <entry>group (thousands) separator</entry>
        </row>
        <row>
         <entry><literal>PR</literal></entry>
@@ -6421,6 +6421,39 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
     Usage notes for numeric formatting:
 
     <itemizedlist>
+     <listitem>
+      <para>
+       <literal>0</> specifies a digit position that will always be printed,
+       even if it contains a leading/trailing zero.  <literal>9</> also
+       specifies a digit position, but if it is a leading zero then it will
+       be replaced by a space, while if it is a trailing zero and fill mode
+       is specified then it will be deleted.  (For <function>to_number()</>,
+       these two pattern characters are equivalent.)
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       The pattern characters <literal>S</>, <literal>L</>, <literal>D</>,
+       and <literal>G</> represent the sign, currency symbol, decimal point,
+       and thousands separator characters defined by the current locale
+       (see <xref linkend="guc-lc-monetary">
+       and <xref linkend="guc-lc-numeric">).  The pattern characters period
+       and comma represent those exact characters, with the meanings of
+       decimal point and thousands separator, regardless of locale.
+      </para>
+     </listitem>
+
+     <listitem>
+      <para>
+       If no explicit provision is made for a sign
+       in <function>to_char()</>'s pattern, one column will be reserved for
+       the sign, and it will be anchored to (appear just left of) the
+       number.  If <literal>S</> appears just left of some <literal>9</>'s,
+       it will likewise be anchored to the number.
+      </para>
+     </listitem>
+
      <listitem>
       <para>
        A sign formatted using <literal>SG</literal>, <literal>PL</literal>, or
@@ -6428,18 +6461,10 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
        the number; for example,
        <literal>to_char(-12, 'MI9999')</literal> produces <literal>'-&nbsp;&nbsp;12'</literal>
        but <literal>to_char(-12, 'S9999')</literal> produces <literal>'&nbsp;&nbsp;-12'</literal>.
-       The Oracle implementation does not allow the use of
+       (The Oracle implementation does not allow the use of
        <literal>MI</literal> before <literal>9</literal>, but rather
        requires that <literal>9</literal> precede
-       <literal>MI</literal>.
-      </para>
-     </listitem>
-
-     <listitem>
-      <para>
-       <literal>9</literal> results in a value with the same number of
-       digits as there are <literal>9</literal>s. If a digit is
-       not available it outputs a space.
+       <literal>MI</literal>.)
       </para>
      </listitem>
 
@@ -6486,8 +6511,8 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
 
    <para>
     Certain modifiers can be applied to any template pattern to alter its
-    behavior.  For example, <literal>FM9999</literal>
-    is the <literal>9999</literal> pattern with the
+    behavior.  For example, <literal>FM99.99</literal>
+    is the <literal>99.99</literal> pattern with the
     <literal>FM</literal> modifier.
     <xref linkend="functions-formatting-numericmod-table"> shows the
     modifier patterns for numeric formatting.
@@ -6506,8 +6531,8 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
       <tbody>
        <row>
         <entry><literal>FM</literal> prefix</entry>
-        <entry>fill mode (suppress leading zeroes and padding blanks)</entry>
-        <entry><literal>FM9999</literal></entry>
+        <entry>fill mode (suppress trailing zeroes and padding blanks)</entry>
+        <entry><literal>FM99.99</literal></entry>
        </row>
        <row>
         <entry><literal>TH</literal> suffix</entry>
@@ -6554,6 +6579,10 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
         <entry><literal>to_char(-0.1, 'FM9.99')</literal></entry>
         <entry><literal>'-.1'</literal></entry>
        </row>
+       <row>
+        <entry><literal>to_char(-0.1, 'FM90.99')</literal></entry>
+        <entry><literal>'-0.1'</literal></entry>
+       </row>
        <row>
         <entry><literal>to_char(0.1, '0.9')</literal></entry>
         <entry><literal>'&nbsp;0.1'</literal></entry>