format-width.doc.patch

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
new file mode 100644
index 3879186..737d677
*** a/doc/src/sgml/func.sgml
--- b/doc/src/sgml/func.sgml
***************
*** 1524,1539 ****
         <entry><type>text</type></entry>
         <entry>
           Format arguments according to a format string.
!          This function is similar to the C function
!          <function>sprintf</>, but only the following conversion specifications
!          are recognized: <literal>%s</literal> interpolates the corresponding
!          argument as a string; <literal>%I</literal> escapes its argument as
!          an SQL identifier; <literal>%L</literal> escapes its argument as an
!          SQL literal; <literal>%%</literal> outputs a literal <literal>%</>.
!          A conversion can reference an explicit parameter position by preceding
!          the conversion specifier with <literal><replaceable>n</>$</>, where
!          <replaceable>n</replaceable> is the argument position.
!          See also <xref linkend="plpgsql-quote-literal-example">.
         </entry>
         <entry><literal>format('Hello %s, %1$s', 'World')</literal></entry>
         <entry><literal>Hello World, World</literal></entry>
--- 1524,1531 ----
         <entry><type>text</type></entry>
         <entry>
           Format arguments according to a format string.
!          This function is similar to the C function <function>sprintf</>.
!          See <xref linkend="functions-string-format">.
         </entry>
         <entry><literal>format('Hello %s, %1$s', 'World')</literal></entry>
         <entry><literal>Hello World, World</literal></entry>
***************
*** 2847,2852 ****
--- 2839,3024 ----
      </tgroup>
     </table>
  
