Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 73e7025

Browse files
tglsfdctglsfdc
committed
Extend format() to handle field width and left/right alignment.
This change adds some more standard sprintf() functionality to format(). Pavel Stehule, reviewed by Dean Rasheed and Kyotaro Horiguchi
1 parent 1a1832e commit 73e7025

File tree

4 files changed

+656
-97
lines changed

4 files changed

+656
-97
lines changed

‎doc/src/sgml/func.sgml

Lines changed: 211 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1519,21 +1519,13 @@
15191519
<primary>format</primary>
15201520
</indexterm>
15211521
<literal><function>format</function>(<parameter>formatstr</parameter> <type>text</type>
1522-
[, <parameter>str</parameter> <type>"any"</type> [, ...] ])</literal>
1522+
[, <parameter>formatarg</parameter> <type>"any"</type> [, ...] ])</literal>
15231523
</entry>
15241524
<entry><type>text</type></entry>
15251525
<entry>
15261526
Format arguments according to a format string.
1527-
This function is similar to the C function
1528-
<function>sprintf</>, but only the following conversion specifications
1529-
are recognized: <literal>%s</literal> interpolates the corresponding
1530-
argument as a string; <literal>%I</literal> escapes its argument as
1531-
an SQL identifier; <literal>%L</literal> escapes its argument as an
1532-
SQL literal; <literal>%%</literal> outputs a literal <literal>%</>.
1533-
A conversion can reference an explicit parameter position by preceding
1534-
the conversion specifier with <literal><replaceable>n</>$</>, where
1535-
<replaceable>n</replaceable> is the argument position.
1536-
See also <xref linkend="plpgsql-quote-literal-example">.
1527+
This function is similar to the C function <function>sprintf</>.
1528+
See <xref linkend="functions-string-format">.
15371529
</entry>
15381530
<entry><literal>format('Hello %s, %1$s', 'World')</literal></entry>
15391531
<entry><literal>Hello World, World</literal></entry>
@@ -2847,6 +2839,214 @@
28472839
</tgroup>
28482840
</table>
28492841

