Add new SQL function, format(text).

Currently, three conversion format specifiers are supported: %s for a
string, %L for an SQL literal, and %I for an SQL identifier.  The latter
two are deliberately designed not to overlap with what sprintf() already
supports, in case we want to add more of sprintf()'s functionality here
later.

Patch by Pavel Stehule, heavily revised by me.  Reviewed by Jeff Janes
and, in earlier versions, by Itagaki Takahiro and Tom Lane.

doc/src/sgml/func.sgml

@@ -1271,6 +1271,9 @@
    <indexterm>
     <primary>encode</primary>
    </indexterm>
+   <indexterm>
+    <primary>format</primary>
+   </indexterm>
    <indexterm>
     <primary>initcap</primary>
    </indexterm>
@@ -1496,6 +1499,28 @@
        <entry><literal>MTIzAAE=</literal></entry>
       </row>       
 
+      <row>
+       <entry>
+        <literal><function>format</function>(<parameter>formatstr</parameter> <type>text</type>
+        [, <parameter>str</parameter> <type>"any"</type> [, ...] ])</literal>
+       </entry>
+       <entry><type>text</type></entry>
+       <entry>
+         Format a string.  This function is similar to the C function
+         <function>sprintf</>; but only the following conversions
+         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>
+      </row>
+
       <row>
        <entry><literal><function>initcap(<parameter>string</parameter>)</function></literal></entry>
        <entry><type>text</type></entry>

doc/src/sgml/plpgsql.sgml

@@ -1152,6 +1152,11 @@ EXECUTE 'SELECT count(*) FROM '
      <secondary>use in PL/pgSQL</secondary>
     </indexterm>
 
+    <indexterm>
+     <primary>format</primary>
+     <secondary>use in PL/pgSQL</secondary>
+    </indexterm>
+
     <para>
      When working with dynamic commands you will often have to handle escaping
      of single quotes.  The recommended method for quoting fixed text in your
@@ -1250,6 +1255,24 @@ EXECUTE 'UPDATE tbl SET '
      <emphasis>must</> use <function>quote_literal</>,
      <function>quote_nullable</>, or <function>quote_ident</>, as appropriate.
     </para>
+
+    <para>
+     Dynamic SQL statements can also be safely constructed using the
+     <function>format</function> function (see <xref
+     linkend="functions-string">). For example:
+<programlisting>
+EXECUTE format('UPDATE tbl SET %I = %L WHERE key = %L', colname, newvalue, keyvalue);
+</programlisting>
+     The <function>format</function> function can be used in conjunction with 
+     the <literal>USING</literal> clause:
+<programlisting>
+EXECUTE format('UPDATE tbl SET %I = $1 WHERE key = $2', colname)
+   USING newvalue, keyvalue;
+</programlisting>
+     This form is more efficient, because the parameters
+     <literal>newvalue</literal> and <literal>keyvalue</literal> are not
+     converted to text.
+    </para>
    </example>
 
     <para>