Home • Explore • Blog • CI
☰



postgresql
48th chunk of `doc/src/sgml/func.sgml`
f924f1a9c0fdb9db8b9e1fa1b7665594e354347c039e26ec0000000100000fa4
   The function <function>format</function> produces output formatted according to
     a format string, in a style similar to the C function
     <function>sprintf</function>.
    </para>

    <para>
<synopsis>
<function>format</function>(<parameter>formatstr</parameter> <type>text</type> <optional>, <parameter>formatarg</parameter> <type>"any"</type> <optional>, ...</optional> </optional>)
</synopsis>
     <parameter>formatstr</parameter> 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</firstterm> are
     used.  Format specifiers act as placeholders in the string, defining how
     subsequent function arguments should be formatted and inserted into the
     result.  Each <parameter>formatarg</parameter> argument is converted to text
     according to the usual output rules for its data type, and then formatted
     and inserted into the result string according to the format specifier(s).
    </para>

    <para>
     Format specifiers are introduced by a <literal>%</literal> character and have
     the form
<synopsis>
%[<parameter>position</parameter>][<parameter>flags</parameter>][<parameter>width</parameter>]<parameter>type</parameter>
</synopsis>
     where the component fields are:

     <variablelist>
      <varlistentry>
       <term><parameter>position</parameter> (optional)</term>
       <listitem>
        <para>
         A string of the form <literal><parameter>n</parameter>$</literal> where
         <parameter>n</parameter> is the index of the argument to print.
         Index 1 means the first argument after
         <parameter>formatstr</parameter>.  If the <parameter>position</parameter> is
         omitted, the default is to use the next argument in sequence.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>flags</parameter> (optional)</term>
       <listitem>
        <para>
         Additional options controlling how the format specifier's output is
         formatted.  Currently the only supported flag is a minus sign
         (<literal>-</literal>) which will cause the format specifier's output to be
         left-justified.  This has no effect unless the <parameter>width</parameter>
         field is also specified.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>width</parameter> (optional)</term>
       <listitem>
        <para>
         Specifies the <emphasis>minimum</emphasis> number of characters to use to
         display the format specifier's output.  The output is padded on the
         left or right (depending on the <literal>-</literal> flag) with spaces as
         needed to fill the width.  A too-small width does not cause
         truncation of the output, but is simply ignored.  The width may be
         specified using any of the following: a positive integer; an
         asterisk (<literal>*</literal>) to use the next function argument as the
         width; or a string of the form <literal>*<parameter>n</parameter>$</literal> to
         use the <parameter>n</parameter>th function argument as the width.
        </para>

        <para>
         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 <literal>-</literal> flag had been specified) within a
         field of length <function>abs</function>(<parameter>width</parameter>).
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><parameter>type</parameter> (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>
Title: PostgreSQL FORMAT Function Details: Syntax and Format Specifiers
Summary
This section explains the syntax and components of the `format` function in PostgreSQL. It details the structure of format specifiers, including the optional position, flags, and width, and the required type. It covers how arguments are converted to text and inserted into the result string according to the format specifiers, including options for left justification and width specification using integers or function arguments.