2842+
<sect2 id="functions-string-format">
2843+
<title><function>format</function></title>
2844+
2845+
<indexterm>
2846+
<primary>format</primary>
2847+
</indexterm>
2848+
2849+
<para>
2850+
The function <function>format</> produces output formatted according to
2851+
a format string, in a style similar to the C function
2852+
<function>sprintf</>.
2853+
</para>
2854+
2855+
<para>
2856+
<synopsis>
2857+
<function>format</>(<parameter>formatstr</> <type>text</> [, <parameter>formatarg</> <type>"any"</> [, ...] ])
2858+
</synopsis>
2859+
<replaceable>formatstr</> is a format string that specifies how the
2860+
result should be formatted. Text in the format string is copied
2861+
directly to the result, except where <firstterm>format specifiers</> are
2862+
used. Format specifiers act as placeholders in the string, defining how
2863+
subsequent function arguments should be formatted and inserted into the
2864+
result. Each <replaceable>formatarg</> argument is converted to text
2865+
according to the usual output rules for its data type, and then formatted
2866+
and inserted into the result string according to the format specifier(s).
2867+
</para>
2868+
2869+
<para>
2870+
Format specifiers are introduced by a <literal>%</> character and have
2871+
the form
2872+
<synopsis>
2873+
%[<replaceable>position</>][<replaceable>flags</>][<replaceable>width</>]<replaceable>type</>
2874+
</synopsis>
2875+
where the component fields are:
2876+
2877+
<variablelist>
2878+
<varlistentry>
2879+
<term><replaceable>position</replaceable> (optional)</term>
2880+
<listitem>
2881+
<para>
2882+
A string of the form <literal><replaceable>n</>$</> where
2883+
<replaceable>n</> is the index of the argument to print.
2884+
Index 1 means the first argument after
2885+
<replaceable>formatstr</>. If the <replaceable>position</> is
2886+
omitted, the default is to use the next argument in sequence.
2887+
</para>
2888+
</listitem>
2889+
</varlistentry>
2890+
2891+
<varlistentry>
2892+
<term><replaceable>flags</replaceable> (optional)</term>
2893+
<listitem>
2894+
<para>
2895+
Additional options controlling how the format specifier's output is
2896+
formatted. Currently the only supported flag is a minus sign
2897+
(<literal>-</>) which will cause the format specifier's output to be
2898+
left-justified. This has no effect unless the <replaceable>width</>
2899+
field is also specified.
2900+
</para>
2901+
</listitem>
2902+
</varlistentry>
2903+
2904+
<varlistentry>
2905+
<term><replaceable>width</replaceable> (optional)</term>
2906+
<listitem>
2907+
<para>
2908+
Specifies the <emphasis>minimum</> number of characters to use to
2909+
display the format specifier's output. The output is padded on the
2910+
left or right (depending on the <literal>-</> flag) with spaces as
2911+
needed to fill the width. A too-small width does not cause
2912+
truncation of the output, but is simply ignored. The width may be
2913+
specified using any of the following: a positive integer; an
2914+
asterisk (<literal>*</>) to use the next function argument as the
2915+
width; or a string of the form <literal>*<replaceable>n</>$</> to
2916+
use the <replaceable>n</>th function argument as the width.
2917+
</para>
2918+
2919+
<para>
2920+
If the width comes from a function argument, that argument is
2921+
consumed before the argument that is used for the format specifier's
2922+
value. If the width argument is negative, the result is left
2923+
aligned (as if the <literal>-</> flag had been specified) within a
2924+
field of length <function>abs</>(<replaceable>width</replaceable>).
2925+
</para>
2926+
</listitem>
2927+
</varlistentry>
2928+
2929+
<varlistentry>
2930+
<term><replaceable>type</replaceable> (required)</term>
2931+
<listitem>
2932+
<para>
2933+
The type of format conversion to use to produce the format
2934+
specifier's output. The following types are supported:
2935+
<itemizedlist>
2936+
<listitem>
2937+
<para>
2938+
<literal>s</literal> formats the argument value as a simple
2939+
string. A null value is treated as an empty string.
2940+
</para>
2941+
</listitem>
2942+
<listitem>
2943+
<para>
2944+
<literal>I</literal> treats the argument value as an SQL
2945+
identifier, double-quoting it if necessary.
2946+
It is an error for the value to be null.
2947+
</para>
2948+
</listitem>
2949+
<listitem>
2950+
<para>
2951+
<literal>L</literal> quotes the argument value as an SQL literal.
2952+
A null value is displayed as the string <literal>NULL</>, without
2953+
quotes.
2954+
</para>
2955+
</listitem>
2956+
</itemizedlist>
2957+
</para>
2958+
</listitem>
2959+
</varlistentry>
2960+
</variablelist>
2961+
</para>
2962+
2963+
<para>
2964+
In addition to the format specifiers described above, the special sequence
2965+
<literal>%%</> may be used to output a literal <literal>%</> character.
2966+
</para>
2967+
2968+
<para>
2969+
Here are some examples of the basic format conversions:
2970+
2971+
<screen>
2972+
SELECT format('Hello %s', 'World');
2973+
<lineannotation>Result: </lineannotation><computeroutput>Hello World</computeroutput>
2974+
2975+
SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
2976+
<lineannotation>Result: </><computeroutput>Testing one, two, three, %</>
2977+
2978+
SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
2979+
<lineannotation>Result: </lineannotation><computeroutput>INSERT INTO "Foo bar" VALUES('O''Reilly')</computeroutput>
2980+
2981+
SELECT format('INSERT INTO %I VALUES(%L)', 'locations', E'C:\\Program Files');
2982+
<lineannotation>Result: </lineannotation><computeroutput>INSERT INTO locations VALUES(E'C:\\Program Files')</computeroutput>
2983+
</screen>
2984+
</para>
2985+
2986+
<para>
2987+
Here are examples using <replaceable>width</replaceable> fields
2988+
and the <literal>-</> flag:
2989+
2990+
<screen>
2991+
SELECT format('|%10s|', 'foo');
2992+
<lineannotation>Result: </><computeroutput>| foo|</>
2993+
2994+
SELECT format('|%-10s|', 'foo');
2995+
<lineannotation>Result: </><computeroutput>|foo |</>
2996+
2997+
SELECT format('|%*s|', 10, 'foo');
2998+
<lineannotation>Result: </><computeroutput>| foo|</>
2999+
3000+
SELECT format('|%*s|', -10, 'foo');
3001+
<lineannotation>Result: </><computeroutput>|foo |</>
3002+
3003+
SELECT format('|%-*s|', 10, 'foo');
3004+
<lineannotation>Result: </><computeroutput>|foo |</>
3005+
3006+
SELECT format('|%-*s|', -10, 'foo');
3007+
<lineannotation>Result: </><computeroutput>|foo |</>
3008+
</screen>
3009+
</para>
3010+
3011+
<para>
3012+
These examples show use of <replaceable>position</> fields:
3013+
3014+
<screen>
3015+
SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
3016+
<lineannotation>Result: </><computeroutput>Testing three, two, one</>
3017+
3018+
SELECT format('|%*2$s|', 'foo', 10, 'bar');
3019+
<lineannotation>Result: </><computeroutput>| bar|</>
3020+
3021+
SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
3022+
<lineannotation>Result: </><computeroutput>| foo|</>
3023+
</screen>
3024+
</para>
3025+
3026+
<para>
3027+
Unlike the standard C function <function>sprintf</>,
3028+
<productname>PostgreSQL</>'s <function>format</> function allows format
3029+
specifiers with and without <replaceable>position</> fields to be mixed
3030+
in the same format string. A format specifier without a
3031+
<replaceable>position</> field always uses the next argument after the
3032+
last argument consumed.
3033+
In addition, the <function>format</> function does not require all
3034+
function arguments to be used in the format string.
3035+
For example:
3036+
3037+
<screen>
3038+
SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
3039+
<lineannotation>Result: </><computeroutput>Testing three, two, three</>
3040+
</screen>
3041+
</para>
3042+
3043+
<para>
3044+
The <literal>%I</> and <literal>%L</> format specifiers are particularly
3045+
useful for safely constructing dynamic SQL statements. See
3046+
<xref linkend="plpgsql-quote-literal-example">.
3047+
</para>
3048+
</sect2>
3049+
28503050
</sect1>
28513051

28523052

0 commit comments

Comments
 (0)