<!-- doc/src/sgml/func.sgml -->
<chapter id="functions">
<title>Functions and Operators</title>
<indexterm zone="functions">
<primary>function</primary>
</indexterm>
<indexterm zone="functions">
<primary>operator</primary>
</indexterm>
<para>
<productname>PostgreSQL</productname> provides a large number of
functions and operators for the built-in data types. Users can also
define their own functions and operators, as described in
<xref linkend="server-programming"/>. The
<application>psql</application> commands <command>\df</command> and
<command>\do</command> can be used to list all
available functions and operators, respectively.
</para>
<para>
If you are concerned about portability then note that most of
the functions and operators described in this chapter, with the
exception of the most trivial arithmetic and comparison operators
and some explicitly marked functions, are not specified by the
<acronym>SQL</acronym> standard. Some of this extended functionality
is present in other <acronym>SQL</acronym> database management
systems, and in many cases this functionality is compatible and
consistent between the various implementations. This chapter is also
not exhaustive; additional functions appear in relevant sections of
the manual.
</para>
<sect1 id="functions-logical">
<title>Logical Operators</title>
<indexterm zone="functions-logical">
<primary>operator</primary>
<secondary>logical</secondary>
</indexterm>
<indexterm>
<primary>Boolean</primary>
<secondary>operators</secondary>
<see>operators, logical</see>
</indexterm>
<para>
The usual logical operators are available:
<indexterm>
<primary>AND (operator)</primary>
</indexterm>
<indexterm>
<primary>OR (operator)</primary>
</indexterm>
<indexterm>
<primary>NOT (operator)</primary>
</indexterm>
<indexterm>
<primary>conjunction</primary>
</indexterm>
<indexterm>
<primary>disjunction</primary>
</indexterm>
<indexterm>
<primary>negation</primary>
</indexterm>
<simplelist>
<member><literal>AND</literal></member>
<member><literal>OR</literal></member>
<member><literal>NOT</literal></member>
</simplelist>
<acronym>SQL</acronym> uses a three-valued logic system with true,
false, and <literal>null</literal>, which represents <quote>unknown</quote>.
Observe the following truth tables:
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry><replaceable>a</replaceable></entry>
<entry><replaceable>b</replaceable></entry>
<entry><replaceable>a</replaceable> AND <replaceable>b</replaceable></entry>
<entry><replaceable>a</replaceable> OR <replaceable>b</replaceable></entry>
</row>
</thead>
<tbody>
<row>
<entry>TRUE</entry>
<entry>TRUE</entry>
<entry>TRUE</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>TRUE</entry>
<entry>FALSE</entry>
<entry>FALSE</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>TRUE</entry>
<entry>NULL</entry>
<entry>NULL</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>FALSE</entry>
<entry>FALSE</entry>
<entry>FALSE</entry>
<entry>FALSE</entry>
</row>
<row>
<entry>FALSE</entry>
<entry>NULL</entry>
<entry>FALSE</entry>
<entry>NULL</entry>
</row>
<row>
<entry>NULL</entry>
<entry>NULL</entry>
<entry>NULL</entry>
<entry>NULL</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry><replaceable>a</replaceable></entry>
<entry>NOT <replaceable>a</replaceable></entry>
</row>
</thead>
<tbody>
<row>
<entry>TRUE</entry>
<entry>FALSE</entry>
</row>
<row>
<entry>FALSE</entry>
<entry>TRUE</entry>
</row>
<row>
<entry>NULL</entry>
<entry>NULL</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
The operators <literal>AND</literal> and <literal>OR</literal> are
commutative, that is, you can switch the left and right operand
without affecting the result. But see <xref
linkend="syntax-express-eval"/> for more information about the
order of evaluation of subexpressions.
</para>
</sect1>
<sect1 id="functions-comparison">
<title>Comparison Functions and Operators</title>
<indexterm zone="functions-comparison">
<primary>comparison</primary>
<secondary>operators</secondary>
</indexterm>
<para>
The usual comparison operators are available, as shown in <xref
linkend="functions-comparison-op-table"/>.
</para>
<table id="functions-comparison-op-table">
<title>Comparison Operators</title>
<tgroup cols="2">
<thead>
<row>
<entry>Operator</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal><</literal> </entry>
<entry>less than</entry>
</row>
<row>
<entry> <literal>></literal> </entry>
<entry>greater than</entry>
</row>
<row>
<entry> <literal><=</literal> </entry>
<entry>less than or equal to</entry>
</row>
<row>
<entry> <literal>>=</literal> </entry>
<entry>greater than or equal to</entry>
</row>
<row>
<entry> <literal>=</literal> </entry>
<entry>equal</entry>
</row>
<row>
<entry> <literal><></literal> or <literal>!=</literal> </entry>
<entry>not equal</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
The <literal>!=</literal> operator is converted to
<literal><></literal> in the parser stage. It is not
possible to implement <literal>!=</literal> and
<literal><></literal> operators that do different things.
</para>
</note>
<para>
Comparison operators are available for all relevant data types.
All comparison operators are binary operators that
return values of type <type>boolean</type>; expressions like
<literal>1 < 2 < 3</literal> are not valid (because there is
no <literal><</literal> operator to compare a Boolean value with
<literal>3</literal>).
</para>
<para>
There are also some comparison predicates, as shown in <xref
linkend="functions-comparison-pred-table"/>. These behave much like
operators, but have special syntax mandated by the SQL standard.
</para>
<table id="functions-comparison-pred-table">
<title>Comparison Predicates</title>
<tgroup cols="2">
<thead>
<row>
<entry>Predicate</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <replaceable>a</replaceable> <literal>BETWEEN</literal> <replaceable>x</replaceable> <literal>AND</literal> <replaceable>y</replaceable> </entry>
<entry>between</entry>
</row>
<row>
<entry> <replaceable>a</replaceable> <literal>NOT BETWEEN</literal> <replaceable>x</replaceable> <literal>AND</literal> <replaceable>y</replaceable> </entry>
<entry>not between</entry>
</row>
<row>
<entry> <replaceable>a</replaceable> <literal>BETWEEN SYMMETRIC</literal> <replaceable>x</replaceable> <literal>AND</literal> <replaceable>y</replaceable> </entry>
<entry>between, after sorting the comparison values</entry>
</row>
<row>
<entry> <replaceable>a</replaceable> <literal>NOT BETWEEN SYMMETRIC</literal> <replaceable>x</replaceable> <literal>AND</literal> <replaceable>y</replaceable> </entry>
<entry>not between, after sorting the comparison values</entry>
</row>
<row>
<entry> <replaceable>a</replaceable> <literal>IS DISTINCT FROM</literal> <replaceable>b</replaceable> </entry>
<entry>not equal, treating null like an ordinary value</entry>
</row>
<row>
<entry><replaceable>a</replaceable> <literal>IS NOT DISTINCT FROM</literal> <replaceable>b</replaceable></entry>
<entry>equal, treating null like an ordinary value</entry>
</row>
<row>
<entry> <replaceable>expression</replaceable> <literal>IS NULL</literal> </entry>
<entry>is null</entry>
</row>
<row>
<entry> <replaceable>expression</replaceable> <literal>IS NOT NULL</literal> </entry>
<entry>is not null</entry>
</row>
<row>
<entry> <replaceable>expression</replaceable> <literal>ISNULL</literal> </entry>
<entry>is null (nonstandard syntax)</entry>
</row>
<row>
<entry> <replaceable>expression</replaceable> <literal>NOTNULL</literal> </entry>
<entry>is not null (nonstandard syntax)</entry>
</row>
<row>
<entry> <replaceable>boolean_expression</replaceable> <literal>IS TRUE</literal> </entry>
<entry>is true</entry>
</row>
<row>
<entry> <replaceable>boolean_expression</replaceable> <literal>IS NOT TRUE</literal> </entry>
<entry>is false or unknown</entry>
</row>
<row>
<entry> <replaceable>boolean_expression</replaceable> <literal>IS FALSE</literal> </entry>
<entry>is false</entry>
</row>
<row>
<entry> <replaceable>boolean_expression</replaceable> <literal>IS NOT FALSE</literal> </entry>
<entry>is true or unknown</entry>
</row>
<row>
<entry> <replaceable>boolean_expression</replaceable> <literal>IS UNKNOWN</literal> </entry>
<entry>is unknown</entry>
</row>
<row>
<entry> <replaceable>boolean_expression</replaceable> <literal>IS NOT UNKNOWN</literal> </entry>
<entry>is true or false</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<indexterm>
<primary>BETWEEN</primary>
</indexterm>
The <token>BETWEEN</token> predicate simplifies range tests:
<synopsis>
<replaceable>a</replaceable> BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
</synopsis>
is equivalent to
<synopsis>
<replaceable>a</replaceable> >= <replaceable>x</replaceable> AND <replaceable>a</replaceable> <= <replaceable>y</replaceable>
</synopsis>
Notice that <token>BETWEEN</token> treats the endpoint values as included
in the range.
<literal>NOT BETWEEN</literal> does the opposite comparison:
<synopsis>
<replaceable>a</replaceable> NOT BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
</synopsis>
is equivalent to
<synopsis>
<replaceable>a</replaceable> < <replaceable>x</replaceable> OR <replaceable>a</replaceable> > <replaceable>y</replaceable>
</synopsis>
<indexterm>
<primary>BETWEEN SYMMETRIC</primary>
</indexterm>
<literal>BETWEEN SYMMETRIC</literal> is like <literal>BETWEEN</literal>
except there is no requirement that the argument to the left of
<literal>AND</literal> be less than or equal to the argument on the right.
If it is not, those two arguments are automatically swapped, so that
a nonempty range is always implied.
</para>
<para>
<indexterm>
<primary>IS DISTINCT FROM</primary>
</indexterm>
<indexterm>
<primary>IS NOT DISTINCT FROM</primary>
</indexterm>
Ordinary comparison operators yield null (signifying <quote>unknown</quote>),
not true or false, when either input is null. For example,
<literal>7 = NULL</literal> yields null, as does <literal>7 <> NULL</literal>. When
this behavior is not suitable, use the
<literal>IS <optional> NOT </optional> DISTINCT FROM</literal> predicates:
<synopsis>
<replaceable>a</replaceable> IS DISTINCT FROM <replaceable>b</replaceable>
<replaceable>a</replaceable> IS NOT DISTINCT FROM <replaceable>b</replaceable>
</synopsis>
For non-null inputs, <literal>IS DISTINCT FROM</literal> is
the same as the <literal><></literal> operator. However, if both
inputs are null it returns false, and if only one input is
null it returns true. Similarly, <literal>IS NOT DISTINCT
FROM</literal> is identical to <literal>=</literal> for non-null
inputs, but it returns true when both inputs are null, and false when only
one input is null. Thus, these predicates effectively act as though null
were a normal data value, rather than <quote>unknown</quote>.
</para>
<para>
<indexterm>
<primary>IS NULL</primary>
</indexterm>
<indexterm>
<primary>IS NOT NULL</primary>
</indexterm>
<indexterm>
<primary>ISNULL</primary>
</indexterm>
<indexterm>
<primary>NOTNULL</primary>
</indexterm>
To check whether a value is or is not null, use the predicates:
<synopsis>
<replaceable>expression</replaceable> IS NULL
<replaceable>expression</replaceable> IS NOT NULL
</synopsis>
or the equivalent, but nonstandard, predicates:
<synopsis>
<replaceable>expression</replaceable> ISNULL
<replaceable>expression</replaceable> NOTNULL
</synopsis>
<indexterm><primary>null value</primary><secondary>comparing</secondary></indexterm>
</para>
<para>
Do <emphasis>not</emphasis> write
<literal><replaceable>expression</replaceable> = NULL</literal>
because <literal>NULL</literal> is not <quote>equal to</quote>
<literal>NULL</literal>. (The null value represents an unknown value,
and it is not known whether two unknown values are equal.)
</para>
<tip>
<para>
Some applications might expect that
<literal><replaceable>expression</replaceable> = NULL</literal>
returns true if <replaceable>expression</replaceable> evaluates to
the null value. It is highly recommended that these applications
be modified to comply with the SQL standard. However, if that
cannot be done the <xref linkend="guc-transform-null-equals"/>
configuration variable is available. If it is enabled,
<productname>PostgreSQL</productname> will convert <literal>x =
NULL</literal> clauses to <literal>x IS NULL</literal>.
</para>
</tip>
<para>
If the <replaceable>expression</replaceable> is row-valued, then
<literal>IS NULL</literal> is true when the row expression itself is null
or when all the row's fields are null, while
<literal>IS NOT NULL</literal> is true when the row expression itself is non-null
and all the row's fields are non-null. Because of this behavior,
<literal>IS NULL</literal> and <literal>IS NOT NULL</literal> do not always return
inverse results for row-valued expressions; in particular, a row-valued
expression that contains both null and non-null fields will return false
for both tests. In some cases, it may be preferable to
write <replaceable>row</replaceable> <literal>IS DISTINCT FROM NULL</literal>
or <replaceable>row</replaceable> <literal>IS NOT DISTINCT FROM NULL</literal>,
which will simply check whether the overall row value is null without any
additional tests on the row fields.
</para>
<para>
<indexterm>
<primary>IS TRUE</primary>
</indexterm>
<indexterm>
<primary>IS NOT TRUE</primary>
</indexterm>
<indexterm>
<primary>IS FALSE</primary>
</indexterm>
<indexterm>
<primary>IS NOT FALSE</primary>
</indexterm>
<indexterm>
<primary>IS UNKNOWN</primary>
</indexterm>
<indexterm>
<primary>IS NOT UNKNOWN</primary>
</indexterm>
Boolean values can also be tested using the predicates
<synopsis>
<replaceable>boolean_expression</replaceable> IS TRUE
<replaceable>boolean_expression</replaceable> IS NOT TRUE
<replaceable>boolean_expression</replaceable> IS FALSE
<replaceable>boolean_expression</replaceable> IS NOT FALSE
<replaceable>boolean_expression</replaceable> IS UNKNOWN
<replaceable>boolean_expression</replaceable> IS NOT UNKNOWN
</synopsis>
These will always return true or false, never a null value, even when the
operand is null.
A null input is treated as the logical value <quote>unknown</quote>.
Notice that <literal>IS UNKNOWN</literal> and <literal>IS NOT UNKNOWN</literal> are
effectively the same as <literal>IS NULL</literal> and
<literal>IS NOT NULL</literal>, respectively, except that the input
expression must be of Boolean type.
</para>
<!-- IS OF does not conform to the ISO SQL behavior, so it is undocumented here
<para>
<indexterm>
<primary>IS OF</primary>
</indexterm>
<indexterm>
<primary>IS NOT OF</primary>
</indexterm>
It is possible to check the data type of an expression using the
predicates
<synopsis>
<replaceable>expression</replaceable> IS OF (typename, ...)
<replaceable>expression</replaceable> IS NOT OF (typename, ...)
</synopsis>
They return a boolean value based on whether the expression's data
type is one of the listed data types.
</para>
-->
<para>
Some comparison-related functions are also available, as shown in <xref
linkend="functions-comparison-func-table"/>.
</para>
<table id="functions-comparison-func-table">
<title>Comparison Functions</title>
<tgroup cols="4">
<thead>
<row>
<entry>Function</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Example Result</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<indexterm>
<primary>num_nonnulls</primary>
</indexterm>
<literal>num_nonnulls(VARIADIC "any")</literal>
</entry>
<entry>returns the number of non-null arguments</entry>
<entry><literal>num_nonnulls(1, NULL, 2)</literal></entry>
<entry><literal>2</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>num_nulls</primary>
</indexterm>
<literal>num_nulls(VARIADIC "any")</literal>
</entry>
<entry>returns the number of null arguments</entry>
<entry><literal>num_nulls(1, NULL, 2)</literal></entry>
<entry><literal>1</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="functions-math">
<title>Mathematical Functions and Operators</title>
<para>
Mathematical operators are provided for many
<productname>PostgreSQL</productname> types. For types without
standard mathematical conventions
(e.g., date/time types) we
describe the actual behavior in subsequent sections.
</para>
<para>
<xref linkend="functions-math-op-table"/> shows the available mathematical operators.
</para>
<table id="functions-math-op-table">
<title>Mathematical Operators</title>
<tgroup cols="4">
<thead>
<row>
<entry>Operator</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>+</literal> </entry>
<entry>addition</entry>
<entry><literal>2 + 3</literal></entry>
<entry><literal>5</literal></entry>
</row>
<row>
<entry> <literal>-</literal> </entry>
<entry>subtraction</entry>
<entry><literal>2 - 3</literal></entry>
<entry><literal>-1</literal></entry>
</row>
<row>
<entry> <literal>*</literal> </entry>
<entry>multiplication</entry>
<entry><literal>2 * 3</literal></entry>
<entry><literal>6</literal></entry>
</row>
<row>
<entry> <literal>/</literal> </entry>
<entry>division (integer division truncates the result)</entry>
<entry><literal>4 / 2</literal></entry>
<entry><literal>2</literal></entry>
</row>
<row>
<entry> <literal>%</literal> </entry>
<entry>modulo (remainder)</entry>
<entry><literal>5 % 4</literal></entry>
<entry><literal>1</literal></entry>
</row>
<row>
<entry> <literal>^</literal> </entry>
<entry>exponentiation (associates left to right)</entry>
<entry><literal>2.0 ^ 3.0</literal></entry>
<entry><literal>8</literal></entry>
</row>
<row>
<entry> <literal>|/</literal> </entry>
<entry>square root</entry>
<entry><literal>|/ 25.0</literal></entry>
<entry><literal>5</literal></entry>
</row>
<row>
<entry> <literal>||/</literal> </entry>
<entry>cube root</entry>
<entry><literal>||/ 27.0</literal></entry>
<entry><literal>3</literal></entry>
</row>
<row>
<entry> <literal>!</literal> </entry>
<entry>factorial</entry>
<entry><literal>5 !</literal></entry>
<entry><literal>120</literal></entry>
</row>
<row>
<entry> <literal>!!</literal> </entry>
<entry>factorial (prefix operator)</entry>
<entry><literal>!! 5</literal></entry>
<entry><literal>120</literal></entry>
</row>
<row>
<entry> <literal>@</literal> </entry>
<entry>absolute value</entry>
<entry><literal>@ -5.0</literal></entry>
<entry><literal>5</literal></entry>
</row>
<row>
<entry> <literal>&</literal> </entry>
<entry>bitwise AND</entry>
<entry><literal>91 & 15</literal></entry>
<entry><literal>11</literal></entry>
</row>
<row>
<entry> <literal>|</literal> </entry>
<entry>bitwise OR</entry>
<entry><literal>32 | 3</literal></entry>
<entry><literal>35</literal></entry>
</row>
<row>
<entry> <literal>#</literal> </entry>
<entry>bitwise XOR</entry>
<entry><literal>17 # 5</literal></entry>
<entry><literal>20</literal></entry>
</row>
<row>
<entry> <literal>~</literal> </entry>
<entry>bitwise NOT</entry>
<entry><literal>~1</literal></entry>
<entry><literal>-2</literal></entry>
</row>
<row>
<entry> <literal><<</literal> </entry>
<entry>bitwise shift left</entry>
<entry><literal>1 << 4</literal></entry>
<entry><literal>16</literal></entry>
</row>
<row>
<entry> <literal>>></literal> </entry>
<entry>bitwise shift right</entry>
<entry><literal>8 >> 2</literal></entry>
<entry><literal>2</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The bitwise operators work only on integral data types, whereas
the others are available for all numeric data types. The bitwise
operators are also available for the bit
string types <type>bit</type> and <type>bit varying</type>, as
shown in <xref linkend="functions-bit-string-op-table"/>.
</para>
<para>
<xref linkend="functions-math-func-table"/> shows the available
mathematical functions. In the table, <literal>dp</literal>
indicates <type>double precision</type>. Many of these functions
are provided in multiple forms with different argument types.
Except where noted, any given form of a function returns the same
data type as its argument.
The functions working with <type>double precision</type> data are mostly
implemented on top of the host system's C library; accuracy and behavior in
boundary cases can therefore vary depending on the host system.
</para>
<table id="functions-math-func-table">
<title>Mathematical Functions</title>
<tgroup cols="5">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<indexterm>
<primary>abs</primary>
</indexterm>
<literal><function>abs(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>absolute value</entry>
<entry><literal>abs(-17.4)</literal></entry>
<entry><literal>17.4</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>cbrt</primary>
</indexterm>
<literal><function>cbrt(<type>dp</type>)</function></literal>
</entry>
<entry><type>dp</type></entry>
<entry>cube root</entry>
<entry><literal>cbrt(27.0)</literal></entry>
<entry><literal>3</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>ceil</primary>
</indexterm>
<literal><function>ceil(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>nearest integer greater than or equal to argument</entry>
<entry><literal>ceil(-42.8)</literal></entry>
<entry><literal>-42</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>ceiling</primary>
</indexterm>
<literal><function>ceiling(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>nearest integer greater than or equal to argument (same as <function>ceil</function>)</entry>
<entry><literal>ceiling(-95.3)</literal></entry>
<entry><literal>-95</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>degrees</primary>
</indexterm>
<literal><function>degrees(<type>dp</type>)</function></literal>
</entry>
<entry><type>dp</type></entry>
<entry>radians to degrees</entry>
<entry><literal>degrees(0.5)</literal></entry>
<entry><literal>28.6478897565412</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>div</primary>
</indexterm>
<literal><function>div(<parameter>y</parameter> <type>numeric</type>,
<parameter>x</parameter> <type>numeric</type>)</function></literal>
</entry>
<entry><type>numeric</type></entry>
<entry>integer quotient of <parameter>y</parameter>/<parameter>x</parameter></entry>
<entry><literal>div(9,4)</literal></entry>
<entry><literal>2</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>exp</primary>
</indexterm>
<literal><function>exp(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>exponential</entry>
<entry><literal>exp(1.0)</literal></entry>
<entry><literal>2.71828182845905</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>floor</primary>
</indexterm>
<literal><function>floor(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>nearest integer less than or equal to argument</entry>
<entry><literal>floor(-42.8)</literal></entry>
<entry><literal>-43</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>ln</primary>
</indexterm>
<literal><function>ln(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>natural logarithm</entry>
<entry><literal>ln(2.0)</literal></entry>
<entry><literal>0.693147180559945</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>log</primary>
</indexterm>
<literal><function>log(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>base 10 logarithm</entry>
<entry><literal>log(100.0)</literal></entry>
<entry><literal>2</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>log10</primary>
</indexterm>
<literal><function>log10(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>base 10 logarithm</entry>
<entry><literal>log10(100.0)</literal></entry>
<entry><literal>2</literal></entry>
</row>
<row>
<entry><literal><function>log(<parameter>b</parameter> <type>numeric</type>,
<parameter>x</parameter> <type>numeric</type>)</function></literal></entry>
<entry><type>numeric</type></entry>
<entry>logarithm to base <parameter>b</parameter></entry>
<entry><literal>log(2.0, 64.0)</literal></entry>
<entry><literal>6.0000000000</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>mod</primary>
</indexterm>
<literal><function>mod(<parameter>y</parameter>,
<parameter>x</parameter>)</function></literal>
</entry>
<entry>(same as argument types)</entry>
<entry>remainder of <parameter>y</parameter>/<parameter>x</parameter></entry>
<entry><literal>mod(9,4)</literal></entry>
<entry><literal>1</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>pi</primary>
</indexterm>
<literal><function>pi()</function></literal>
</entry>
<entry><type>dp</type></entry>
<entry><quote>π</quote> constant</entry>
<entry><literal>pi()</literal></entry>
<entry><literal>3.14159265358979</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>power</primary>
</indexterm>
<literal><function>power(<parameter>a</parameter> <type>dp</type>,
<parameter>b</parameter> <type>dp</type>)</function></literal>
</entry>
<entry><type>dp</type></entry>
<entry><parameter>a</parameter> raised to the power of <parameter>b</parameter></entry>
<entry><literal>power(9.0, 3.0)</literal></entry>
<entry><literal>729</literal></entry>
</row>
<row>
<entry><literal><function>power(<parameter>a</parameter> <type>numeric</type>,
<parameter>b</parameter> <type>numeric</type>)</function></literal></entry>
<entry><type>numeric</type></entry>
<entry><parameter>a</parameter> raised to the power of <parameter>b</parameter></entry>
<entry><literal>power(9.0, 3.0)</literal></entry>
<entry><literal>729</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>radians</primary>
</indexterm>
<literal><function>radians(<type>dp</type>)</function></literal>
</entry>
<entry><type>dp</type></entry>
<entry>degrees to radians</entry>
<entry><literal>radians(45.0)</literal></entry>
<entry><literal>0.785398163397448</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>round</primary>
</indexterm>
<literal><function>round(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>round to nearest integer</entry>
<entry><literal>round(42.4)</literal></entry>
<entry><literal>42</literal></entry>
</row>
<row>
<entry><literal><function>round(<parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>int</type>)</function></literal></entry>
<entry><type>numeric</type></entry>
<entry>round to <parameter>s</parameter> decimal places</entry>
<entry><literal>round(42.4382, 2)</literal></entry>
<entry><literal>42.44</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>scale</primary>
</indexterm>
<literal><function>scale(<type>numeric</type>)</function></literal>
</entry>
<entry><type>integer</type></entry>
<entry>scale of the argument (the number of decimal digits in the fractional part)</entry>
<entry><literal>scale(8.41)</literal></entry>
<entry><literal>2</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>sign</primary>
</indexterm>
<literal><function>sign(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>sign of the argument (-1, 0, +1)</entry>
<entry><literal>sign(-8.4)</literal></entry>
<entry><literal>-1</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>sqrt</primary>
</indexterm>
<literal><function>sqrt(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>square root</entry>
<entry><literal>sqrt(2.0)</literal></entry>
<entry><literal>1.4142135623731</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>trunc</primary>
</indexterm>
<literal><function>trunc(<type>dp</type> or <type>numeric</type>)</function></literal>
</entry>
<entry>(same as input)</entry>
<entry>truncate toward zero</entry>
<entry><literal>trunc(42.8)</literal></entry>
<entry><literal>42</literal></entry>
</row>
<row>
<entry><literal><function>trunc(<parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>int</type>)</function></literal></entry>
<entry><type>numeric</type></entry>
<entry>truncate to <parameter>s</parameter> decimal places</entry>
<entry><literal>trunc(42.4382, 2)</literal></entry>
<entry><literal>42.43</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>width_bucket</primary>
</indexterm>
<literal><function>width_bucket(<parameter>operand</parameter> <type>dp</type>, <parameter>b1</parameter> <type>dp</type>, <parameter>b2</parameter> <type>dp</type>, <parameter>count</parameter> <type>int</type>)</function></literal></entry>
<entry><type>int</type></entry>
<entry>return the bucket number to which <parameter>operand</parameter> would
be assigned in a histogram having <parameter>count</parameter> equal-width
buckets spanning the range <parameter>b1</parameter> to <parameter>b2</parameter>;
returns <literal>0</literal> or <literal><parameter>count</parameter>+1</literal> for
an input outside the range</entry>
<entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
<entry><literal>3</literal></entry>
</row>
<row>
<entry><literal><function>width_bucket(<parameter>operand</parameter> <type>numeric</type>, <parameter>b1</parameter> <type>numeric</type>, <parameter>b2</parameter> <type>numeric</type>, <parameter>count</parameter> <type>int</type>)</function></literal></entry>
<entry><type>int</type></entry>
<entry>return the bucket number to which <parameter>operand</parameter> would
be assigned in a histogram having <parameter>count</parameter> equal-width
buckets spanning the range <parameter>b1</parameter> to <parameter>b2</parameter>;
returns <literal>0</literal> or <literal><parameter>count</parameter>+1</literal> for
an input outside the range</entry>
<entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
<entry><literal>3</literal></entry>
</row>
<row>
<entry><literal><function>width_bucket(<parameter>operand</parameter> <type>anyelement</type>, <parameter>thresholds</parameter> <type>anyarray</type>)</function></literal></entry>
<entry><type>int</type></entry>
<entry>return the bucket number to which <parameter>operand</parameter> would
be assigned given an array listing the lower bounds of the buckets;
returns <literal>0</literal> for an input less than the first lower bound;
the <parameter>thresholds</parameter> array <emphasis>must be sorted</emphasis>,
smallest first, or unexpected results will be obtained</entry>
<entry><literal>width_bucket(now(), array['yesterday', 'today', 'tomorrow']::timestamptz[])</literal></entry>
<entry><literal>2</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="functions-math-random-table"/> shows functions for
generating random numbers.
</para>
<table id="functions-math-random-table">
<title>Random Functions</title>
<tgroup cols="3">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<indexterm>
<primary>random</primary>
</indexterm>
<literal><function>random()</function></literal>
</entry>
<entry><type>dp</type></entry>
<entry>random value in the range 0.0 <= x < 1.0</entry>
</row>
<row>
<entry>
<indexterm>
<primary>setseed</primary>
</indexterm>
<literal><function>setseed(<type>dp</type>)</function></literal>
</entry>
<entry><type>void</type></entry>
<entry>set seed for subsequent <literal>random()</literal> calls (value between -1.0 and
1.0, inclusive)</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The <function>random()</function> function uses a simple linear
congruential algorithm. It is fast but not suitable for cryptographic
applications; see the <xref linkend="pgcrypto"/> module for a more
secure alternative.
If <function>setseed()</function> is called, the results of
subsequent <function>random()</function> calls in the current session are
repeatable by re-issuing <function>setseed()</function> with the same
argument.
</para>
<para>
<xref linkend="functions-math-trig-table"/> shows the
available trigonometric functions. All these functions
take arguments and return values of type <type>double
precision</type>. Each of the trigonometric functions comes in
two variants, one that measures angles in radians and one that
measures angles in degrees.
</para>
<table id="functions-math-trig-table">
<title>Trigonometric Functions</title>
<tgroup cols="3">
<thead>
<row>
<entry>Function (radians)</entry>
<entry>Function (degrees)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<indexterm>
<primary>acos</primary>
</indexterm><literal><function>acos(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>acosd</primary>
</indexterm><literal><function>acosd(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>inverse cosine</entry>
</row>
<row>
<entry>
<indexterm>
<primary>asin</primary>
</indexterm>
<literal><function>asin(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>asind</primary>
</indexterm>
<literal><function>asind(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>inverse sine</entry>
</row>
<row>
<entry>
<indexterm>
<primary>atan</primary>
</indexterm>
<literal><function>atan(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>atand</primary>
</indexterm>
<literal><function>atand(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>inverse tangent</entry>
</row>
<row>
<entry>
<indexterm>
<primary>atan2</primary>
</indexterm>
<literal><function>atan2(<replaceable>y</replaceable>,
<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>atan2d</primary>
</indexterm>
<literal><function>atan2d(<replaceable>y</replaceable>,
<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>inverse tangent of
<literal><replaceable>y</replaceable>/<replaceable>x</replaceable></literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>cos</primary>
</indexterm>
<literal><function>cos(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>cosd</primary>
</indexterm>
<literal><function>cosd(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>cosine</entry>
</row>
<row>
<entry>
<indexterm>
<primary>cot</primary>
</indexterm>
<literal><function>cot(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>cotd</primary>
</indexterm>
<literal><function>cotd(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>cotangent</entry>
</row>
<row>
<entry>
<indexterm>
<primary>sin</primary>
</indexterm>
<literal><function>sin(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>sind</primary>
</indexterm>
<literal><function>sind(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>sine</entry>
</row>
<row>
<entry>
<indexterm>
<primary>tan</primary>
</indexterm>
<literal><function>tan(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>
<indexterm>
<primary>tand</primary>
</indexterm>
<literal><function>tand(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>tangent</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
Another way to work with angles measured in degrees is to use the unit
transformation functions <literal><function>radians()</function></literal>
and <literal><function>degrees()</function></literal> shown earlier.
However, using the degree-based trigonometric functions is preferred,
as that way avoids round-off error for special cases such
as <literal>sind(30)</literal>.
</para>
</note>
<para>
<xref linkend="functions-math-hyp-table"/> shows the
available hyperbolic functions. All these functions
take arguments and return values of type <type>double
precision</type>.
</para>
<table id="functions-math-hyp-table">
<title>Hyperbolic Functions</title>
<tgroup cols="4">
<thead>
<row>
<entry>Function</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<indexterm>
<primary>sinh</primary>
</indexterm>
<literal><function>sinh(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>hyperbolic sine</entry>
<entry><literal>sinh(0)</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>cosh</primary>
</indexterm>
<literal><function>cosh(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>hyperbolic cosine</entry>
<entry><literal>cosh(0)</literal></entry>
<entry><literal>1</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>tanh</primary>
</indexterm>
<literal><function>tanh(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>hyperbolic tangent</entry>
<entry><literal>tanh(0)</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>asinh</primary>
</indexterm>
<literal><function>asinh(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>inverse hyperbolic sine</entry>
<entry><literal>asinh(0)</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>acosh</primary>
</indexterm>
<literal><function>acosh(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>inverse hyperbolic cosine</entry>
<entry><literal>acosh(1)</literal></entry>
<entry><literal>0</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>atanh</primary>
</indexterm>
<literal><function>atanh(<replaceable>x</replaceable>)</function></literal>
</entry>
<entry>inverse hyperbolic tangent</entry>
<entry><literal>atanh(0)</literal></entry>
<entry><literal>0</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
<sect1 id="functions-string">
<title>String Functions and Operators</title>
<para>
This section describes functions and operators for examining and
manipulating string values. Strings in this context include values
of the types <type>character</type>, <type>character varying</type>,
and <type>text</type>. Unless otherwise noted, all
of the functions listed below work on all of these types, but be
wary of potential effects of automatic space-padding when using the
<type>character</type> type. Some functions also exist
natively for the bit-string types.
</para>
<para>
<acronym>SQL</acronym> defines some string functions that use
key words, rather than commas, to separate
arguments. Details are in
<xref linkend="functions-string-sql"/>.
<productname>PostgreSQL</productname> also provides versions of these functions
that use the regular function invocation syntax
(see <xref linkend="functions-string-other"/>).
</para>
<note>
<para>
Before <productname>PostgreSQL</productname> 8.3, these functions would
silently accept values of several non-string data types as well, due to
the presence of implicit coercions from those data types to
<type>text</type>. Those coercions have been removed because they frequently
caused surprising behaviors. However, the string concatenation operator
(<literal>||</literal>) still accepts non-string input, so long as at least one
input is of a string type, as shown in <xref
linkend="functions-string-sql"/>. For other cases, insert an explicit
coercion to <type>text</type> if you need to duplicate the previous behavior.
</para>
</note>
<table id="functions-string-sql">
<title><acronym>SQL</acronym> String Functions and Operators</title>
<tgroup cols="5">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal><parameter>string</parameter> <literal>||</literal>
<parameter>string</parameter></literal></entry>
<entry> <type>text</type> </entry>
<entry>
String concatenation
<indexterm>
<primary>character string</primary>
<secondary>concatenation</secondary>
</indexterm>
</entry>
<entry><literal>'Post' || 'greSQL'</literal></entry>
<entry><literal>PostgreSQL</literal></entry>
</row>
<row>
<entry>
<literal><parameter>string</parameter> <literal>||</literal>
<parameter>non-string</parameter></literal>
or
<literal><parameter>non-string</parameter> <literal>||</literal>
<parameter>string</parameter></literal>
</entry>
<entry> <type>text</type> </entry>
<entry>
String concatenation with one non-string input
</entry>
<entry><literal>'Value: ' || 42</literal></entry>
<entry><literal>Value: 42</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>bit_length</primary>
</indexterm>
<literal><function>bit_length(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>Number of bits in string</entry>
<entry><literal>bit_length('jose')</literal></entry>
<entry><literal>32</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>char_length</primary>
</indexterm>
<literal><function>char_length(<parameter>string</parameter>)</function></literal> or <literal><function>character_length(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>
Number of characters in string
<indexterm>
<primary>character string</primary>
<secondary>length</secondary>
</indexterm>
<indexterm>
<primary>length</primary>
<secondary sortas="character string">of a character string</secondary>
<see>character string, length</see>
</indexterm>
</entry>
<entry><literal>char_length('jose')</literal></entry>
<entry><literal>4</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>lower</primary>
</indexterm>
<literal><function>lower(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>Convert string to lower case</entry>
<entry><literal>lower('TOM')</literal></entry>
<entry><literal>tom</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>octet_length</primary>
</indexterm>
<literal><function>octet_length(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>Number of bytes in string</entry>
<entry><literal>octet_length('jose')</literal></entry>
<entry><literal>4</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>overlay</primary>
</indexterm>
<literal><function>overlay(<parameter>string</parameter> placing <parameter>string</parameter> from <type>int</type> <optional>for <type>int</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Replace substring
</entry>
<entry><literal>overlay('Txxxxas' placing 'hom' from 2 for 4)</literal></entry>
<entry><literal>Thomas</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>position</primary>
</indexterm>
<literal><function>position(<parameter>substring</parameter> in <parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>Location of specified substring</entry>
<entry><literal>position('om' in 'Thomas')</literal></entry>
<entry><literal>3</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>substring</primary>
</indexterm>
<literal><function>substring(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Extract substring
</entry>
<entry><literal>substring('Thomas' from 2 for 3)</literal></entry>
<entry><literal>hom</literal></entry>
</row>
<row>
<entry><literal><function>substring(<parameter>string</parameter> from <replaceable>pattern</replaceable>)</function></literal></entry>
<entry><type>text</type></entry>
<entry>
Extract substring matching POSIX regular expression. See
<xref linkend="functions-matching"/> for more information on pattern
matching.
</entry>
<entry><literal>substring('Thomas' from '...$')</literal></entry>
<entry><literal>mas</literal></entry>
</row>
<row>
<entry><literal><function>substring(<parameter>string</parameter> from <replaceable>pattern</replaceable> for <replaceable>escape</replaceable>)</function></literal></entry>
<entry><type>text</type></entry>
<entry>
Extract substring matching <acronym>SQL</acronym> regular expression.
See <xref linkend="functions-matching"/> for more information on
pattern matching.
</entry>
<entry><literal>substring('Thomas' from '%#"o_a#"_' for '#')</literal></entry>
<entry><literal>oma</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>trim</primary>
</indexterm>
<literal><function>trim(<optional>leading | trailing | both</optional>
<optional><parameter>characters</parameter></optional> from
<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Remove the longest string containing only characters from
<parameter>characters</parameter> (a space by default) from the
start, end, or both ends (<literal>both</literal> is the default)
of <parameter>string</parameter>
</entry>
<entry><literal>trim(both 'xyz' from 'yxTomxx')</literal></entry>
<entry><literal>Tom</literal></entry>
</row>
<row>
<entry>
<literal><function>trim(<optional>leading | trailing
| both</optional> <optional>from</optional>
<parameter>string</parameter>
<optional>, <parameter>characters</parameter></optional>
)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Non-standard syntax for <function>trim()</function>
</entry>
<entry><literal>trim(both from 'yxTomxx', 'xyz')</literal></entry>
<entry><literal>Tom</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>upper</primary>
</indexterm>
<literal><function>upper(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>Convert string to upper case</entry>
<entry><literal>upper('tom')</literal></entry>
<entry><literal>TOM</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Additional string manipulation functions are available and are
listed in <xref linkend="functions-string-other"/>. Some of them are used internally to implement the
<acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-string-sql"/>.
</para>
<table id="functions-string-other">
<title>Other String Functions</title>
<tgroup cols="5">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<indexterm>
<primary>ascii</primary>
</indexterm>
<literal><function>ascii(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>
<acronym>ASCII</acronym> code of the first character of the
argument. For <acronym>UTF8</acronym> returns the Unicode code
point of the character. For other multibyte encodings, the
argument must be an <acronym>ASCII</acronym> character.
</entry>
<entry><literal>ascii('x')</literal></entry>
<entry><literal>120</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>btrim</primary>
</indexterm>
<literal><function>btrim(<parameter>string</parameter> <type>text</type>
<optional>, <parameter>characters</parameter> <type>text</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Remove the longest string consisting only of characters
in <parameter>characters</parameter> (a space by default)
from the start and end of <parameter>string</parameter>
</entry>
<entry><literal>btrim('xyxtrimyyx', 'xyz')</literal></entry>
<entry><literal>trim</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>chr</primary>
</indexterm>
<literal><function>chr(<type>int</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Character with the given code. For <acronym>UTF8</acronym> the
argument is treated as a Unicode code point. For other multibyte
encodings the argument must designate an
<acronym>ASCII</acronym> character. The NULL (0) character is not
allowed because text data types cannot store such bytes.
</entry>
<entry><literal>chr(65)</literal></entry>
<entry><literal>A</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>concat</primary>
</indexterm>
<literal><function>concat(<parameter>str</parameter> <type>"any"</type>
[, <parameter>str</parameter> <type>"any"</type> [, ...] ])</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Concatenate the text representations of all the arguments.
NULL arguments are ignored.
</entry>
<entry><literal>concat('abcde', 2, NULL, 22)</literal></entry>
<entry><literal>abcde222</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>concat_ws</primary>
</indexterm>
<literal><function>concat_ws(<parameter>sep</parameter> <type>text</type>,
<parameter>str</parameter> <type>"any"</type>
[, <parameter>str</parameter> <type>"any"</type> [, ...] ])</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Concatenate all but the first argument with separators. The first
argument is used as the separator string. NULL arguments are ignored.
</entry>
<entry><literal>concat_ws(',', 'abcde', 2, NULL, 22)</literal></entry>
<entry><literal>abcde,2,22</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>convert</primary>
</indexterm>
<literal><function>convert(<parameter>string</parameter> <type>bytea</type>,
<parameter>src_encoding</parameter> <type>name</type>,
<parameter>dest_encoding</parameter> <type>name</type>)</function></literal>
</entry>
<entry><type>bytea</type></entry>
<entry>
Convert string to <parameter>dest_encoding</parameter>. The
original encoding is specified by
<parameter>src_encoding</parameter>. The
<parameter>string</parameter> must be valid in this encoding.
Conversions can be defined by <command>CREATE CONVERSION</command>.
Also there are some predefined conversions. See <xref
linkend="conversion-names"/> for available conversions.
</entry>
<entry><literal>convert('text_in_utf8', 'UTF8', 'LATIN1')</literal></entry>
<entry><literal>text_in_utf8</literal> represented in Latin-1
encoding (ISO 8859-1)</entry>
</row>
<row>
<entry>
<indexterm>
<primary>convert_from</primary>
</indexterm>
<literal><function>convert_from(<parameter>string</parameter> <type>bytea</type>,
<parameter>src_encoding</parameter> <type>name</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Convert string to the database encoding. The original encoding
is specified by <parameter>src_encoding</parameter>. The
<parameter>string</parameter> must be valid in this encoding.
</entry>
<entry><literal>convert_from('text_in_utf8', 'UTF8')</literal></entry>
<entry><literal>text_in_utf8</literal> represented in the current database encoding</entry>
</row>
<row>
<entry>
<indexterm>
<primary>convert_to</primary>
</indexterm>
<literal><function>convert_to(<parameter>string</parameter> <type>text</type>,
<parameter>dest_encoding</parameter> <type>name</type>)</function></literal>
</entry>
<entry><type>bytea</type></entry>
<entry>
Convert string to <parameter>dest_encoding</parameter>.
</entry>
<entry><literal>convert_to('some text', 'UTF8')</literal></entry>
<entry><literal>some text</literal> represented in the UTF8 encoding</entry>
</row>
<row>
<entry>
<indexterm>
<primary>decode</primary>
</indexterm>
<literal><function>decode(<parameter>string</parameter> <type>text</type>,
<parameter>format</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>bytea</type></entry>
<entry>
Decode binary data from textual representation in <parameter>string</parameter>.
Options for <parameter>format</parameter> are same as in <function>encode</function>.
</entry>
<entry><literal>decode('MTIzAAE=', 'base64')</literal></entry>
<entry><literal>\x3132330001</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>encode</primary>
</indexterm>
<literal><function>encode(<parameter>data</parameter> <type>bytea</type>,
<parameter>format</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Encode binary data into a textual representation. Supported
formats are: <literal>base64</literal>, <literal>hex</literal>, <literal>escape</literal>.
<literal>escape</literal> converts zero bytes and high-bit-set bytes to
octal sequences (<literal>\</literal><replaceable>nnn</replaceable>) and
doubles backslashes.
</entry>
<entry><literal>encode('123\000\001', 'base64')</literal></entry>
<entry><literal>MTIzAAE=</literal></entry>
</row>
<row>
<entry id="format">
<indexterm>
<primary>format</primary>
</indexterm>
<literal><function>format</function>(<parameter>formatstr</parameter> <type>text</type>
[, <parameter>formatarg</parameter> <type>"any"</type> [, ...] ])</literal>
</entry>
<entry><type>text</type></entry>
<entry>
Format arguments according to a format string.
This function is similar to the C function <function>sprintf</function>.
See <xref linkend="functions-string-format"/>.
</entry>
<entry><literal>format('Hello %s, %1$s', 'World')</literal></entry>
<entry><literal>Hello World, World</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>initcap</primary>
</indexterm>
<literal><function>initcap(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Convert the first letter of each word to upper case and the
rest to lower case. Words are sequences of alphanumeric
characters separated by non-alphanumeric characters.
</entry>
<entry><literal>initcap('hi THOMAS')</literal></entry>
<entry><literal>Hi Thomas</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>left</primary>
</indexterm>
<literal><function>left(<parameter>str</parameter> <type>text</type>,
<parameter>n</parameter> <type>int</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Return first <replaceable>n</replaceable> characters in the string. When <replaceable>n</replaceable>
is negative, return all but last |<replaceable>n</replaceable>| characters.
</entry>
<entry><literal>left('abcde', 2)</literal></entry>
<entry><literal>ab</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>length</primary>
</indexterm>
<literal><function>length(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>
Number of characters in <parameter>string</parameter>
</entry>
<entry><literal>length('jose')</literal></entry>
<entry><literal>4</literal></entry>
</row>
<row>
<entry><literal><function>length(<parameter>string</parameter> <type>bytea</type>,
<parameter>encoding</parameter> <type>name</type> )</function></literal></entry>
<entry><type>int</type></entry>
<entry>
Number of characters in <parameter>string</parameter> in the given
<parameter>encoding</parameter>. The <parameter>string</parameter>
must be valid in this encoding.
</entry>
<entry><literal>length('jose', 'UTF8')</literal></entry>
<entry><literal>4</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>lpad</primary>
</indexterm>
<literal><function>lpad(<parameter>string</parameter> <type>text</type>,
<parameter>length</parameter> <type>int</type>
<optional>, <parameter>fill</parameter> <type>text</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Fill up the <parameter>string</parameter> to length
<parameter>length</parameter> by prepending the characters
<parameter>fill</parameter> (a space by default). If the
<parameter>string</parameter> is already longer than
<parameter>length</parameter> then it is truncated (on the
right).
</entry>
<entry><literal>lpad('hi', 5, 'xy')</literal></entry>
<entry><literal>xyxhi</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>ltrim</primary>
</indexterm>
<literal><function>ltrim(<parameter>string</parameter> <type>text</type>
<optional>, <parameter>characters</parameter> <type>text</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Remove the longest string containing only characters from
<parameter>characters</parameter> (a space by default) from the start of
<parameter>string</parameter>
</entry>
<entry><literal>ltrim('zzzytest', 'xyz')</literal></entry>
<entry><literal>test</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>md5</primary>
</indexterm>
<literal><function>md5(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Calculates the MD5 hash of <parameter>string</parameter>,
returning the result in hexadecimal
</entry>
<entry><literal>md5('abc')</literal></entry>
<entry><literal>900150983cd24fb0 d6963f7d28e17f72</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>parse_ident</primary>
</indexterm>
<literal><function>parse_ident(<parameter>qualified_identifier</parameter> <type>text</type>
[, <parameter>strictmode</parameter> <type>boolean</type> DEFAULT true ] )</function></literal>
</entry>
<entry><type>text[]</type></entry>
<entry>
Split <parameter>qualified_identifier</parameter> into an array of
identifiers, removing any quoting of individual identifiers. By
default, extra characters after the last identifier are considered an
error; but if the second parameter is <literal>false</literal>, then such
extra characters are ignored. (This behavior is useful for parsing
names for objects like functions.) Note that this function does not
truncate over-length identifiers. If you want truncation you can cast
the result to <type>name[]</type>.
</entry>
<entry><literal>parse_ident('"SomeSchema".someTable')</literal></entry>
<entry><literal>{SomeSchema,sometable}</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>pg_client_encoding</primary>
</indexterm>
<literal><function>pg_client_encoding()</function></literal>
</entry>
<entry><type>name</type></entry>
<entry>
Current client encoding name
</entry>
<entry><literal>pg_client_encoding()</literal></entry>
<entry><literal>SQL_ASCII</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>quote_ident</primary>
</indexterm>
<literal><function>quote_ident(<parameter>string</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Return the given string suitably quoted to be used as an identifier
in an <acronym>SQL</acronym> statement string.
Quotes are added only if necessary (i.e., if the string contains
non-identifier characters or would be case-folded).
Embedded quotes are properly doubled.
See also <xref linkend="plpgsql-quote-literal-example"/>.
</entry>
<entry><literal>quote_ident('Foo bar')</literal></entry>
<entry><literal>"Foo bar"</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>quote_literal</primary>
</indexterm>
<literal><function>quote_literal(<parameter>string</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Return the given string suitably quoted to be used as a string literal
in an <acronym>SQL</acronym> statement string.
Embedded single-quotes and backslashes are properly doubled.
Note that <function>quote_literal</function> returns null on null
input; if the argument might be null,
<function>quote_nullable</function> is often more suitable.
See also <xref linkend="plpgsql-quote-literal-example"/>.
</entry>
<entry><literal>quote_literal(E'O\'Reilly')</literal></entry>
<entry><literal>'O''Reilly'</literal></entry>
</row>
<row>
<entry><literal><function>quote_literal(<parameter>value</parameter> <type>anyelement</type>)</function></literal></entry>
<entry><type>text</type></entry>
<entry>
Coerce the given value to text and then quote it as a literal.
Embedded single-quotes and backslashes are properly doubled.
</entry>
<entry><literal>quote_literal(42.5)</literal></entry>
<entry><literal>'42.5'</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>quote_nullable</primary>
</indexterm>
<literal><function>quote_nullable(<parameter>string</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Return the given string suitably quoted to be used as a string literal
in an <acronym>SQL</acronym> statement string; or, if the argument
is null, return <literal>NULL</literal>.
Embedded single-quotes and backslashes are properly doubled.
See also <xref linkend="plpgsql-quote-literal-example"/>.
</entry>
<entry><literal>quote_nullable(NULL)</literal></entry>
<entry><literal>NULL</literal></entry>
</row>
<row>
<entry><literal><function>quote_nullable(<parameter>value</parameter> <type>anyelement</type>)</function></literal></entry>
<entry><type>text</type></entry>
<entry>
Coerce the given value to text and then quote it as a literal;
or, if the argument is null, return <literal>NULL</literal>.
Embedded single-quotes and backslashes are properly doubled.
</entry>
<entry><literal>quote_nullable(42.5)</literal></entry>
<entry><literal>'42.5'</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>regexp_match</primary>
</indexterm>
<literal><function>regexp_match(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal>
</entry>
<entry><type>text[]</type></entry>
<entry>
Return captured substring(s) resulting from the first match of a POSIX
regular expression to the <parameter>string</parameter>. See
<xref linkend="functions-posix-regexp"/> for more information.
</entry>
<entry><literal>regexp_match('foobarbequebaz', '(bar)(beque)')</literal></entry>
<entry><literal>{bar,beque}</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>regexp_matches</primary>
</indexterm>
<literal><function>regexp_matches(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal>
</entry>
<entry><type>setof text[]</type></entry>
<entry>
Return captured substring(s) resulting from matching a POSIX regular
expression to the <parameter>string</parameter>. See
<xref linkend="functions-posix-regexp"/> for more information.
</entry>
<entry><literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal></entry>
<entry><literal>{bar}</literal><para><literal>{baz}</literal></para> (2 rows)</entry>
</row>
<row>
<entry>
<indexterm>
<primary>regexp_replace</primary>
</indexterm>
<literal><function>regexp_replace(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Replace substring(s) matching a POSIX regular expression. See
<xref linkend="functions-posix-regexp"/> for more information.
</entry>
<entry><literal>regexp_replace('Thomas', '.[mN]a.', 'M')</literal></entry>
<entry><literal>ThM</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>regexp_split_to_array</primary>
</indexterm>
<literal><function>regexp_split_to_array(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type> ])</function></literal>
</entry>
<entry><type>text[]</type></entry>
<entry>
Split <parameter>string</parameter> using a POSIX regular expression as
the delimiter. See <xref linkend="functions-posix-regexp"/> for more
information.
</entry>
<entry><literal>regexp_split_to_array('hello world', '\s+')</literal></entry>
<entry><literal>{hello,world}</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>regexp_split_to_table</primary>
</indexterm>
<literal><function>regexp_split_to_table(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</function></literal>
</entry>
<entry><type>setof text</type></entry>
<entry>
Split <parameter>string</parameter> using a POSIX regular expression as
the delimiter. See <xref linkend="functions-posix-regexp"/> for more
information.
</entry>
<entry><literal>regexp_split_to_table('hello world', '\s+')</literal></entry>
<entry><literal>hello</literal><para><literal>world</literal></para> (2 rows)</entry>
</row>
<row>
<entry>
<indexterm>
<primary>repeat</primary>
</indexterm>
<literal><function>repeat(<parameter>string</parameter> <type>text</type>, <parameter>number</parameter> <type>int</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>Repeat <parameter>string</parameter> the specified
<parameter>number</parameter> of times</entry>
<entry><literal>repeat('Pg', 4)</literal></entry>
<entry><literal>PgPgPgPg</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>replace</primary>
</indexterm>
<literal><function>replace(<parameter>string</parameter> <type>text</type>,
<parameter>from</parameter> <type>text</type>,
<parameter>to</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>Replace all occurrences in <parameter>string</parameter> of substring
<parameter>from</parameter> with substring <parameter>to</parameter>
</entry>
<entry><literal>replace('abcdefabcdef', 'cd', 'XX')</literal></entry>
<entry><literal>abXXefabXXef</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>reverse</primary>
</indexterm>
<literal><function>reverse(<parameter>str</parameter>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Return reversed string.
</entry>
<entry><literal>reverse('abcde')</literal></entry>
<entry><literal>edcba</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>right</primary>
</indexterm>
<literal><function>right(<parameter>str</parameter> <type>text</type>,
<parameter>n</parameter> <type>int</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Return last <replaceable>n</replaceable> characters in the string. When <replaceable>n</replaceable>
is negative, return all but first |<replaceable>n</replaceable>| characters.
</entry>
<entry><literal>right('abcde', 2)</literal></entry>
<entry><literal>de</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>rpad</primary>
</indexterm>
<literal><function>rpad(<parameter>string</parameter> <type>text</type>,
<parameter>length</parameter> <type>int</type>
<optional>, <parameter>fill</parameter> <type>text</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Fill up the <parameter>string</parameter> to length
<parameter>length</parameter> by appending the characters
<parameter>fill</parameter> (a space by default). If the
<parameter>string</parameter> is already longer than
<parameter>length</parameter> then it is truncated.
</entry>
<entry><literal>rpad('hi', 5, 'xy')</literal></entry>
<entry><literal>hixyx</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>rtrim</primary>
</indexterm>
<literal><function>rtrim(<parameter>string</parameter> <type>text</type>
<optional>, <parameter>characters</parameter> <type>text</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Remove the longest string containing only characters from
<parameter>characters</parameter> (a space by default) from the end of
<parameter>string</parameter>
</entry>
<entry><literal>rtrim('testxxzx', 'xyz')</literal></entry>
<entry><literal>test</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>split_part</primary>
</indexterm>
<literal><function>split_part(<parameter>string</parameter> <type>text</type>,
<parameter>delimiter</parameter> <type>text</type>,
<parameter>field</parameter> <type>int</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>Split <parameter>string</parameter> on <parameter>delimiter</parameter>
and return the given field (counting from one)
</entry>
<entry><literal>split_part('abc~@~def~@~ghi', '~@~', 2)</literal></entry>
<entry><literal>def</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>strpos</primary>
</indexterm>
<literal><function>strpos(<parameter>string</parameter>, <parameter>substring</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>
Location of specified substring (same as
<literal>position(<parameter>substring</parameter> in
<parameter>string</parameter>)</literal>, but note the reversed
argument order)
</entry>
<entry><literal>strpos('high', 'ig')</literal></entry>
<entry><literal>2</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>substr</primary>
</indexterm>
<literal><function>substr(<parameter>string</parameter>, <parameter>from</parameter> <optional>, <parameter>count</parameter></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Extract substring (same as
<literal>substring(<parameter>string</parameter> from <parameter>from</parameter> for <parameter>count</parameter>)</literal>)
</entry>
<entry><literal>substr('alphabet', 3, 2)</literal></entry>
<entry><literal>ph</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>starts_with</primary>
</indexterm>
<literal><function>starts_with(<parameter>string</parameter>, <parameter>prefix</parameter>)</function></literal>
</entry>
<entry><type>bool</type></entry>
<entry>
Returns true if <parameter>string</parameter> starts with <parameter>prefix</parameter>.
</entry>
<entry><literal>starts_with('alphabet', 'alph')</literal></entry>
<entry><literal>t</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>to_ascii</primary>
</indexterm>
<literal><function>to_ascii(<parameter>string</parameter> <type>text</type>
<optional>, <parameter>encoding</parameter> <type>text</type></optional>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Convert <parameter>string</parameter> to <acronym>ASCII</acronym> from another encoding
(only supports conversion from <literal>LATIN1</literal>, <literal>LATIN2</literal>, <literal>LATIN9</literal>,
and <literal>WIN1250</literal> encodings)
</entry>
<entry><literal>to_ascii('Karel')</literal></entry>
<entry><literal>Karel</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>to_hex</primary>
</indexterm>
<literal><function>to_hex(<parameter>number</parameter> <type>int</type>
or <type>bigint</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>Convert <parameter>number</parameter> to its equivalent hexadecimal
representation
</entry>
<entry><literal>to_hex(2147483647)</literal></entry>
<entry><literal>7fffffff</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>translate</primary>
</indexterm>
<literal><function>translate(<parameter>string</parameter> <type>text</type>,
<parameter>from</parameter> <type>text</type>,
<parameter>to</parameter> <type>text</type>)</function></literal>
</entry>
<entry><type>text</type></entry>
<entry>
Any character in <parameter>string</parameter> that matches a
character in the <parameter>from</parameter> set is replaced by
the corresponding character in the <parameter>to</parameter>
set. If <parameter>from</parameter> is longer than
<parameter>to</parameter>, occurrences of the extra characters in
<parameter>from</parameter> are removed.
</entry>
<entry><literal>translate('12345', '143', 'ax')</literal></entry>
<entry><literal>a2x5</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The <function>concat</function>, <function>concat_ws</function> and
<function>format</function> functions are variadic, so it is possible to
pass the values to be concatenated or formatted as an array marked with
the <literal>VARIADIC</literal> keyword (see <xref
linkend="xfunc-sql-variadic-functions"/>). The array's elements are
treated as if they were separate ordinary arguments to the function.
If the variadic array argument is NULL, <function>concat</function>
and <function>concat_ws</function> return NULL, but
<function>format</function> treats a NULL as a zero-element array.
</para>
<para>
See also the aggregate function <function>string_agg</function> in
<xref linkend="functions-aggregate"/>.
</para>
<table id="conversion-names">
<title>Built-in Conversions</title>
<tgroup cols="3">
<thead>
<row>
<entry>Conversion Name
<footnote>
<para>
The conversion names follow a standard naming scheme: The
official name of the source encoding with all
non-alphanumeric characters replaced by underscores, followed
by <literal>_to_</literal>, followed by the similarly processed
destination encoding name. Therefore, the names might deviate
from the customary encoding names.
</para>
</footnote>
</entry>
<entry>Source Encoding</entry>
<entry>Destination Encoding</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>ascii_to_mic</literal></entry>
<entry><literal>SQL_ASCII</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>ascii_to_utf8</literal></entry>
<entry><literal>SQL_ASCII</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>big5_to_euc_tw</literal></entry>
<entry><literal>BIG5</literal></entry>
<entry><literal>EUC_TW</literal></entry>
</row>
<row>
<entry><literal>big5_to_mic</literal></entry>
<entry><literal>BIG5</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>big5_to_utf8</literal></entry>
<entry><literal>BIG5</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>euc_cn_to_mic</literal></entry>
<entry><literal>EUC_CN</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>euc_cn_to_utf8</literal></entry>
<entry><literal>EUC_CN</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>euc_jp_to_mic</literal></entry>
<entry><literal>EUC_JP</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>euc_jp_to_sjis</literal></entry>
<entry><literal>EUC_JP</literal></entry>
<entry><literal>SJIS</literal></entry>
</row>
<row>
<entry><literal>euc_jp_to_utf8</literal></entry>
<entry><literal>EUC_JP</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>euc_kr_to_mic</literal></entry>
<entry><literal>EUC_KR</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>euc_kr_to_utf8</literal></entry>
<entry><literal>EUC_KR</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>euc_tw_to_big5</literal></entry>
<entry><literal>EUC_TW</literal></entry>
<entry><literal>BIG5</literal></entry>
</row>
<row>
<entry><literal>euc_tw_to_mic</literal></entry>
<entry><literal>EUC_TW</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>euc_tw_to_utf8</literal></entry>
<entry><literal>EUC_TW</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>gb18030_to_utf8</literal></entry>
<entry><literal>GB18030</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>gbk_to_utf8</literal></entry>
<entry><literal>GBK</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_10_to_utf8</literal></entry>
<entry><literal>LATIN6</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_13_to_utf8</literal></entry>
<entry><literal>LATIN7</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_14_to_utf8</literal></entry>
<entry><literal>LATIN8</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_15_to_utf8</literal></entry>
<entry><literal>LATIN9</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_16_to_utf8</literal></entry>
<entry><literal>LATIN10</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_1_to_mic</literal></entry>
<entry><literal>LATIN1</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>iso_8859_1_to_utf8</literal></entry>
<entry><literal>LATIN1</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_2_to_mic</literal></entry>
<entry><literal>LATIN2</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>iso_8859_2_to_utf8</literal></entry>
<entry><literal>LATIN2</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_2_to_windows_1250</literal></entry>
<entry><literal>LATIN2</literal></entry>
<entry><literal>WIN1250</literal></entry>
</row>
<row>
<entry><literal>iso_8859_3_to_mic</literal></entry>
<entry><literal>LATIN3</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>iso_8859_3_to_utf8</literal></entry>
<entry><literal>LATIN3</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_4_to_mic</literal></entry>
<entry><literal>LATIN4</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>iso_8859_4_to_utf8</literal></entry>
<entry><literal>LATIN4</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_5_to_koi8_r</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
<entry><literal>KOI8R</literal></entry>
</row>
<row>
<entry><literal>iso_8859_5_to_mic</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>iso_8859_5_to_utf8</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_5_to_windows_1251</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
<entry><literal>WIN1251</literal></entry>
</row>
<row>
<entry><literal>iso_8859_5_to_windows_866</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
<entry><literal>WIN866</literal></entry>
</row>
<row>
<entry><literal>iso_8859_6_to_utf8</literal></entry>
<entry><literal>ISO_8859_6</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_7_to_utf8</literal></entry>
<entry><literal>ISO_8859_7</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_8_to_utf8</literal></entry>
<entry><literal>ISO_8859_8</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>iso_8859_9_to_utf8</literal></entry>
<entry><literal>LATIN5</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>johab_to_utf8</literal></entry>
<entry><literal>JOHAB</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>koi8_r_to_iso_8859_5</literal></entry>
<entry><literal>KOI8R</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
</row>
<row>
<entry><literal>koi8_r_to_mic</literal></entry>
<entry><literal>KOI8R</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>koi8_r_to_utf8</literal></entry>
<entry><literal>KOI8R</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>koi8_r_to_windows_1251</literal></entry>
<entry><literal>KOI8R</literal></entry>
<entry><literal>WIN1251</literal></entry>
</row>
<row>
<entry><literal>koi8_r_to_windows_866</literal></entry>
<entry><literal>KOI8R</literal></entry>
<entry><literal>WIN866</literal></entry>
</row>
<row>
<entry><literal>koi8_u_to_utf8</literal></entry>
<entry><literal>KOI8U</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>mic_to_ascii</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>SQL_ASCII</literal></entry>
</row>
<row>
<entry><literal>mic_to_big5</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>BIG5</literal></entry>
</row>
<row>
<entry><literal>mic_to_euc_cn</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>EUC_CN</literal></entry>
</row>
<row>
<entry><literal>mic_to_euc_jp</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>EUC_JP</literal></entry>
</row>
<row>
<entry><literal>mic_to_euc_kr</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>EUC_KR</literal></entry>
</row>
<row>
<entry><literal>mic_to_euc_tw</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>EUC_TW</literal></entry>
</row>
<row>
<entry><literal>mic_to_iso_8859_1</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>LATIN1</literal></entry>
</row>
<row>
<entry><literal>mic_to_iso_8859_2</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>LATIN2</literal></entry>
</row>
<row>
<entry><literal>mic_to_iso_8859_3</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>LATIN3</literal></entry>
</row>
<row>
<entry><literal>mic_to_iso_8859_4</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>LATIN4</literal></entry>
</row>
<row>
<entry><literal>mic_to_iso_8859_5</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
</row>
<row>
<entry><literal>mic_to_koi8_r</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>KOI8R</literal></entry>
</row>
<row>
<entry><literal>mic_to_sjis</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>SJIS</literal></entry>
</row>
<row>
<entry><literal>mic_to_windows_1250</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>WIN1250</literal></entry>
</row>
<row>
<entry><literal>mic_to_windows_1251</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>WIN1251</literal></entry>
</row>
<row>
<entry><literal>mic_to_windows_866</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
<entry><literal>WIN866</literal></entry>
</row>
<row>
<entry><literal>sjis_to_euc_jp</literal></entry>
<entry><literal>SJIS</literal></entry>
<entry><literal>EUC_JP</literal></entry>
</row>
<row>
<entry><literal>sjis_to_mic</literal></entry>
<entry><literal>SJIS</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>sjis_to_utf8</literal></entry>
<entry><literal>SJIS</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>tcvn_to_utf8</literal></entry>
<entry><literal>WIN1258</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>uhc_to_utf8</literal></entry>
<entry><literal>UHC</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>utf8_to_ascii</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>SQL_ASCII</literal></entry>
</row>
<row>
<entry><literal>utf8_to_big5</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>BIG5</literal></entry>
</row>
<row>
<entry><literal>utf8_to_euc_cn</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>EUC_CN</literal></entry>
</row>
<row>
<entry><literal>utf8_to_euc_jp</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>EUC_JP</literal></entry>
</row>
<row>
<entry><literal>utf8_to_euc_kr</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>EUC_KR</literal></entry>
</row>
<row>
<entry><literal>utf8_to_euc_tw</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>EUC_TW</literal></entry>
</row>
<row>
<entry><literal>utf8_to_gb18030</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>GB18030</literal></entry>
</row>
<row>
<entry><literal>utf8_to_gbk</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>GBK</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_1</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN1</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_10</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN6</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_13</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN7</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_14</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN8</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_15</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN9</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_16</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN10</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_2</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN2</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_3</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN3</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_4</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN4</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_5</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_6</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>ISO_8859_6</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_7</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>ISO_8859_7</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_8</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>ISO_8859_8</literal></entry>
</row>
<row>
<entry><literal>utf8_to_iso_8859_9</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>LATIN5</literal></entry>
</row>
<row>
<entry><literal>utf8_to_johab</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>JOHAB</literal></entry>
</row>
<row>
<entry><literal>utf8_to_koi8_r</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>KOI8R</literal></entry>
</row>
<row>
<entry><literal>utf8_to_koi8_u</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>KOI8U</literal></entry>
</row>
<row>
<entry><literal>utf8_to_sjis</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>SJIS</literal></entry>
</row>
<row>
<entry><literal>utf8_to_tcvn</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1258</literal></entry>
</row>
<row>
<entry><literal>utf8_to_uhc</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>UHC</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1250</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1250</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1251</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1251</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1252</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1252</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1253</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1253</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1254</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1254</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1255</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1255</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1256</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1256</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_1257</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN1257</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_866</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN866</literal></entry>
</row>
<row>
<entry><literal>utf8_to_windows_874</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>WIN874</literal></entry>
</row>
<row>
<entry><literal>windows_1250_to_iso_8859_2</literal></entry>
<entry><literal>WIN1250</literal></entry>
<entry><literal>LATIN2</literal></entry>
</row>
<row>
<entry><literal>windows_1250_to_mic</literal></entry>
<entry><literal>WIN1250</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>windows_1250_to_utf8</literal></entry>
<entry><literal>WIN1250</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>windows_1251_to_iso_8859_5</literal></entry>
<entry><literal>WIN1251</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
</row>
<row>
<entry><literal>windows_1251_to_koi8_r</literal></entry>
<entry><literal>WIN1251</literal></entry>
<entry><literal>KOI8R</literal></entry>
</row>
<row>
<entry><literal>windows_1251_to_mic</literal></entry>
<entry><literal>WIN1251</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>windows_1251_to_utf8</literal></entry>
<entry><literal>WIN1251</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>windows_1251_to_windows_866</literal></entry>
<entry><literal>WIN1251</literal></entry>
<entry><literal>WIN866</literal></entry>
</row>
<row>
<entry><literal>windows_1252_to_utf8</literal></entry>
<entry><literal>WIN1252</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>windows_1256_to_utf8</literal></entry>
<entry><literal>WIN1256</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>windows_866_to_iso_8859_5</literal></entry>
<entry><literal>WIN866</literal></entry>
<entry><literal>ISO_8859_5</literal></entry>
</row>
<row>
<entry><literal>windows_866_to_koi8_r</literal></entry>
<entry><literal>WIN866</literal></entry>
<entry><literal>KOI8R</literal></entry>
</row>
<row>
<entry><literal>windows_866_to_mic</literal></entry>
<entry><literal>WIN866</literal></entry>
<entry><literal>MULE_INTERNAL</literal></entry>
</row>
<row>
<entry><literal>windows_866_to_utf8</literal></entry>
<entry><literal>WIN866</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>windows_866_to_windows_1251</literal></entry>
<entry><literal>WIN866</literal></entry>
<entry><literal>WIN</literal></entry>
</row>
<row>
<entry><literal>windows_874_to_utf8</literal></entry>
<entry><literal>WIN874</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>euc_jis_2004_to_utf8</literal></entry>
<entry><literal>EUC_JIS_2004</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>utf8_to_euc_jis_2004</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>EUC_JIS_2004</literal></entry>
</row>
<row>
<entry><literal>shift_jis_2004_to_utf8</literal></entry>
<entry><literal>SHIFT_JIS_2004</literal></entry>
<entry><literal>UTF8</literal></entry>
</row>
<row>
<entry><literal>utf8_to_shift_jis_2004</literal></entry>
<entry><literal>UTF8</literal></entry>
<entry><literal>SHIFT_JIS_2004</literal></entry>
</row>
<row>
<entry><literal>euc_jis_2004_to_shift_jis_2004</literal></entry>
<entry><literal>EUC_JIS_2004</literal></entry>
<entry><literal>SHIFT_JIS_2004</literal></entry>
</row>
<row>
<entry><literal>shift_jis_2004_to_euc_jis_2004</literal></entry>
<entry><literal>SHIFT_JIS_2004</literal></entry>
<entry><literal>EUC_JIS_2004</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<sect2 id="functions-string-format">
<title><function>format</function></title>
<indexterm>
<primary>format</primary>
</indexterm>
<para>
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> [, <parameter>formatarg</parameter> <type>"any"</type> [, ...] ])
</synopsis>
<replaceable>formatstr</replaceable> 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 <replaceable>formatarg</replaceable> 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>
%[<replaceable>position</replaceable>][<replaceable>flags</replaceable>][<replaceable>width</replaceable>]<replaceable>type</replaceable>
</synopsis>
where the component fields are:
<variablelist>
<varlistentry>
<term><replaceable>position</replaceable> (optional)</term>
<listitem>
<para>
A string of the form <literal><replaceable>n</replaceable>$</literal> where
<replaceable>n</replaceable> is the index of the argument to print.
Index 1 means the first argument after
<replaceable>formatstr</replaceable>. If the <replaceable>position</replaceable> is
omitted, the default is to use the next argument in sequence.
</para>
</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 a minus sign
(<literal>-</literal>) which will cause the format specifier's output to be
left-justified. This has no effect unless the <replaceable>width</replaceable>
field is also specified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>width</replaceable> (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>*<replaceable>n</replaceable>$</literal> to
use the <replaceable>n</replaceable>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>(<replaceable>width</replaceable>).
</para>
</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> treats the argument value as an SQL
identifier, double-quoting it if necessary.
It is an error for the value to be null (equivalent to
<function>quote_ident</function>).
</para>
</listitem>
<listitem>
<para>
<literal>L</literal> quotes the argument value as an SQL literal.
A null value is displayed as the string <literal>NULL</literal>, without
quotes (equivalent to <function>quote_nullable</function>).
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
In addition to the format specifiers described above, the special sequence
<literal>%%</literal> may be used to output a literal <literal>%</literal> character.
</para>
<para>
Here are some examples of the basic format conversions:
<screen>
SELECT format('Hello %s', 'World');
<lineannotation>Result: </lineannotation><computeroutput>Hello World</computeroutput>
SELECT format('Testing %s, %s, %s, %%', 'one', 'two', 'three');
<lineannotation>Result: </lineannotation><computeroutput>Testing one, two, three, %</computeroutput>
SELECT format('INSERT INTO %I VALUES(%L)', 'Foo bar', E'O\'Reilly');
<lineannotation>Result: </lineannotation><computeroutput>INSERT INTO "Foo bar" VALUES('O''Reilly')</computeroutput>
SELECT format('INSERT INTO %I VALUES(%L)', 'locations', 'C:\Program Files');
<lineannotation>Result: </lineannotation><computeroutput>INSERT INTO locations VALUES('C:\Program Files')</computeroutput>
</screen>
</para>
<para>
Here are examples using <replaceable>width</replaceable> fields
and the <literal>-</literal> flag:
<screen>
SELECT format('|%10s|', 'foo');
<lineannotation>Result: </lineannotation><computeroutput>| foo|</computeroutput>
SELECT format('|%-10s|', 'foo');
<lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput>
SELECT format('|%*s|', 10, 'foo');
<lineannotation>Result: </lineannotation><computeroutput>| foo|</computeroutput>
SELECT format('|%*s|', -10, 'foo');
<lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput>
SELECT format('|%-*s|', 10, 'foo');
<lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput>
SELECT format('|%-*s|', -10, 'foo');
<lineannotation>Result: </lineannotation><computeroutput>|foo |</computeroutput>
</screen>
</para>
<para>
These examples show use of <replaceable>position</replaceable> fields:
<screen>
SELECT format('Testing %3$s, %2$s, %1$s', 'one', 'two', 'three');
<lineannotation>Result: </lineannotation><computeroutput>Testing three, two, one</computeroutput>
SELECT format('|%*2$s|', 'foo', 10, 'bar');
<lineannotation>Result: </lineannotation><computeroutput>| bar|</computeroutput>
SELECT format('|%1$*2$s|', 'foo', 10, 'bar');
<lineannotation>Result: </lineannotation><computeroutput>| foo|</computeroutput>
</screen>
</para>
<para>
Unlike the standard C function <function>sprintf</function>,
<productname>PostgreSQL</productname>'s <function>format</function> function allows format
specifiers with and without <replaceable>position</replaceable> fields to be mixed
in the same format string. A format specifier without a
<replaceable>position</replaceable> field always uses the next argument after the
last argument consumed.
In addition, the <function>format</function> function does not require all
function arguments to be used in the format string.
For example:
<screen>
SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
<lineannotation>Result: </lineannotation><computeroutput>Testing three, two, three</computeroutput>
</screen>
</para>
<para>
The <literal>%I</literal> and <literal>%L</literal> format specifiers are particularly
useful for safely constructing dynamic SQL statements. See
<xref linkend="plpgsql-quote-literal-example"/>.
</para>
</sect2>
</sect1>
<sect1 id="functions-binarystring">
<title>Binary String Functions and Operators</title>
<indexterm zone="functions-binarystring">
<primary>binary data</primary>
<secondary>functions</secondary>
</indexterm>
<para>
This section describes functions and operators for examining and
manipulating values of type <type>bytea</type>.
</para>
<para>
<acronym>SQL</acronym> defines some string functions that use
key words, rather than commas, to separate
arguments. Details are in
<xref linkend="functions-binarystring-sql"/>.
<productname>PostgreSQL</productname> also provides versions of these functions
that use the regular function invocation syntax
(see <xref linkend="functions-binarystring-other"/>).
</para>
<note>
<para>
The sample results shown on this page assume that the server parameter
<link linkend="guc-bytea-output"><varname>bytea_output</varname></link> is set
to <literal>escape</literal> (the traditional PostgreSQL format).
</para>
</note>
<table id="functions-binarystring-sql">
<title><acronym>SQL</acronym> Binary String Functions and Operators</title>
<tgroup cols="5">
<thead>
<row>
<entry>Function</entry>
<entry>Return Type</entry>
<entry>Description</entry>
<entry>Example</entry>
<entry>Result</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal><parameter>string</parameter> <literal>||</literal>
<parameter>string</parameter></literal></entry>
<entry> <type>bytea</type> </entry>
<entry>
String concatenation
<indexterm>
<primary>binary string</primary>
<secondary>concatenation</secondary>
</indexterm>
</entry>
<entry><literal>'\\Post'::bytea || '\047gres\000'::bytea</literal></entry>
<entry><literal>\\Post'gres\000</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>octet_length</primary>
</indexterm>
<literal><function>octet_length(<parameter>string</parameter>)</function></literal>
</entry>
<entry><type>int</type></entry>
<entry>Number of bytes in binary string</entry>
<entry><literal>octet_length('jo\000se'::bytea)</literal></entry>
<entry><literal>5</literal></entry>
</row>
<row>
<entry>
<indexterm>
<primary>overlay</primary>
</indexterm>
<literal><function>overlay(<parameter>string</parameter> placing <parameter>string</parameter> from <type>int
|