+    <sect2 id="functions-string-format">
+     <title><function>format</function></title>
+ 
+     <indexterm>
+      <primary>format</primary>
+     </indexterm>
+ 
+     <para>
+      The function <function>format</> produces formatted output according to
+      a format string in a similar way to the C function <function>sprintf</>.
+     </para>
+ 
+     <para>
+ <synopsis>
+ format(<parameter>formatstr</> <type>text</> [, <parameter>str</> <type>"any"</> [, ...] ])
+ </synopsis>
+      <replaceable>formatstr</> is a format string that specifies how the
+      result should be formatted.  Text in the format string is copied directly
+      to the result, except where <firstterm>format specifiers</> are used.
+      Format specifiers act as placeholders in the string, allowing subsequent
+      function arguments to be formatted and inserted into the result.
+     </para>
+ 
+     <para>
+      Format specifiers are introduced by a <literal>%</> character and take
+      the form
+ <synopsis>
+ %[<replaceable>parameter</>][<replaceable>flags</>][<replaceable>width</>]<replaceable>type</>
+ </synopsis>
+      <variablelist>
+       <varlistentry>
+        <term><replaceable>parameter</replaceable> (optional)</term>
+        <listitem>
+         <para>
+          An expression of the form <literal><replaceable>n</>$</> where
+          <replaceable>n</> is the index of the argument to use for the format
+          specifier's value.  An index of 1 means the first argument after
+          <replaceable>formatstr</>.  If the <replaceable>parameter</> field is
+          omitted, the default is to use the next argument.
+         </para>
+ <screen>
+ SELECT format('Testing %s, %s, %s', 'one', 'two', 'three');
+ <lineannotation>Result: </><computeroutput>Testing one, two, three</>
+ 
+ SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
+ <lineannotation>Result: </><computeroutput>Testing three, two, one</>
+ </screen>
+ 
+         <para>
+          Note that unlike the C function <function>sprintf</> defined in the
+          Single UNIX Specification, the <function>format</> function in
+          <productname>PostgreSQL</> allows format specifiers with and without
+          explicit <replaceable>parameter</> fields to be mixed in the same
+          format string.  A format specifier without a
+          <replaceable>parameter</> field always uses the next argument after
+          the last argument consumed.  In addition, the
+          <productname>PostgreSQL</> <function>format</> function does not
+          require all function arguments to be referred to in the format
+          string.
+         </para>
+ <screen>
+ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
+ <lineannotation>Result: </><computeroutput>Testing three, two, three</>
+ </screen>
+        </listitem>
+       </varlistentry>
+ 
+       <varlistentry>
+        <term><replaceable>flags</replaceable> (optional)</term>
+        <listitem>
+         <para>
+          Additional options controlling how the format specifier's output is
+          formatted.  Currently the only supported flag is an minus sign
+          (<literal>-</>) which will cause the format specifier's output to be
+          left-aligned.  This has no effect unless the <replaceable>width</>
+          field is also specified.
+         </para>
+ <screen>
+ SELECT format('|%10s|%-10s|', 'foo', 'bar');
+ <lineannotation>Result: </><computeroutput>|       foo|bar       |</>
+ </screen>
+        </listitem>
+       </varlistentry>
+ 
+       <varlistentry>
+        <term><replaceable>width</replaceable> (optional)</term>
+        <listitem>
+         <para>
+          Specifies the <emphasis>minimum</> number of characters to use to
+          display the format specifier's output.  The width may be specified
+          using any of the following: a positive integer; an asterisk
+          (<literal>*</>) to use the next function argument as the width; or an
+          expression of the form <literal>*<replaceable>n</>$</> to use the
+          <replaceable>n</>th function argument as the width.
+         </para>
+ 
+         <para>
+          If the width comes from a function argument, that argument is
+          consumed <emphasis>before</> the argument that is used for the format
+          specifier's value.  If the width argument is negative, the result is
+          left aligned, as if the <literal>-</> flag had been specified.
+         </para>
+ <screen>
+ SELECT format('|%10s|', 'foo');
+ <lineannotation>Result: </><computeroutput>|       foo|</>
+ 
+ SELECT format('|%*s|', 10, 'foo');
+ <lineannotation>Result: </><computeroutput>|       foo|</>
+ 
+ SELECT format('|%*s|', -10, 'foo');
+ <lineannotation>Result: </><computeroutput>|foo       |</>
+ 
+ SELECT format('|%-*s|', 10, 'foo');
+ <lineannotation>Result: </><computeroutput>|foo       |</>
+ 
+ SELECT format('|%-*s|', -10, 'foo');
+ <lineannotation>Result: </><computeroutput>|foo       |</>
+ 
+ SELECT format('|%*2$s|', 'foo', 10, 'bar');
+ <lineannotation>Result: </><computeroutput>|       bar|</>
+ 
+ SELECT format('|%3$*2$s|', 'foo', 10, 'bar');
+ <lineannotation>Result: </><computeroutput>|       bar|</>
+ </screen>
+        </listitem>
+       </varlistentry>
+ 
+       <varlistentry>
+        <term><replaceable>type</replaceable> (required)</term>
+        <listitem>
+         <para>
+          The type of format conversion to use to produce the format
+          specifier's output.  The following types are supported:
+          <itemizedlist>
+           <listitem>
+            <para>
+             <literal>s</literal> formats the argument value as a simple
+             string.  A null value is treated as an empty string.
+            </para>
+           </listitem>
+           <listitem>
+            <para>
+             <literal>I</literal> escapes the value as an SQL identifier.  It
+             is an error for the value to be null.
+            </para>
+           </listitem>
+           <listitem>
+            <para>
+             <literal>L</literal> escapes the value as an SQL literal.  A null
+             value is displayed as the literal value <literal>NULL</>.
+            </para>
+           </listitem>
+          </itemizedlist>
+         </para>
+ <screen>
+ SELECT format('Hello %s', 'World');
+ <lineannotation>Result: </lineannotation><computeroutput>Hello World</computeroutput>
+ 
+ SELECT format('DROP TABLE %I', 'Foo bar');
+ <lineannotation>Result: </lineannotation><computeroutput>DROP TABLE "Foo bar"</computeroutput>
+ 
+ SELECT format('SELECT %L', E'O\'Reilly');
+ <lineannotation>Result: </lineannotation><computeroutput>SELECT 'O''Reilly'</computeroutput>
+ </screen>
+ 
+         <para>
+          The <literal>%I</> and <literal>%L</> format specifiers may be used
+          to safely construct dynamic SQL statements.  See
+          <xref linkend="plpgsql-quote-literal-example">.
+         </para>
+        </listitem>
+       </varlistentry>
+      </variablelist>
+     </para>
+ 
+     <para>
+      In addition to the format specifiers above, the special escape sequence
+      <literal>%%</> may be used to output a literal <literal>%</> character.
+     </para>
+    </sect2>
    </sect1>