diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
new file mode 100644
index 3879186..240a6e7
*** a/doc/src/sgml/func.sgml
--- b/doc/src/sgml/func.sgml
***************
*** 1519,1539 ****
format
format(formatstr text
! [, str "any" [, ...] ])
text
Format arguments according to a format string.
! This function is similar to the C function
! sprintf, but only the following conversion specifications
! are recognized: %s interpolates the corresponding
! argument as a string; %I escapes its argument as
! an SQL identifier; %L escapes its argument as an
! SQL literal; %% outputs a literal %.
! A conversion can reference an explicit parameter position by preceding
! the conversion specifier with n$, where
! n is the argument position.
! See also .
format('Hello %s, %1$s', 'World')
Hello World, World
--- 1519,1531 ----
format
format(formatstr text
! [, formatarg "any" [, ...] ])
text
Format arguments according to a format string.
! This function is similar to the C function sprintf.
! See .
format('Hello %s, %1$s', 'World')
Hello World, World
***************
*** 2847,2852 ****
--- 2839,3024 ----
+
+ <function>format</function>
+
+
+ format
+
+
+
+ The function format produces formatted output according to
+ a format string in a similar way to the C function sprintf.
+
+
+
+
+ format(formatstr text [, formatarg "any" [, ...] ])
+
+ 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 format specifiers are used.
+ Format specifiers act as placeholders in the string, allowing subsequent
+ function arguments to be formatted and inserted into the result.
+
+
+
+ Format specifiers are introduced by a % character and take
+ the form
+
+ %[parameter][flags][width]type
+
+
+
+ parameter (optional)
+
+
+ An expression of the form n$ where
+ n is the index of the argument to use for the format
+ specifier's value. An index of 1 means the first argument after
+ formatstr. If the parameter field is
+ omitted, the default is to use the next argument.
+
+
+ SELECT format('Testing %s, %s, %s', 'one', 'two', 'three');
+ Result: Testing one, two, three
+
+ SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
+ Result: Testing three, two, one
+
+
+
+ Note that unlike the C function sprintf defined in the
+ Single UNIX Specification, the format function in
+ PostgreSQL allows format specifiers with and without
+ explicit parameter fields to be mixed in the same
+ format string. A format specifier without a
+ parameter field always uses the next argument after
+ the last argument consumed. In addition, the
+ PostgreSQL format function does not
+ require all function arguments to be referred to in the format
+ string.
+
+
+ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
+ Result: Testing three, two, three
+
+
+
+
+
+ flags (optional)
+
+
+ Additional options controlling how the format specifier's output is
+ formatted. Currently the only supported flag is an minus sign
+ (-) which will cause the format specifier's output to be
+ left-aligned. This has no effect unless the width
+ field is also specified.
+
+
+ SELECT format('|%10s|%-10s|', 'foo', 'bar');
+ Result: | foo|bar |
+
+
+
+
+
+ width (optional)
+
+
+ Specifies the 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
+ (*) to use the next function argument as the width; or an
+ expression of the form *n$ to use the
+ nth function argument as the width.
+
+
+
+ If the width comes from a function argument, that argument is
+ consumed 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 - flag had been specified.
+
+
+ SELECT format('|%10s|', 'foo');
+ Result: | foo|
+
+ SELECT format('|%*s|', 10, 'foo');
+ Result: | foo|
+
+ SELECT format('|%*s|', -10, 'foo');
+ Result: |foo |
+
+ SELECT format('|%-*s|', 10, 'foo');
+ Result: |foo |
+
+ SELECT format('|%-*s|', -10, 'foo');
+ Result: |foo |
+
+ SELECT format('|%*2$s|', 'foo', 10, 'bar');
+ Result: | bar|
+
+ SELECT format('|%3$*2$s|', 'foo', 10, 'bar');
+ Result: | bar|
+
+
+
+
+
+ type (required)
+
+
+ The type of format conversion to use to produce the format
+ specifier's output. The following types are supported:
+
+
+
+ s formats the argument value as a simple
+ string. A null value is treated as an empty string.
+
+
+
+
+ I escapes the value as an SQL identifier. It
+ is an error for the value to be null.
+
+
+
+
+ L escapes the value as an SQL literal. A null
+ value is displayed as the literal value NULL.
+
+
+
+
+
+ SELECT format('Hello %s', 'World');
+ Result: Hello World
+
+ SELECT format('DROP TABLE %I', 'Foo bar');
+ Result: DROP TABLE "Foo bar"
+
+ SELECT format('SELECT %L', E'O\'Reilly');
+ Result: SELECT 'O''Reilly'
+
+
+
+ The %I and %L format specifiers may be used
+ to safely construct dynamic SQL statements. See
+ .
+
+
+
+
+
+
+
+ In addition to the format specifiers above, the special escape sequence
+ %% may be used to output a literal % character.
+
+