<!-- 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. This chapter
describes most of them, although additional special-purpose functions
appear in relevant sections of the manual. 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>
The notation used throughout this chapter to describe the argument and
result data types of a function or operator is like this:
<synopsis>
<function>repeat</function> ( <type>text</type>, <type>integer</type> ) <returnvalue>text</returnvalue>
</synopsis>
which says that the function <function>repeat</function> takes one text and
one integer argument and returns a result of type text. The right arrow
is also used to indicate the result of an example, thus:
<programlisting>
repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
</programlisting>
</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.
</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>
<synopsis>
<type>boolean</type> <literal>AND</literal> <type>boolean</type> <returnvalue>boolean</returnvalue>
<type>boolean</type> <literal>OR</literal> <type>boolean</type> <returnvalue>boolean</returnvalue>
<literal>NOT</literal> <type>boolean</type> <returnvalue>boolean</returnvalue>
</synopsis>
<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 operands
without affecting the result. (However, it is not guaranteed that
the left operand is evaluated before the right operand. 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>
<replaceable>datatype</replaceable> <literal><</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Less than</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>></literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Greater than</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal><=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Less than or equal to</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>>=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Greater than or equal to</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Equal</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal><></literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Not equal</entry>
</row>
<row>
<entry>
<replaceable>datatype</replaceable> <literal>!=</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</entry>
<entry>Not equal</entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
<literal><></literal> is the standard SQL notation for <quote>not
equal</quote>. <literal>!=</literal> is an alias, which is converted
to <literal><></literal> at a very early stage of parsing.
Hence, it is not possible to implement <literal>!=</literal>
and <literal><></literal> operators that do different things.
</para>
</note>
<para>
These comparison operators are available for all built-in data types
that have a natural ordering, including numeric, string, and date/time
types. In addition, arrays, composite types, and ranges can be compared
if their component data types are comparable.
</para>
<para>
It is usually possible to compare values of related data
types as well; for example <type>integer</type> <literal>></literal>
<type>bigint</type> will work. Some cases of this sort are implemented
directly by <quote>cross-type</quote> comparison operators, but if no
such operator is available, the parser will coerce the less-general type
to the more-general type and apply the latter's comparison operator.
</para>
<para>
As shown above, all comparison operators are binary operators that
return values of type <type>boolean</type>. Thus, 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>). Use the <literal>BETWEEN</literal> predicates
shown below to perform range tests.
</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="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Predicate
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>BETWEEN</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Between (inclusive of the range endpoints).
</para>
<para>
<literal>2 BETWEEN 1 AND 3</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>2 BETWEEN 3 AND 1</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>NOT BETWEEN</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Not between (the negation of <literal>BETWEEN</literal>).
</para>
<para>
<literal>2 NOT BETWEEN 1 AND 3</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>BETWEEN SYMMETRIC</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Between, after sorting the two endpoint values.
</para>
<para>
<literal>2 BETWEEN SYMMETRIC 3 AND 1</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>NOT BETWEEN SYMMETRIC</literal> <replaceable>datatype</replaceable> <literal>AND</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Not between, after sorting the two endpoint values.
</para>
<para>
<literal>2 NOT BETWEEN SYMMETRIC 3 AND 1</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS DISTINCT FROM</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Not equal, treating null as a comparable value.
</para>
<para>
<literal>1 IS DISTINCT FROM NULL</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para>
<para>
<literal>NULL IS DISTINCT FROM NULL</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS NOT DISTINCT FROM</literal> <replaceable>datatype</replaceable>
<returnvalue>boolean</returnvalue>
</para>
<para>
Equal, treating null as a comparable value.
</para>
<para>
<literal>1 IS NOT DISTINCT FROM NULL</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para>
<para>
<literal>NULL IS NOT DISTINCT FROM NULL</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS NULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is null.
</para>
<para>
<literal>1.5 IS NULL</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>IS NOT NULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is not null.
</para>
<para>
<literal>'null' IS NOT NULL</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>ISNULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is null (nonstandard syntax).
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>datatype</replaceable> <literal>NOTNULL</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether value is not null (nonstandard syntax).
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS TRUE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields true.
</para>
<para>
<literal>true IS TRUE</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>NULL::boolean IS TRUE</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS NOT TRUE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields false or unknown.
</para>
<para>
<literal>true IS NOT TRUE</literal>
<returnvalue>f</returnvalue>
</para>
<para>
<literal>NULL::boolean IS NOT TRUE</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS FALSE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields false.
</para>
<para>
<literal>true IS FALSE</literal>
<returnvalue>f</returnvalue>
</para>
<para>
<literal>NULL::boolean IS FALSE</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS NOT FALSE</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields true or unknown.
</para>
<para>
<literal>true IS NOT FALSE</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>NULL::boolean IS NOT FALSE</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS UNKNOWN</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields unknown.
</para>
<para>
<literal>true IS UNKNOWN</literal>
<returnvalue>f</returnvalue>
</para>
<para>
<literal>NULL::boolean IS UNKNOWN</literal>
<returnvalue>t</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>boolean</type> <literal>IS NOT UNKNOWN</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Test whether boolean expression yields true or false.
</para>
<para>
<literal>true IS NOT UNKNOWN</literal>
<returnvalue>t</returnvalue>
</para>
<para>
<literal>NULL::boolean IS NOT UNKNOWN</literal>
<returnvalue>f</returnvalue> (rather than <literal>NULL</literal>)
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<indexterm>
<primary>BETWEEN</primary>
</indexterm>
<indexterm>
<primary>BETWEEN SYMMETRIC</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>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>
The various variants of <literal>BETWEEN</literal> are implemented in
terms of the ordinary comparison operators, and therefore will work for
any data type(s) that can be compared.
</para>
<note>
<para>
The use of <literal>AND</literal> in the <literal>BETWEEN</literal>
syntax creates an ambiguity with the use of <literal>AND</literal> as a
logical operator. To resolve this, only a limited set of expression
types are allowed as the second argument of a <literal>BETWEEN</literal>
clause. If you need to write a more complex sub-expression
in <literal>BETWEEN</literal>, write parentheses around the
sub-expression.
</para>
</note>
<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. For example:
<programlisting>
SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
SELECT ROW(table.*) IS NULL FROM table; -- detect all-null rows
SELECT ROW(table.*) IS NOT NULL FROM table; -- detect all-non-null rows
SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in rows
</programlisting>
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>
<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="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>num_nonnulls</primary>
</indexterm>
<function>num_nonnulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of non-null arguments.
</para>
<para>
<literal>num_nonnulls(1, NULL, 2)</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>num_nulls</primary>
</indexterm>
<function>num_nulls</function> ( <literal>VARIADIC</literal> <type>"any"</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of null arguments.
</para>
<para>
<literal>num_nulls(1, NULL, 2)</literal>
<returnvalue>1</returnvalue>
</para></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 mathematical
operators that are available for the standard numeric types.
Unless otherwise noted, operators shown as
accepting <replaceable>numeric_type</replaceable> are available for all
the types <type>smallint</type>, <type>integer</type>,
<type>bigint</type>, <type>numeric</type>, <type>real</type>,
and <type>double precision</type>.
Operators shown as accepting <replaceable>integral_type</replaceable>
are available for the types <type>smallint</type>, <type>integer</type>,
and <type>bigint</type>.
Except where noted, each form of an operator returns the same data type
as its argument(s). Calls involving multiple argument data types, such
as <type>integer</type> <literal>+</literal> <type>numeric</type>,
are resolved by using the type appearing later in these lists.
</para>
<table id="functions-math-op-table">
<title>Mathematical Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Operator
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>numeric_type</replaceable> <literal>+</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Addition
</para>
<para>
<literal>2 + 3</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>+</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Unary plus (no operation)
</para>
<para>
<literal>+ 3.5</literal>
<returnvalue>3.5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>numeric_type</replaceable> <literal>-</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Subtraction
</para>
<para>
<literal>2 - 3</literal>
<returnvalue>-1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>-</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Negation
</para>
<para>
<literal>- (-4)</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>numeric_type</replaceable> <literal>*</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Multiplication
</para>
<para>
<literal>2 * 3</literal>
<returnvalue>6</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>numeric_type</replaceable> <literal>/</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Division (for integral types, division truncates the result towards
zero)
</para>
<para>
<literal>5.0 / 2</literal>
<returnvalue>2.5000000000000000</returnvalue>
</para>
<para>
<literal>5 / 2</literal>
<returnvalue>2</returnvalue>
</para>
<para>
<literal>(-5) / 2</literal>
<returnvalue>-2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>numeric_type</replaceable> <literal>%</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Modulo (remainder); available for <type>smallint</type>,
<type>integer</type>, <type>bigint</type>, and <type>numeric</type>
</para>
<para>
<literal>5 % 4</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>numeric</type> <literal>^</literal> <type>numeric</type>
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<type>double precision</type> <literal>^</literal> <type>double precision</type>
<returnvalue>double precision</returnvalue>
</para>
<para>
Exponentiation
</para>
<para>
<literal>2 ^ 3</literal>
<returnvalue>8</returnvalue>
</para>
<para>
Unlike typical mathematical practice, multiple uses of
<literal>^</literal> will associate left to right by default:
</para>
<para>
<literal>2 ^ 3 ^ 3</literal>
<returnvalue>512</returnvalue>
</para>
<para>
<literal>2 ^ (3 ^ 3)</literal>
<returnvalue>134217728</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>|/</literal> <type>double precision</type>
<returnvalue>double precision</returnvalue>
</para>
<para>
Square root
</para>
<para>
<literal>|/ 25.0</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>||/</literal> <type>double precision</type>
<returnvalue>double precision</returnvalue>
</para>
<para>
Cube root
</para>
<para>
<literal>||/ 64.0</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>@</literal> <replaceable>numeric_type</replaceable>
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Absolute value
</para>
<para>
<literal>@ -5.0</literal>
<returnvalue>5.0</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>integral_type</replaceable> <literal>&</literal> <replaceable>integral_type</replaceable>
<returnvalue><replaceable>integral_type</replaceable></returnvalue>
</para>
<para>
Bitwise AND
</para>
<para>
<literal>91 & 15</literal>
<returnvalue>11</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>integral_type</replaceable> <literal>|</literal> <replaceable>integral_type</replaceable>
<returnvalue><replaceable>integral_type</replaceable></returnvalue>
</para>
<para>
Bitwise OR
</para>
<para>
<literal>32 | 3</literal>
<returnvalue>35</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>integral_type</replaceable> <literal>#</literal> <replaceable>integral_type</replaceable>
<returnvalue><replaceable>integral_type</replaceable></returnvalue>
</para>
<para>
Bitwise exclusive OR
</para>
<para>
<literal>17 # 5</literal>
<returnvalue>20</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>~</literal> <replaceable>integral_type</replaceable>
<returnvalue><replaceable>integral_type</replaceable></returnvalue>
</para>
<para>
Bitwise NOT
</para>
<para>
<literal>~1</literal>
<returnvalue>-2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>integral_type</replaceable> <literal><<</literal> <type>integer</type>
<returnvalue><replaceable>integral_type</replaceable></returnvalue>
</para>
<para>
Bitwise shift left
</para>
<para>
<literal>1 << 4</literal>
<returnvalue>16</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<replaceable>integral_type</replaceable> <literal>>></literal> <type>integer</type>
<returnvalue><replaceable>integral_type</replaceable></returnvalue>
</para>
<para>
Bitwise shift right
</para>
<para>
<literal>8 >> 2</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<xref linkend="functions-math-func-table"/> shows the available
mathematical functions.
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(s); cross-type cases are resolved in the
same way as explained above for operators.
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="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>abs</primary>
</indexterm>
<function>abs</function> ( <replaceable>numeric_type</replaceable> )
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Absolute value
</para>
<para>
<literal>abs(-17.4)</literal>
<returnvalue>17.4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cbrt</primary>
</indexterm>
<function>cbrt</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Cube root
</para>
<para>
<literal>cbrt(64.0)</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ceil</primary>
</indexterm>
<function>ceil</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>ceil</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Nearest integer greater than or equal to argument
</para>
<para>
<literal>ceil(42.2)</literal>
<returnvalue>43</returnvalue>
</para>
<para>
<literal>ceil(-42.8)</literal>
<returnvalue>-42</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ceiling</primary>
</indexterm>
<function>ceiling</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>ceiling</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Nearest integer greater than or equal to argument (same
as <function>ceil</function>)
</para>
<para>
<literal>ceiling(95.3)</literal>
<returnvalue>96</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>degrees</primary>
</indexterm>
<function>degrees</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Converts radians to degrees
</para>
<para>
<literal>degrees(0.5)</literal>
<returnvalue>28.64788975654116</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>div</primary>
</indexterm>
<function>div</function> ( <parameter>y</parameter> <type>numeric</type>,
<parameter>x</parameter> <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para>
Integer quotient of <parameter>y</parameter>/<parameter>x</parameter>
(truncates towards zero)
</para>
<para>
<literal>div(9, 4)</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>erf</primary>
</indexterm>
<function>erf</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Error function
</para>
<para>
<literal>erf(1.0)</literal>
<returnvalue>0.8427007929497149</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>erfc</primary>
</indexterm>
<function>erfc</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Complementary error function (<literal>1 - erf(x)</literal>, without
loss of precision for large inputs)
</para>
<para>
<literal>erfc(1.0)</literal>
<returnvalue>0.15729920705028513</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>exp</primary>
</indexterm>
<function>exp</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>exp</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Exponential (<literal>e</literal> raised to the given power)
</para>
<para>
<literal>exp(1.0)</literal>
<returnvalue>2.7182818284590452</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-factorial">
<primary>factorial</primary>
</indexterm>
<function>factorial</function> ( <type>bigint</type> )
<returnvalue>numeric</returnvalue>
</para>
<para>
Factorial
</para>
<para>
<literal>factorial(5)</literal>
<returnvalue>120</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>floor</primary>
</indexterm>
<function>floor</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>floor</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Nearest integer less than or equal to argument
</para>
<para>
<literal>floor(42.8)</literal>
<returnvalue>42</returnvalue>
</para>
<para>
<literal>floor(-42.8)</literal>
<returnvalue>-43</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>gamma</primary>
</indexterm>
<function>gamma</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Gamma function
</para>
<para>
<literal>gamma(0.5)</literal>
<returnvalue>1.772453850905516</returnvalue>
</para>
<para>
<literal>gamma(6)</literal>
<returnvalue>120</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>gcd</primary>
</indexterm>
<function>gcd</function> ( <replaceable>numeric_type</replaceable>, <replaceable>numeric_type</replaceable> )
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Greatest common divisor (the largest positive number that divides both
inputs with no remainder); returns <literal>0</literal> if both inputs
are zero; available for <type>integer</type>, <type>bigint</type>,
and <type>numeric</type>
</para>
<para>
<literal>gcd(1071, 462)</literal>
<returnvalue>21</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lcm</primary>
</indexterm>
<function>lcm</function> ( <replaceable>numeric_type</replaceable>, <replaceable>numeric_type</replaceable> )
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Least common multiple (the smallest strictly positive number that is
an integral multiple of both inputs); returns <literal>0</literal> if
either input is zero; available for <type>integer</type>,
<type>bigint</type>, and <type>numeric</type>
</para>
<para>
<literal>lcm(1071, 462)</literal>
<returnvalue>23562</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lgamma</primary>
</indexterm>
<function>lgamma</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Natural logarithm of the absolute value of the gamma function
</para>
<para>
<literal>lgamma(1000)</literal>
<returnvalue>5905.220423209181</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ln</primary>
</indexterm>
<function>ln</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>ln</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Natural logarithm
</para>
<para>
<literal>ln(2.0)</literal>
<returnvalue>0.6931471805599453</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>log</primary>
</indexterm>
<function>log</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>log</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Base 10 logarithm
</para>
<para>
<literal>log(100)</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>log10</primary>
</indexterm>
<function>log10</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>log10</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Base 10 logarithm (same as <function>log</function>)
</para>
<para>
<literal>log10(1000)</literal>
<returnvalue>3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>log</function> ( <parameter>b</parameter> <type>numeric</type>,
<parameter>x</parameter> <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para>
Logarithm of <parameter>x</parameter> to base <parameter>b</parameter>
</para>
<para>
<literal>log(2.0, 64.0)</literal>
<returnvalue>6.0000000000000000</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>min_scale</primary>
</indexterm>
<function>min_scale</function> ( <type>numeric</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Minimum scale (number of fractional decimal digits) needed
to represent the supplied value precisely
</para>
<para>
<literal>min_scale(8.4100)</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>mod</primary>
</indexterm>
<function>mod</function> ( <parameter>y</parameter> <replaceable>numeric_type</replaceable>,
<parameter>x</parameter> <replaceable>numeric_type</replaceable> )
<returnvalue><replaceable>numeric_type</replaceable></returnvalue>
</para>
<para>
Remainder of <parameter>y</parameter>/<parameter>x</parameter>;
available for <type>smallint</type>, <type>integer</type>,
<type>bigint</type>, and <type>numeric</type>
</para>
<para>
<literal>mod(9, 4)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pi</primary>
</indexterm>
<function>pi</function> ( )
<returnvalue>double precision</returnvalue>
</para>
<para>
Approximate value of <phrase role="symbol_font">π</phrase>
</para>
<para>
<literal>pi()</literal>
<returnvalue>3.141592653589793</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>power</primary>
</indexterm>
<function>power</function> ( <parameter>a</parameter> <type>numeric</type>,
<parameter>b</parameter> <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>power</function> ( <parameter>a</parameter> <type>double precision</type>,
<parameter>b</parameter> <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
<parameter>a</parameter> raised to the power of <parameter>b</parameter>
</para>
<para>
<literal>power(9, 3)</literal>
<returnvalue>729</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>radians</primary>
</indexterm>
<function>radians</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Converts degrees to radians
</para>
<para>
<literal>radians(45.0)</literal>
<returnvalue>0.7853981633974483</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>round</primary>
</indexterm>
<function>round</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>round</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Rounds to nearest integer. For <type>numeric</type>, ties are
broken by rounding away from zero. For <type>double precision</type>,
the tie-breaking behavior is platform dependent, but
<quote>round to nearest even</quote> is the most common rule.
</para>
<para>
<literal>round(42.4)</literal>
<returnvalue>42</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>round</function> ( <parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>integer</type> )
<returnvalue>numeric</returnvalue>
</para>
<para>
Rounds <parameter>v</parameter> to <parameter>s</parameter> decimal
places. Ties are broken by rounding away from zero.
</para>
<para>
<literal>round(42.4382, 2)</literal>
<returnvalue>42.44</returnvalue>
</para>
<para>
<literal>round(1234.56, -1)</literal>
<returnvalue>1230</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>scale</primary>
</indexterm>
<function>scale</function> ( <type>numeric</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Scale of the argument (the number of decimal digits in the fractional part)
</para>
<para>
<literal>scale(8.4100)</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sign</primary>
</indexterm>
<function>sign</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>sign</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Sign of the argument (-1, 0, or +1)
</para>
<para>
<literal>sign(-8.4)</literal>
<returnvalue>-1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sqrt</primary>
</indexterm>
<function>sqrt</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>sqrt</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Square root
</para>
<para>
<literal>sqrt(2)</literal>
<returnvalue>1.4142135623730951</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>trim_scale</primary>
</indexterm>
<function>trim_scale</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para>
Reduces the value's scale (number of fractional decimal digits) by
removing trailing zeroes
</para>
<para>
<literal>trim_scale(8.4100)</literal>
<returnvalue>8.41</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>trunc</primary>
</indexterm>
<function>trunc</function> ( <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para role="func_signature">
<function>trunc</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Truncates to integer (towards zero)
</para>
<para>
<literal>trunc(42.8)</literal>
<returnvalue>42</returnvalue>
</para>
<para>
<literal>trunc(-42.8)</literal>
<returnvalue>-42</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>trunc</function> ( <parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>integer</type> )
<returnvalue>numeric</returnvalue>
</para>
<para>
Truncates <parameter>v</parameter> to <parameter>s</parameter>
decimal places
</para>
<para>
<literal>trunc(42.4382, 2)</literal>
<returnvalue>42.43</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>width_bucket</primary>
</indexterm>
<function>width_bucket</function> ( <parameter>operand</parameter> <type>numeric</type>, <parameter>low</parameter> <type>numeric</type>, <parameter>high</parameter> <type>numeric</type>, <parameter>count</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para role="func_signature">
<function>width_bucket</function> ( <parameter>operand</parameter> <type>double precision</type>, <parameter>low</parameter> <type>double precision</type>, <parameter>high</parameter> <type>double precision</type>, <parameter>count</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of the bucket in
which <parameter>operand</parameter> falls in a histogram
having <parameter>count</parameter> equal-width buckets spanning the
range <parameter>low</parameter> to <parameter>high</parameter>.
The buckets have inclusive lower bounds and exclusive upper bounds.
Returns <literal>0</literal> for an input less
than <parameter>low</parameter>,
or <literal><parameter>count</parameter>+1</literal> for an input
greater than or equal to <parameter>high</parameter>.
If <parameter>low</parameter> > <parameter>high</parameter>,
the behavior is mirror-reversed, with bucket <literal>1</literal>
now being the one just below <parameter>low</parameter>, and the
inclusive bounds now being on the upper side.
</para>
<para>
<literal>width_bucket(5.35, 0.024, 10.06, 5)</literal>
<returnvalue>3</returnvalue>
</para>
<para>
<literal>width_bucket(9, 10, 0, 10)</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>width_bucket</function> ( <parameter>operand</parameter> <type>anycompatible</type>, <parameter>thresholds</parameter> <type>anycompatiblearray</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of the bucket in
which <parameter>operand</parameter> falls given an array listing the
inclusive lower bounds of the buckets.
Returns <literal>0</literal> for an input less than the first lower
bound. <parameter>operand</parameter> and the array elements can be
of any type having standard comparison operators.
The <parameter>thresholds</parameter> array <emphasis>must be
sorted</emphasis>, smallest first, or unexpected results will be
obtained.
</para>
<para>
<literal>width_bucket(now(), array['yesterday', 'today', 'tomorrow']::timestamptz[])</literal>
<returnvalue>2</returnvalue>
</para></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="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>random</primary>
</indexterm>
<function>random</function> ( )
<returnvalue>double precision</returnvalue>
</para>
<para>
Returns a random value in the range 0.0 <= x < 1.0
</para>
<para>
<literal>random()</literal>
<returnvalue>0.897124072839091</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>random</primary>
</indexterm>
<function>random</function> ( <parameter>min</parameter> <type>integer</type>, <parameter>max</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para role="func_signature">
<function>random</function> ( <parameter>min</parameter> <type>bigint</type>, <parameter>max</parameter> <type>bigint</type> )
<returnvalue>bigint</returnvalue>
</para>
<para role="func_signature">
<function>random</function> ( <parameter>min</parameter> <type>numeric</type>, <parameter>max</parameter> <type>numeric</type> )
<returnvalue>numeric</returnvalue>
</para>
<para>
Returns a random value in the range
<parameter>min</parameter> <= x <= <parameter>max</parameter>.
For type <type>numeric</type>, the result will have the same number of
fractional decimal digits as <parameter>min</parameter> or
<parameter>max</parameter>, whichever has more.
</para>
<para>
<literal>random(1, 10)</literal>
<returnvalue>7</returnvalue>
</para>
<para>
<literal>random(-0.499, 0.499)</literal>
<returnvalue>0.347</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>random_normal</primary>
</indexterm>
<function>random_normal</function> (
<optional> <parameter>mean</parameter> <type>double precision</type>
<optional>, <parameter>stddev</parameter> <type>double precision</type> </optional></optional> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Returns a random value from the normal distribution with the given
parameters; <parameter>mean</parameter> defaults to 0.0
and <parameter>stddev</parameter> defaults to 1.0
</para>
<para>
<literal>random_normal(0.0, 1.0)</literal>
<returnvalue>0.051285419</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>setseed</primary>
</indexterm>
<function>setseed</function> ( <type>double precision</type> )
<returnvalue>void</returnvalue>
</para>
<para>
Sets the seed for subsequent <literal>random()</literal> and
<literal>random_normal()</literal> calls;
argument must be between -1.0 and 1.0, inclusive
</para>
<para>
<literal>setseed(0.12345)</literal>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The <function>random()</function> and <function>random_normal()</function>
functions listed in <xref linkend="functions-math-random-table"/> use a
deterministic pseudo-random number generator.
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 series of results of
subsequent calls to these functions in the current session
can be repeated by re-issuing <function>setseed()</function> with the same
argument.
Without any prior <function>setseed()</function> call in the same
session, the first call to any of these functions obtains a seed
from a platform-dependent source of random bits.
</para>
<para>
<xref linkend="functions-math-trig-table"/> shows the
available trigonometric functions. Each of these 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="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>acos</primary>
</indexterm>
<function>acos</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse cosine, result in radians
</para>
<para>
<literal>acos(1)</literal>
<returnvalue>0</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>acosd</primary>
</indexterm>
<function>acosd</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse cosine, result in degrees
</para>
<para>
<literal>acosd(0.5)</literal>
<returnvalue>60</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>asin</primary>
</indexterm>
<function>asin</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse sine, result in radians
</para>
<para>
<literal>asin(1)</literal>
<returnvalue>1.5707963267948966</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>asind</primary>
</indexterm>
<function>asind</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse sine, result in degrees
</para>
<para>
<literal>asind(0.5)</literal>
<returnvalue>30</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>atan</primary>
</indexterm>
<function>atan</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse tangent, result in radians
</para>
<para>
<literal>atan(1)</literal>
<returnvalue>0.7853981633974483</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>atand</primary>
</indexterm>
<function>atand</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse tangent, result in degrees
</para>
<para>
<literal>atand(1)</literal>
<returnvalue>45</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>atan2</primary>
</indexterm>
<function>atan2</function> ( <parameter>y</parameter> <type>double precision</type>,
<parameter>x</parameter> <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse tangent of
<parameter>y</parameter>/<parameter>x</parameter>,
result in radians
</para>
<para>
<literal>atan2(1, 0)</literal>
<returnvalue>1.5707963267948966</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>atan2d</primary>
</indexterm>
<function>atan2d</function> ( <parameter>y</parameter> <type>double precision</type>,
<parameter>x</parameter> <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse tangent of
<parameter>y</parameter>/<parameter>x</parameter>,
result in degrees
</para>
<para>
<literal>atan2d(1, 0)</literal>
<returnvalue>90</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cos</primary>
</indexterm>
<function>cos</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Cosine, argument in radians
</para>
<para>
<literal>cos(0)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cosd</primary>
</indexterm>
<function>cosd</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Cosine, argument in degrees
</para>
<para>
<literal>cosd(60)</literal>
<returnvalue>0.5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cot</primary>
</indexterm>
<function>cot</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Cotangent, argument in radians
</para>
<para>
<literal>cot(0.5)</literal>
<returnvalue>1.830487721712452</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cotd</primary>
</indexterm>
<function>cotd</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Cotangent, argument in degrees
</para>
<para>
<literal>cotd(45)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sin</primary>
</indexterm>
<function>sin</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Sine, argument in radians
</para>
<para>
<literal>sin(1)</literal>
<returnvalue>0.8414709848078965</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sind</primary>
</indexterm>
<function>sind</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Sine, argument in degrees
</para>
<para>
<literal>sind(30)</literal>
<returnvalue>0.5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>tan</primary>
</indexterm>
<function>tan</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Tangent, argument in radians
</para>
<para>
<literal>tan(1)</literal>
<returnvalue>1.5574077246549023</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>tand</primary>
</indexterm>
<function>tand</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Tangent, argument in degrees
</para>
<para>
<literal>tand(45)</literal>
<returnvalue>1</returnvalue>
</para></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.
</para>
<table id="functions-math-hyp-table">
<title>Hyperbolic Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sinh</primary>
</indexterm>
<function>sinh</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Hyperbolic sine
</para>
<para>
<literal>sinh(1)</literal>
<returnvalue>1.1752011936438014</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>cosh</primary>
</indexterm>
<function>cosh</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Hyperbolic cosine
</para>
<para>
<literal>cosh(0)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>tanh</primary>
</indexterm>
<function>tanh</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Hyperbolic tangent
</para>
<para>
<literal>tanh(1)</literal>
<returnvalue>0.7615941559557649</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>asinh</primary>
</indexterm>
<function>asinh</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse hyperbolic sine
</para>
<para>
<literal>asinh(1)</literal>
<returnvalue>0.881373587019543</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>acosh</primary>
</indexterm>
<function>acosh</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse hyperbolic cosine
</para>
<para>
<literal>acosh(1)</literal>
<returnvalue>0</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>atanh</primary>
</indexterm>
<function>atanh</function> ( <type>double precision</type> )
<returnvalue>double precision</returnvalue>
</para>
<para>
Inverse hyperbolic tangent
</para>
<para>
<literal>atanh(0.5)</literal>
<returnvalue>0.5493061443340548</returnvalue>
</para></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>. Except where noted, these functions and operators
are declared to accept and return type <type>text</type>. They will
interchangeably accept <type>character varying</type> arguments.
Values of type <type>character</type> will be converted
to <type>text</type> before the function or operator is applied, resulting
in stripping any trailing spaces in the <type>character</type> value.
</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>
The string concatenation operator (<literal>||</literal>) will accept
non-string input, so long as at least one input is of string type, as shown
in <xref linkend="functions-string-sql"/>. For other cases, inserting an
explicit coercion to <type>text</type> can be used to have non-string input
accepted.
</para>
</note>
<table id="functions-string-sql">
<title><acronym>SQL</acronym> String Functions and Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function/Operator
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>character string</primary>
<secondary>concatenation</secondary>
</indexterm>
<type>text</type> <literal>||</literal> <type>text</type>
<returnvalue>text</returnvalue>
</para>
<para>
Concatenates the two strings.
</para>
<para>
<literal>'Post' || 'greSQL'</literal>
<returnvalue>PostgreSQL</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>text</type> <literal>||</literal> <type>anynonarray</type>
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<type>anynonarray</type> <literal>||</literal> <type>text</type>
<returnvalue>text</returnvalue>
</para>
<para>
Converts the non-string input to text, then concatenates the two
strings. (The non-string input cannot be of an array type, because
that would create ambiguity with the array <literal>||</literal>
operators. If you want to concatenate an array's text equivalent,
cast it to <type>text</type> explicitly.)
</para>
<para>
<literal>'Value: ' || 42</literal>
<returnvalue>Value: 42</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>btrim</primary>
</indexterm>
<function>btrim</function> ( <parameter>string</parameter> <type>text</type>
<optional>, <parameter>characters</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Removes the longest string containing only characters
in <parameter>characters</parameter> (a space by default)
from the start and end of <parameter>string</parameter>.
</para>
<para>
<literal>btrim('xyxtrimyyx', 'xyz')</literal>
<returnvalue>trim</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>normalized</primary>
</indexterm>
<indexterm>
<primary>Unicode normalization</primary>
</indexterm>
<type>text</type> <literal>IS</literal> <optional><literal>NOT</literal></optional> <optional><parameter>form</parameter></optional> <literal>NORMALIZED</literal>
<returnvalue>boolean</returnvalue>
</para>
<para>
Checks whether the string is in the specified Unicode normalization
form. The optional <parameter>form</parameter> key word specifies the
form: <literal>NFC</literal> (the default), <literal>NFD</literal>,
<literal>NFKC</literal>, or <literal>NFKD</literal>. This expression can
only be used when the server encoding is <literal>UTF8</literal>. Note
that checking for normalization using this expression is often faster
than normalizing possibly already normalized strings.
</para>
<para>
<literal>U&'\0061\0308bc' IS NFD NORMALIZED</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>bit_length</primary>
</indexterm>
<function>bit_length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bits in the string (8
times the <function>octet_length</function>).
</para>
<para>
<literal>bit_length('jose')</literal>
<returnvalue>32</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>char_length</primary>
</indexterm>
<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>
<function>char_length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para role="func_signature">
<indexterm>
<primary>character_length</primary>
</indexterm>
<function>character_length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of characters in the string.
</para>
<para>
<literal>char_length('josé')</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-lower">
<primary>lower</primary>
</indexterm>
<function>lower</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the string to all lower case, according to the rules of the
database's locale.
</para>
<para>
<literal>lower('TOM')</literal>
<returnvalue>tom</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lpad</primary>
</indexterm>
<function>lpad</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>length</parameter> <type>integer</type>
<optional>, <parameter>fill</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Extends 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).
</para>
<para>
<literal>lpad('hi', 5, 'xy')</literal>
<returnvalue>xyxhi</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ltrim</primary>
</indexterm>
<function>ltrim</function> ( <parameter>string</parameter> <type>text</type>
<optional>, <parameter>characters</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Removes the longest string containing only characters in
<parameter>characters</parameter> (a space by default) from the start of
<parameter>string</parameter>.
</para>
<para>
<literal>ltrim('zzzytest', 'xyz')</literal>
<returnvalue>test</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-normalize">
<primary>normalize</primary>
</indexterm>
<indexterm>
<primary>Unicode normalization</primary>
</indexterm>
<function>normalize</function> ( <type>text</type>
<optional>, <parameter>form</parameter> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the string to the specified Unicode
normalization form. The optional <parameter>form</parameter> key word
specifies the form: <literal>NFC</literal> (the default),
<literal>NFD</literal>, <literal>NFKC</literal>, or
<literal>NFKD</literal>. This function can only be used when the
server encoding is <literal>UTF8</literal>.
</para>
<para>
<literal>normalize(U&'\0061\0308bc', NFC)</literal>
<returnvalue>U&'\00E4bc'</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>octet_length</primary>
</indexterm>
<function>octet_length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bytes in the string.
</para>
<para>
<literal>octet_length('josé')</literal>
<returnvalue>5</returnvalue> (if server encoding is UTF8)
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>octet_length</primary>
</indexterm>
<function>octet_length</function> ( <type>character</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bytes in the string. Since this version of the
function accepts type <type>character</type> directly, it will not
strip trailing spaces.
</para>
<para>
<literal>octet_length('abc '::character(4))</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>overlay</primary>
</indexterm>
<function>overlay</function> ( <parameter>string</parameter> <type>text</type> <literal>PLACING</literal> <parameter>newsubstring</parameter> <type>text</type> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Replaces the substring of <parameter>string</parameter> that starts at
the <parameter>start</parameter>'th character and extends
for <parameter>count</parameter> characters
with <parameter>newsubstring</parameter>.
If <parameter>count</parameter> is omitted, it defaults to the length
of <parameter>newsubstring</parameter>.
</para>
<para>
<literal>overlay('Txxxxas' placing 'hom' from 2 for 4)</literal>
<returnvalue>Thomas</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>position</primary>
</indexterm>
<function>position</function> ( <parameter>substring</parameter> <type>text</type> <literal>IN</literal> <parameter>string</parameter> <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns first starting index of the specified
<parameter>substring</parameter> within
<parameter>string</parameter>, or zero if it's not present.
</para>
<para>
<literal>position('om' in 'Thomas')</literal>
<returnvalue>3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>rpad</primary>
</indexterm>
<function>rpad</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>length</parameter> <type>integer</type>
<optional>, <parameter>fill</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Extends 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.
</para>
<para>
<literal>rpad('hi', 5, 'xy')</literal>
<returnvalue>hixyx</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>rtrim</primary>
</indexterm>
<function>rtrim</function> ( <parameter>string</parameter> <type>text</type>
<optional>, <parameter>characters</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Removes the longest string containing only characters in
<parameter>characters</parameter> (a space by default) from the end of
<parameter>string</parameter>.
</para>
<para>
<literal>rtrim('testxxzx', 'xyz')</literal>
<returnvalue>test</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substring</primary>
</indexterm>
<function>substring</function> ( <parameter>string</parameter> <type>text</type> <optional> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> </optional> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Extracts the substring of <parameter>string</parameter> starting at
the <parameter>start</parameter>'th character if that is specified,
and stopping after <parameter>count</parameter> characters if that is
specified. Provide at least one of <parameter>start</parameter>
and <parameter>count</parameter>.
</para>
<para>
<literal>substring('Thomas' from 2 for 3)</literal>
<returnvalue>hom</returnvalue>
</para>
<para>
<literal>substring('Thomas' from 3)</literal>
<returnvalue>omas</returnvalue>
</para>
<para>
<literal>substring('Thomas' for 2)</literal>
<returnvalue>Th</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>FROM</literal> <parameter>pattern</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Extracts the first substring matching POSIX regular expression; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>substring('Thomas' from '...$')</literal>
<returnvalue>mas</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>SIMILAR</literal> <parameter>pattern</parameter> <type>text</type> <literal>ESCAPE</literal> <parameter>escape</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>FROM</literal> <parameter>pattern</parameter> <type>text</type> <literal>FOR</literal> <parameter>escape</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Extracts the first substring matching <acronym>SQL</acronym> regular expression;
see <xref linkend="functions-similarto-regexp"/>. The first form has
been specified since SQL:2003; the second form was only in SQL:1999
and should be considered obsolete.
</para>
<para>
<literal>substring('Thomas' similar '%#"o_a#"_' escape '#')</literal>
<returnvalue>oma</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>trim</primary>
</indexterm>
<function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional>
<optional> <parameter>characters</parameter> <type>text</type> </optional> <literal>FROM</literal>
<parameter>string</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Removes the longest string containing only characters in
<parameter>characters</parameter> (a space by default) from the
start, end, or both ends (<literal>BOTH</literal> is the default)
of <parameter>string</parameter>.
</para>
<para>
<literal>trim(both 'xyz' from 'yxTomxx')</literal>
<returnvalue>Tom</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional> <optional> <literal>FROM</literal> </optional>
<parameter>string</parameter> <type>text</type> <optional>,
<parameter>characters</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
This is a non-standard syntax for <function>trim()</function>.
</para>
<para>
<literal>trim(both from 'yxTomxx', 'xyz')</literal>
<returnvalue>Tom</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>unicode_assigned</primary>
</indexterm>
<function>unicode_assigned</function> ( <type>text</type> )
<returnvalue>boolean</returnvalue>
</para>
<para>
Returns <literal>true</literal> if all characters in the string are
assigned Unicode codepoints; <literal>false</literal> otherwise. This
function can only be used when the server encoding is
<literal>UTF8</literal>.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>upper</primary>
</indexterm>
<function>upper</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the string to all upper case, according to the rules of the
database's locale.
</para>
<para>
<literal>upper('tom')</literal>
<returnvalue>TOM</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Additional string manipulation functions and operators are available
and are listed in <xref linkend="functions-string-other"/>. (Some of
these are used internally to implement
the <acronym>SQL</acronym>-standard string functions listed in
<xref linkend="functions-string-sql"/>.)
There are also pattern-matching operators, which are described in
<xref linkend="functions-matching"/>, and operators for full-text
search, which are described in <xref linkend="textsearch"/>.
</para>
<table id="functions-string-other">
<title>Other String Functions and Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function/Operator
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>character string</primary>
<secondary>prefix test</secondary>
</indexterm>
<type>text</type> <literal>^@</literal> <type>text</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
Returns true if the first string starts with the second string
(equivalent to the <function>starts_with()</function> function).
</para>
<para>
<literal>'alphabet' ^@ 'alph'</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ascii</primary>
</indexterm>
<function>ascii</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the numeric code of the first character of the argument.
In <acronym>UTF8</acronym> encoding, returns the Unicode code point
of the character. In other multibyte encodings, the argument must
be an <acronym>ASCII</acronym> character.
</para>
<para>
<literal>ascii('x')</literal>
<returnvalue>120</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>chr</primary>
</indexterm>
<function>chr</function> ( <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns the character with the given code. In <acronym>UTF8</acronym>
encoding the argument is treated as a Unicode code point. In other
multibyte encodings the argument must designate
an <acronym>ASCII</acronym> character. <literal>chr(0)</literal> is
disallowed because text data types cannot store that character.
</para>
<para>
<literal>chr(65)</literal>
<returnvalue>A</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>concat</primary>
</indexterm>
<function>concat</function> ( <parameter>val1</parameter> <type>"any"</type>
<optional>, <parameter>val2</parameter> <type>"any"</type> <optional>, ...</optional> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Concatenates the text representations of all the arguments.
NULL arguments are ignored.
</para>
<para>
<literal>concat('abcde', 2, NULL, 22)</literal>
<returnvalue>abcde222</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>concat_ws</primary>
</indexterm>
<function>concat_ws</function> ( <parameter>sep</parameter> <type>text</type>,
<parameter>val1</parameter> <type>"any"</type>
<optional>, <parameter>val2</parameter> <type>"any"</type> <optional>, ...</optional> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Concatenates all but the first argument, with separators. The first
argument is used as the separator string, and should not be NULL.
Other NULL arguments are ignored.
</para>
<para>
<literal>concat_ws(',', 'abcde', 2, NULL, 22)</literal>
<returnvalue>abcde,2,22</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>format</primary>
</indexterm>
<function>format</function> ( <parameter>formatstr</parameter> <type>text</type>
<optional>, <parameter>formatarg</parameter> <type>"any"</type> <optional>, ...</optional> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Formats arguments according to a format string;
see <xref linkend="functions-string-format"/>.
This function is similar to the C function <function>sprintf</function>.
</para>
<para>
<literal>format('Hello %s, %1$s', 'World')</literal>
<returnvalue>Hello World, World</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>initcap</primary>
</indexterm>
<function>initcap</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts 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.
</para>
<para>
<literal>initcap('hi THOMAS')</literal>
<returnvalue>Hi Thomas</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>casefold</primary>
</indexterm>
<function>casefold</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Performs case folding of the input string according to the collation.
Case folding is similar to case conversion, but the purpose of case
folding is to facilitate case-insensitive matching of strings,
whereas the purpose of case conversion is to convert to a particular
cased form. This function can only be used when the server encoding
is <literal>UTF8</literal>.
</para>
<para>
Ordinarily, case folding simply converts to lowercase, but there may
be exceptions depending on the collation. For instance, some
characters have more than two lowercase variants, or fold to uppercase.
</para>
<para>
Case folding may change the length of the string. For instance, in
the <literal>PG_UNICODE_FAST</literal> collation, <literal>ß</literal>
(U+00DF) folds to <literal>ss</literal>.
</para>
<para>
<function>casefold</function> can be used for Unicode Default Caseless
Matching. It does not always preserve the normalized form of the
input string (see <xref linkend="function-normalize"/>).
</para>
<para>
The <literal>libc</literal> provider doesn't support case folding, so
<function>casefold</function> is identical to <xref
linkend="function-lower"/>.
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>left</primary>
</indexterm>
<function>left</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>n</parameter> <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns first <parameter>n</parameter> characters in the
string, or when <parameter>n</parameter> is negative, returns
all but last |<parameter>n</parameter>| characters.
</para>
<para>
<literal>left('abcde', 2)</literal>
<returnvalue>ab</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>length</primary>
</indexterm>
<function>length</function> ( <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of characters in the string.
</para>
<para>
<literal>length('jose')</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>md5</primary>
</indexterm>
<function>md5</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Computes the MD5 <link linkend="functions-hash-note">hash</link> of
the argument, with the result written in hexadecimal.
</para>
<para>
<literal>md5('abc')</literal>
<returnvalue>900150983cd24fb0&zwsp;d6963f7d28e17f72</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>parse_ident</primary>
</indexterm>
<function>parse_ident</function> ( <parameter>qualified_identifier</parameter> <type>text</type>
<optional>, <parameter>strict_mode</parameter> <type>boolean</type> <literal>DEFAULT</literal> <literal>true</literal> </optional> )
<returnvalue>text[]</returnvalue>
</para>
<para>
Splits <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>.
</para>
<para>
<literal>parse_ident('"SomeSchema".someTable')</literal>
<returnvalue>{SomeSchema,sometable}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_client_encoding</primary>
</indexterm>
<function>pg_client_encoding</function> ( )
<returnvalue>name</returnvalue>
</para>
<para>
Returns current client encoding name.
</para>
<para>
<literal>pg_client_encoding()</literal>
<returnvalue>UTF8</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>quote_ident</primary>
</indexterm>
<function>quote_ident</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns 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"/>.
</para>
<para>
<literal>quote_ident('Foo bar')</literal>
<returnvalue>"Foo bar"</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>quote_literal</primary>
</indexterm>
<function>quote_literal</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns 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"/>.
</para>
<para>
<literal>quote_literal(E'O\'Reilly')</literal>
<returnvalue>'O''Reilly'</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>quote_literal</function> ( <type>anyelement</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the given value to text and then quotes it as a literal.
Embedded single-quotes and backslashes are properly doubled.
</para>
<para>
<literal>quote_literal(42.5)</literal>
<returnvalue>'42.5'</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>quote_nullable</primary>
</indexterm>
<function>quote_nullable</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns 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, returns <literal>NULL</literal>.
Embedded single-quotes and backslashes are properly doubled.
See also <xref linkend="plpgsql-quote-literal-example"/>.
</para>
<para>
<literal>quote_nullable(NULL)</literal>
<returnvalue>NULL</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>quote_nullable</function> ( <type>anyelement</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the given value to text and then quotes it as a literal;
or, if the argument is null, returns <literal>NULL</literal>.
Embedded single-quotes and backslashes are properly doubled.
</para>
<para>
<literal>quote_nullable(42.5)</literal>
<returnvalue>'42.5'</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_count</primary>
</indexterm>
<function>regexp_count</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>
<optional>, <parameter>start</parameter> <type>integer</type>
<optional>, <parameter>flags</parameter> <type>text</type> </optional> </optional> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of times the POSIX regular
expression <parameter>pattern</parameter> matches in
the <parameter>string</parameter>; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_count('123456789012', '\d\d\d', 2)</literal>
<returnvalue>3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_instr</primary>
</indexterm>
<function>regexp_instr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>
<optional>, <parameter>start</parameter> <type>integer</type>
<optional>, <parameter>N</parameter> <type>integer</type>
<optional>, <parameter>endoption</parameter> <type>integer</type>
<optional>, <parameter>flags</parameter> <type>text</type>
<optional>, <parameter>subexpr</parameter> <type>integer</type> </optional> </optional> </optional> </optional> </optional> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the position within <parameter>string</parameter> where
the <parameter>N</parameter>'th match of the POSIX regular
expression <parameter>pattern</parameter> occurs, or zero if there is
no such match; see <xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i')</literal>
<returnvalue>3</returnvalue>
</para>
<para>
<literal>regexp_instr('ABCDEF', 'c(.)(..)', 1, 1, 0, 'i', 2)</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_like</primary>
</indexterm>
<function>regexp_like</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>
<optional>, <parameter>flags</parameter> <type>text</type> </optional> )
<returnvalue>boolean</returnvalue>
</para>
<para>
Checks whether a match of the POSIX regular
expression <parameter>pattern</parameter> occurs
within <parameter>string</parameter>; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_like('Hello World', 'world$', 'i')</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_match</primary>
</indexterm>
<function>regexp_match</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> <optional>, <parameter>flags</parameter> <type>text</type> </optional> )
<returnvalue>text[]</returnvalue>
</para>
<para>
Returns substrings within the first match of the POSIX regular
expression <parameter>pattern</parameter> to
the <parameter>string</parameter>; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_match('foobarbequebaz', '(bar)(beque)')</literal>
<returnvalue>{bar,beque}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_matches</primary>
</indexterm>
<function>regexp_matches</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> <optional>, <parameter>flags</parameter> <type>text</type> </optional> )
<returnvalue>setof text[]</returnvalue>
</para>
<para>
Returns substrings within the first match of the POSIX regular
expression <parameter>pattern</parameter> to
the <parameter>string</parameter>, or substrings within all
such matches if the <literal>g</literal> flag is used;
see <xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal>
<returnvalue></returnvalue>
<programlisting>
{bar}
{baz}
</programlisting>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_replace</primary>
</indexterm>
<function>regexp_replace</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type>
<optional>, <parameter>flags</parameter> <type>text</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Replaces the substring that is the first match to the POSIX
regular expression <parameter>pattern</parameter>, or all such
matches if the <literal>g</literal> flag is used; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_replace('Thomas', '.[mN]a.', 'M')</literal>
<returnvalue>ThM</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>regexp_replace</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type>,
<parameter>start</parameter> <type>integer</type>
<optional>, <parameter>N</parameter> <type>integer</type>
<optional>, <parameter>flags</parameter> <type>text</type> </optional> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Replaces the substring that is the <parameter>N</parameter>'th
match to the POSIX regular expression <parameter>pattern</parameter>,
or all such matches if <parameter>N</parameter> is zero, with the
search beginning at the <parameter>start</parameter>'th character
of <parameter>string</parameter>. If <parameter>N</parameter> is
omitted, it defaults to 1. See
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_replace('Thomas', '.', 'X', 3, 2)</literal>
<returnvalue>ThoXas</returnvalue>
</para>
<para>
<literal>regexp_replace(string=>'hello world', pattern=>'l', replacement=>'XX', start=>1, "N"=>2)</literal>
<returnvalue>helXXo world</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_split_to_array</primary>
</indexterm>
<function>regexp_split_to_array</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> <optional>, <parameter>flags</parameter> <type>text</type> </optional> )
<returnvalue>text[]</returnvalue>
</para>
<para>
Splits <parameter>string</parameter> using a POSIX regular
expression as the delimiter, producing an array of results; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_split_to_array('hello world', '\s+')</literal>
<returnvalue>{hello,world}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_split_to_table</primary>
</indexterm>
<function>regexp_split_to_table</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> <optional>, <parameter>flags</parameter> <type>text</type> </optional> )
<returnvalue>setof text</returnvalue>
</para>
<para>
Splits <parameter>string</parameter> using a POSIX regular
expression as the delimiter, producing a set of results; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_split_to_table('hello world', '\s+')</literal>
<returnvalue></returnvalue>
<programlisting>
hello
world
</programlisting>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>regexp_substr</primary>
</indexterm>
<function>regexp_substr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>
<optional>, <parameter>start</parameter> <type>integer</type>
<optional>, <parameter>N</parameter> <type>integer</type>
<optional>, <parameter>flags</parameter> <type>text</type>
<optional>, <parameter>subexpr</parameter> <type>integer</type> </optional> </optional> </optional> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns the substring within <parameter>string</parameter> that
matches the <parameter>N</parameter>'th occurrence of the POSIX
regular expression <parameter>pattern</parameter>,
or <literal>NULL</literal> if there is no such match; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
<literal>regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i')</literal>
<returnvalue>CDEF</returnvalue>
</para>
<para>
<literal>regexp_substr('ABCDEF', 'c(.)(..)', 1, 1, 'i', 2)</literal>
<returnvalue>EF</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>repeat</primary>
</indexterm>
<function>repeat</function> ( <parameter>string</parameter> <type>text</type>, <parameter>number</parameter> <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Repeats <parameter>string</parameter> the specified
<parameter>number</parameter> of times.
</para>
<para>
<literal>repeat('Pg', 4)</literal>
<returnvalue>PgPgPgPg</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>replace</primary>
</indexterm>
<function>replace</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>from</parameter> <type>text</type>,
<parameter>to</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Replaces all occurrences in <parameter>string</parameter> of
substring <parameter>from</parameter> with
substring <parameter>to</parameter>.
</para>
<para>
<literal>replace('abcdefabcdef', 'cd', 'XX')</literal>
<returnvalue>abXXefabXXef</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>reverse</primary>
</indexterm>
<function>reverse</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Reverses the order of the characters in the string.
</para>
<para>
<literal>reverse('abcde')</literal>
<returnvalue>edcba</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>right</primary>
</indexterm>
<function>right</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>n</parameter> <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Returns last <parameter>n</parameter> characters in the string,
or when <parameter>n</parameter> is negative, returns all but
first |<parameter>n</parameter>| characters.
</para>
<para>
<literal>right('abcde', 2)</literal>
<returnvalue>de</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>split_part</primary>
</indexterm>
<function>split_part</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>delimiter</parameter> <type>text</type>,
<parameter>n</parameter> <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Splits <parameter>string</parameter> at occurrences
of <parameter>delimiter</parameter> and returns
the <parameter>n</parameter>'th field (counting from one),
or when <parameter>n</parameter> is negative, returns
the |<parameter>n</parameter>|'th-from-last field.
</para>
<para>
<literal>split_part('abc~@~def~@~ghi', '~@~', 2)</literal>
<returnvalue>def</returnvalue>
</para>
<para>
<literal>split_part('abc,def,ghi,jkl', ',', -2)</literal>
<returnvalue>ghi</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>starts_with</primary>
</indexterm>
<function>starts_with</function> ( <parameter>string</parameter> <type>text</type>, <parameter>prefix</parameter> <type>text</type> )
<returnvalue>boolean</returnvalue>
</para>
<para>
Returns true if <parameter>string</parameter> starts
with <parameter>prefix</parameter>.
</para>
<para>
<literal>starts_with('alphabet', 'alph')</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-string-to-array">
<primary>string_to_array</primary>
</indexterm>
<function>string_to_array</function> ( <parameter>string</parameter> <type>text</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
<returnvalue>text[]</returnvalue>
</para>
<para>
Splits the <parameter>string</parameter> at occurrences
of <parameter>delimiter</parameter> and forms the resulting fields
into a <type>text</type> array.
If <parameter>delimiter</parameter> is <literal>NULL</literal>,
each character in the <parameter>string</parameter> will become a
separate element in the array.
If <parameter>delimiter</parameter> is an empty string, then
the <parameter>string</parameter> is treated as a single field.
If <parameter>null_string</parameter> is supplied and is
not <literal>NULL</literal>, fields matching that string are
replaced by <literal>NULL</literal>.
See also <link linkend="function-array-to-string"><function>array_to_string</function></link>.
</para>
<para>
<literal>string_to_array('xx~~yy~~zz', '~~', 'yy')</literal>
<returnvalue>{xx,NULL,zz}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>string_to_table</primary>
</indexterm>
<function>string_to_table</function> ( <parameter>string</parameter> <type>text</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
<returnvalue>setof text</returnvalue>
</para>
<para>
Splits the <parameter>string</parameter> at occurrences
of <parameter>delimiter</parameter> and returns the resulting fields
as a set of <type>text</type> rows.
If <parameter>delimiter</parameter> is <literal>NULL</literal>,
each character in the <parameter>string</parameter> will become a
separate row of the result.
If <parameter>delimiter</parameter> is an empty string, then
the <parameter>string</parameter> is treated as a single field.
If <parameter>null_string</parameter> is supplied and is
not <literal>NULL</literal>, fields matching that string are
replaced by <literal>NULL</literal>.
</para>
<para>
<literal>string_to_table('xx~^~yy~^~zz', '~^~', 'yy')</literal>
<returnvalue></returnvalue>
<programlisting>
xx
NULL
zz
</programlisting>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>strpos</primary>
</indexterm>
<function>strpos</function> ( <parameter>string</parameter> <type>text</type>, <parameter>substring</parameter> <type>text</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns first starting index of the specified <parameter>substring</parameter>
within <parameter>string</parameter>, or zero if it's not present.
(Same as <literal>position(<parameter>substring</parameter> in
<parameter>string</parameter>)</literal>, but note the reversed
argument order.)
</para>
<para>
<literal>strpos('high', 'ig')</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substr</primary>
</indexterm>
<function>substr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>text</returnvalue>
</para>
<para>
Extracts the substring of <parameter>string</parameter> starting at
the <parameter>start</parameter>'th character,
and extending for <parameter>count</parameter> characters if that is
specified. (Same
as <literal>substring(<parameter>string</parameter>
from <parameter>start</parameter>
for <parameter>count</parameter>)</literal>.)
</para>
<para>
<literal>substr('alphabet', 3)</literal>
<returnvalue>phabet</returnvalue>
</para>
<para>
<literal>substr('alphabet', 3, 2)</literal>
<returnvalue>ph</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>to_ascii</primary>
</indexterm>
<function>to_ascii</function> ( <parameter>string</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<function>to_ascii</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>encoding</parameter> <type>name</type> )
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<function>to_ascii</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>encoding</parameter> <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts <parameter>string</parameter> to <acronym>ASCII</acronym>
from another encoding, which may be identified by name or number.
If <parameter>encoding</parameter> is omitted the database encoding
is assumed (which in practice is the only useful case).
The conversion consists primarily of dropping accents.
Conversion is only supported
from <literal>LATIN1</literal>, <literal>LATIN2</literal>,
<literal>LATIN9</literal>, and <literal>WIN1250</literal> encodings.
(See the <xref linkend="unaccent"/> module for another, more flexible
solution.)
</para>
<para>
<literal>to_ascii('Karél')</literal>
<returnvalue>Karel</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>to_bin</primary>
</indexterm>
<function>to_bin</function> ( <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<function>to_bin</function> ( <type>bigint</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the number to its equivalent two's complement binary
representation.
</para>
<para>
<literal>to_bin(2147483647)</literal>
<returnvalue>1111111111111111111111111111111</returnvalue>
</para>
<para>
<literal>to_bin(-1234)</literal>
<returnvalue>11111111111111111111101100101110</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>to_hex</primary>
</indexterm>
<function>to_hex</function> ( <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<function>to_hex</function> ( <type>bigint</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the number to its equivalent two's complement hexadecimal
representation.
</para>
<para>
<literal>to_hex(2147483647)</literal>
<returnvalue>7fffffff</returnvalue>
</para>
<para>
<literal>to_hex(-1234)</literal>
<returnvalue>fffffb2e</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>to_oct</primary>
</indexterm>
<function>to_oct</function> ( <type>integer</type> )
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<function>to_oct</function> ( <type>bigint</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts the number to its equivalent two's complement octal
representation.
</para>
<para>
<literal>to_oct(2147483647)</literal>
<returnvalue>17777777777</returnvalue>
</para>
<para>
<literal>to_oct(-1234)</literal>
<returnvalue>37777775456</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>translate</primary>
</indexterm>
<function>translate</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>from</parameter> <type>text</type>,
<parameter>to</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Replaces each character in <parameter>string</parameter> that
matches a character in the <parameter>from</parameter> set with 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 deleted.
</para>
<para>
<literal>translate('12345', '143', 'ax')</literal>
<returnvalue>a2x5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>unistr</primary>
</indexterm>
<function>unistr</function> ( <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Evaluate escaped Unicode characters in the argument. Unicode characters
can be specified as
<literal>\<replaceable>XXXX</replaceable></literal> (4 hexadecimal
digits), <literal>\+<replaceable>XXXXXX</replaceable></literal> (6
hexadecimal digits),
<literal>\u<replaceable>XXXX</replaceable></literal> (4 hexadecimal
digits), or <literal>\U<replaceable>XXXXXXXX</replaceable></literal>
(8 hexadecimal digits). To specify a backslash, write two
backslashes. All other characters are taken literally.
</para>
<para>
If the server encoding is not UTF-8, the Unicode code point identified
by one of these escape sequences is converted to the actual server
encoding; an error is reported if that's not possible.
</para>
<para>
This function provides a (non-standard) alternative to string
constants with Unicode escapes (see <xref
linkend="sql-syntax-strings-uescape"/>).
</para>
<para>
<literal>unistr('d\0061t\+000061')</literal>
<returnvalue>data</returnvalue>
</para>
<para>
<literal>unistr('d\u0061t\U00000061')</literal>
<returnvalue>data</returnvalue>
</para></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"/>, and the functions for
converting between strings and the <type>bytea</type> type in
<xref linkend="functions-binarystring-conversions"/>.
</para>
<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> <optional>, <parameter>formatarg</parameter> <type>"any"</type> <optional>, ...</optional> </optional>)
</synopsis>
<parameter>formatstr</parameter> is a format string that specifies how the
result should be formatted. Text in the format string is copied
directly to the result, except where <firstterm>format specifiers</firstterm> are
used. Format specifiers act as placeholders in the string, defining how
subsequent function arguments should be formatted and inserted into the
result. Each <parameter>formatarg</parameter> argument is converted to text
according to the usual output rules for its data type, and then formatted
and inserted into the result string according to the format specifier(s).
</para>
<para>
Format specifiers are introduced by a <literal>%</literal> character and have
the form
<synopsis>
%[<parameter>position</parameter>][<parameter>flags</parameter>][<parameter>width</parameter>]<parameter>type</parameter>
</synopsis>
where the component fields are:
<variablelist>
<varlistentry>
<term><parameter>position</parameter> (optional)</term>
<listitem>
<para>
A string of the form <literal><parameter>n</parameter>$</literal> where
<parameter>n</parameter> is the index of the argument to print.
Index 1 means the first argument after
<parameter>formatstr</parameter>. If the <parameter>position</parameter> is
omitted, the default is to use the next argument in sequence.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter> (optional)</term>
<listitem>
<para>
Additional options controlling how the format specifier's output is
formatted. Currently the only supported flag is a minus sign
(<literal>-</literal>) which will cause the format specifier's output to be
left-justified. This has no effect unless the <parameter>width</parameter>
field is also specified.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>width</parameter> (optional)</term>
<listitem>
<para>
Specifies the <emphasis>minimum</emphasis> number of characters to use to
display the format specifier's output. The output is padded on the
left or right (depending on the <literal>-</literal> flag) with spaces as
needed to fill the width. A too-small width does not cause
truncation of the output, but is simply ignored. The width may be
specified using any of the following: a positive integer; an
asterisk (<literal>*</literal>) to use the next function argument as the
width; or a string of the form <literal>*<parameter>n</parameter>$</literal> to
use the <parameter>n</parameter>th function argument as the width.
</para>
<para>
If the width comes from a function argument, that argument is
consumed before the argument that is used for the format specifier's
value. If the width argument is negative, the result is left
aligned (as if the <literal>-</literal> flag had been specified) within a
field of length <function>abs</function>(<parameter>width</parameter>).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter> (required)</term>
<listitem>
<para>
The type of format conversion to use to produce the format
specifier's output. The following types are supported:
<itemizedlist>
<listitem>
<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 <parameter>width</parameter> 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 <parameter>position</parameter> 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 <parameter>position</parameter> fields to be mixed
in the same format string. A format specifier without a
<parameter>position</parameter> 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 binary strings, that is values of type <type>bytea</type>.
Many of these are equivalent, in purpose and syntax, to the
text-string functions described in the previous section.
</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>
<table id="functions-binarystring-sql">
<title><acronym>SQL</acronym> Binary String Functions and Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function/Operator
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>binary string</primary>
<secondary>concatenation</secondary>
</indexterm>
<type>bytea</type> <literal>||</literal> <type>bytea</type>
<returnvalue>bytea</returnvalue>
</para>
<para>
Concatenates the two binary strings.
</para>
<para>
<literal>'\x123456'::bytea || '\x789a00bcde'::bytea</literal>
<returnvalue>\x123456789a00bcde</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>bit_length</primary>
</indexterm>
<function>bit_length</function> ( <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bits in the binary string (8
times the <function>octet_length</function>).
</para>
<para>
<literal>bit_length('\x123456'::bytea)</literal>
<returnvalue>24</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>btrim</primary>
</indexterm>
<function>btrim</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the start and end of
<parameter>bytes</parameter>.
</para>
<para>
<literal>btrim('\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x345678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>ltrim</primary>
</indexterm>
<function>ltrim</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the start of
<parameter>bytes</parameter>.
</para>
<para>
<literal>ltrim('\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x34567890</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>octet_length</primary>
</indexterm>
<function>octet_length</function> ( <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bytes in the binary string.
</para>
<para>
<literal>octet_length('\x123456'::bytea)</literal>
<returnvalue>3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>overlay</primary>
</indexterm>
<function>overlay</function> ( <parameter>bytes</parameter> <type>bytea</type> <literal>PLACING</literal> <parameter>newsubstring</parameter> <type>bytea</type> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Replaces the substring of <parameter>bytes</parameter> that starts at
the <parameter>start</parameter>'th byte and extends
for <parameter>count</parameter> bytes
with <parameter>newsubstring</parameter>.
If <parameter>count</parameter> is omitted, it defaults to the length
of <parameter>newsubstring</parameter>.
</para>
<para>
<literal>overlay('\x1234567890'::bytea placing '\002\003'::bytea from 2 for 3)</literal>
<returnvalue>\x12020390</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>position</primary>
</indexterm>
<function>position</function> ( <parameter>substring</parameter> <type>bytea</type> <literal>IN</literal> <parameter>bytes</parameter> <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns first starting index of the specified
<parameter>substring</parameter> within
<parameter>bytes</parameter>, or zero if it's not present.
</para>
<para>
<literal>position('\x5678'::bytea in '\x1234567890'::bytea)</literal>
<returnvalue>3</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>rtrim</primary>
</indexterm>
<function>rtrim</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the end of
<parameter>bytes</parameter>.
</para>
<para>
<literal>rtrim('\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x12345678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substring</primary>
</indexterm>
<function>substring</function> ( <parameter>bytes</parameter> <type>bytea</type> <optional> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> </optional> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Extracts the substring of <parameter>bytes</parameter> starting at
the <parameter>start</parameter>'th byte if that is specified,
and stopping after <parameter>count</parameter> bytes if that is
specified. Provide at least one of <parameter>start</parameter>
and <parameter>count</parameter>.
</para>
<para>
<literal>substring('\x1234567890'::bytea from 3 for 2)</literal>
<returnvalue>\x5678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>trim</primary>
</indexterm>
<function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional>
<parameter>bytesremoved</parameter> <type>bytea</type> <literal>FROM</literal>
<parameter>bytes</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Removes the longest string containing only bytes appearing in
<parameter>bytesremoved</parameter> from the start,
end, or both ends (<literal>BOTH</literal> is the default)
of <parameter>bytes</parameter>.
</para>
<para>
<literal>trim('\x9012'::bytea from '\x1234567890'::bytea)</literal>
<returnvalue>\x345678</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>trim</function> ( <optional> <literal>LEADING</literal> | <literal>TRAILING</literal> | <literal>BOTH</literal> </optional> <optional> <literal>FROM</literal> </optional>
<parameter>bytes</parameter> <type>bytea</type>,
<parameter>bytesremoved</parameter> <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
This is a non-standard syntax for <function>trim()</function>.
</para>
<para>
<literal>trim(both from '\x1234567890'::bytea, '\x9012'::bytea)</literal>
<returnvalue>\x345678</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Additional binary string manipulation functions are available and
are listed in <xref linkend="functions-binarystring-other"/>. Some
of them are used internally to implement the
<acronym>SQL</acronym>-standard string functions listed in <xref
linkend="functions-binarystring-sql"/>.
</para>
<table id="functions-binarystring-other">
<title>Other Binary String Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>bit_count</primary>
</indexterm>
<indexterm>
<primary>popcount</primary>
<see>bit_count</see>
</indexterm>
<function>bit_count</function> ( <parameter>bytes</parameter> <type>bytea</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the number of bits set in the binary string (also known as
<quote>popcount</quote>).
</para>
<para>
<literal>bit_count('\x1234567890'::bytea)</literal>
<returnvalue>15</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>crc32</primary>
</indexterm>
<function>crc32</function> ( <type>bytea</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Computes the CRC-32 value of the binary string.
</para>
<para>
<literal>crc32('abc'::bytea)</literal>
<returnvalue>891568578</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>crc32c</primary>
</indexterm>
<function>crc32c</function> ( <type>bytea</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Computes the CRC-32C value of the binary string.
</para>
<para>
<literal>crc32c('abc'::bytea)</literal>
<returnvalue>910901175</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>get_bit</primary>
</indexterm>
<function>get_bit</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>bigint</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Extracts <link linkend="functions-zerobased-note">n'th</link> bit
from binary string.
</para>
<para>
<literal>get_bit('\x1234567890'::bytea, 30)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>get_byte</primary>
</indexterm>
<function>get_byte</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Extracts <link linkend="functions-zerobased-note">n'th</link> byte
from binary string.
</para>
<para>
<literal>get_byte('\x1234567890'::bytea, 4)</literal>
<returnvalue>144</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>length</primary>
</indexterm>
<indexterm>
<primary>binary string</primary>
<secondary>length</secondary>
</indexterm>
<indexterm>
<primary>length</primary>
<secondary sortas="binary string">of a binary string</secondary>
<see>binary strings, length</see>
</indexterm>
<function>length</function> ( <type>bytea</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of bytes in the binary string.
</para>
<para>
<literal>length('\x1234567890'::bytea)</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>length</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>encoding</parameter> <type>name</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns the number of characters in the binary string, assuming
that it is text in the given <parameter>encoding</parameter>.
</para>
<para>
<literal>length('jose'::bytea, 'UTF8')</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>md5</primary>
</indexterm>
<function>md5</function> ( <type>bytea</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Computes the MD5 <link linkend="functions-hash-note">hash</link> of
the binary string, with the result written in hexadecimal.
</para>
<para>
<literal>md5('Th\000omas'::bytea)</literal>
<returnvalue>8ab2d3c9689aaf18&zwsp;b4958c334c82d8b1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>reverse</primary>
</indexterm>
<function>reverse</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Reverses the order of the bytes in the binary string.
</para>
<para>
<literal>reverse('\xabcd'::bytea)</literal>
<returnvalue>\xcdab</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_bit</primary>
</indexterm>
<function>set_bit</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>bigint</type>,
<parameter>newvalue</parameter> <type>integer</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Sets <link linkend="functions-zerobased-note">n'th</link> bit in
binary string to <parameter>newvalue</parameter>.
</para>
<para>
<literal>set_bit('\x1234567890'::bytea, 30, 0)</literal>
<returnvalue>\x1234563890</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_byte</primary>
</indexterm>
<function>set_byte</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>n</parameter> <type>integer</type>,
<parameter>newvalue</parameter> <type>integer</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Sets <link linkend="functions-zerobased-note">n'th</link> byte in
binary string to <parameter>newvalue</parameter>.
</para>
<para>
<literal>set_byte('\x1234567890'::bytea, 4, 64)</literal>
<returnvalue>\x1234567840</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha224</primary>
</indexterm>
<function>sha224</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-224 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha224('abc'::bytea)</literal>
<returnvalue>\x23097d223405d8228642a477bda2&zwsp;55b32aadbce4bda0b3f7e36c9da7</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha256</primary>
</indexterm>
<function>sha256</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-256 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha256('abc'::bytea)</literal>
<returnvalue>\xba7816bf8f01cfea414140de5dae2223&zwsp;b00361a396177a9cb410ff61f20015ad</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha384</primary>
</indexterm>
<function>sha384</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-384 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha384('abc'::bytea)</literal>
<returnvalue>\xcb00753f45a35e8bb5a03d699ac65007&zwsp;272c32ab0eded1631a8b605a43ff5bed&zwsp;8086072ba1e7cc2358baeca134c825a7</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>sha512</primary>
</indexterm>
<function>sha512</function> ( <type>bytea</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Computes the SHA-512 <link linkend="functions-hash-note">hash</link>
of the binary string.
</para>
<para>
<literal>sha512('abc'::bytea)</literal>
<returnvalue>\xddaf35a193617abacc417349ae204131&zwsp;12e6fa4e89a97ea20a9eeee64b55d39a&zwsp;2192992a274fc1a836ba3c23a3feebbd&zwsp;454d4423643ce80e2a9ac94fa54ca49f</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substr</primary>
</indexterm>
<function>substr</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Extracts the substring of <parameter>bytes</parameter> starting at
the <parameter>start</parameter>'th byte,
and extending for <parameter>count</parameter> bytes if that is
specified. (Same
as <literal>substring(<parameter>bytes</parameter>
from <parameter>start</parameter>
for <parameter>count</parameter>)</literal>.)
</para>
<para>
<literal>substr('\x1234567890'::bytea, 3, 2)</literal>
<returnvalue>\x5678</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para id="functions-zerobased-note">
Functions <function>get_byte</function> and <function>set_byte</function>
number the first byte of a binary string as byte 0.
Functions <function>get_bit</function> and <function>set_bit</function>
number bits from the right within each byte; for example bit 0 is the least
significant bit of the first byte, and bit 15 is the most significant bit
of the second byte.
</para>
<para id="functions-hash-note">
For historical reasons, the function <function>md5</function>
returns a hex-encoded value of type <type>text</type> whereas the SHA-2
functions return type <type>bytea</type>. Use the functions
<link linkend="function-encode"><function>encode</function></link>
and <link linkend="function-decode"><function>decode</function></link> to
convert between the two. For example write <literal>encode(sha256('abc'),
'hex')</literal> to get a hex-encoded text representation,
or <literal>decode(md5('abc'), 'hex')</literal> to get
a <type>bytea</type> value.
</para>
<para>
<indexterm>
<primary>character string</primary>
<secondary>converting to binary string</secondary>
</indexterm>
<indexterm>
<primary>binary string</primary>
<secondary>converting to character string</secondary>
</indexterm>
Functions for converting strings between different character sets
(encodings), and for representing arbitrary binary data in textual
form, are shown in
<xref linkend="functions-binarystring-conversions"/>. For these
functions, an argument or result of type <type>text</type> is expressed
in the database's default encoding, while arguments or results of
type <type>bytea</type> are in an encoding named by another argument.
</para>
<table id="functions-binarystring-conversions">
<title>Text/Binary String Conversion Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>convert</primary>
</indexterm>
<function>convert</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>src_encoding</parameter> <type>name</type>,
<parameter>dest_encoding</parameter> <type>name</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Converts a binary string representing text in
encoding <parameter>src_encoding</parameter>
to a binary string in encoding <parameter>dest_encoding</parameter>
(see <xref linkend="multibyte-conversions-supported"/> for
available conversions).
</para>
<para>
<literal>convert('text_in_utf8', 'UTF8', 'LATIN1')</literal>
<returnvalue>\x746578745f696e5f75746638</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>convert_from</primary>
</indexterm>
<function>convert_from</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>src_encoding</parameter> <type>name</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts a binary string representing text in
encoding <parameter>src_encoding</parameter>
to <type>text</type> in the database encoding
(see <xref linkend="multibyte-conversions-supported"/> for
available conversions).
</para>
<para>
<literal>convert_from('text_in_utf8', 'UTF8')</literal>
<returnvalue>text_in_utf8</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>convert_to</primary>
</indexterm>
<function>convert_to</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>dest_encoding</parameter> <type>name</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Converts a <type>text</type> string (in the database encoding) to a
binary string encoded in encoding <parameter>dest_encoding</parameter>
(see <xref linkend="multibyte-conversions-supported"/> for
available conversions).
</para>
<para>
<literal>convert_to('some_text', 'UTF8')</literal>
<returnvalue>\x736f6d655f74657874</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-encode">
<primary>encode</primary>
</indexterm>
<function>encode</function> ( <parameter>bytes</parameter> <type>bytea</type>,
<parameter>format</parameter> <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Encodes binary data into a textual representation; supported
<parameter>format</parameter> values are:
<link linkend="encode-format-base64"><literal>base64</literal></link>,
<link linkend="encode-format-escape"><literal>escape</literal></link>,
<link linkend="encode-format-hex"><literal>hex</literal></link>.
</para>
<para>
<literal>encode('123\000\001', 'base64')</literal>
<returnvalue>MTIzAAE=</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-decode">
<primary>decode</primary>
</indexterm>
<function>decode</function> ( <parameter>string</parameter> <type>text</type>,
<parameter>format</parameter> <type>text</type> )
<returnvalue>bytea</returnvalue>
</para>
<para>
Decodes binary data from a textual representation; supported
<parameter>format</parameter> values are the same as
for <function>encode</function>.
</para>
<para>
<literal>decode('MTIzAAE=', 'base64')</literal>
<returnvalue>\x3132330001</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The <function>encode</function> and <function>decode</function>
functions support the following textual formats:
<variablelist>
<varlistentry id="encode-format-base64">
<term>base64
<indexterm>
<primary>base64 format</primary>
</indexterm></term>
<listitem>
<para>
The <literal>base64</literal> format is that
of <ulink url="https://datatracker.ietf.org/doc/html/rfc2045#section-6.8">RFC
2045 Section 6.8</ulink>. As per the <acronym>RFC</acronym>, encoded lines are
broken at 76 characters. However instead of the MIME CRLF
end-of-line marker, only a newline is used for end-of-line.
The <function>decode</function> function ignores carriage-return,
newline, space, and tab characters. Otherwise, an error is
raised when <function>decode</function> is supplied invalid
base64 data — including when trailing padding is incorrect.
</para>
</listitem>
</varlistentry>
<varlistentry id="encode-format-escape">
<term>escape
<indexterm>
<primary>escape format</primary>
</indexterm></term>
<listitem>
<para>
The <literal>escape</literal> format converts zero bytes and
bytes with the high bit set into octal escape sequences
(<literal>\</literal><replaceable>nnn</replaceable>), and it doubles
backslashes. Other byte values are represented literally.
The <function>decode</function> function will raise an error if a
backslash is not followed by either a second backslash or three
octal digits; it accepts other byte values unchanged.
</para>
</listitem>
</varlistentry>
<varlistentry id="encode-format-hex">
<term>hex
<indexterm>
<primary>hex format</primary>
</indexterm></term>
<listitem>
<para>
The <literal>hex</literal> format represents each 4 bits of
data as one hexadecimal digit, <literal>0</literal>
through <literal>f</literal>, writing the higher-order digit of
each byte first. The <function>encode</function> function outputs
the <literal>a</literal>-<literal>f</literal> hex digits in lower
case. Because the smallest unit of data is 8 bits, there are
always an even number of characters returned
by <function>encode</function>.
The <function>decode</function> function
accepts the <literal>a</literal>-<literal>f</literal> characters in
either upper or lower case. An error is raised
when <function>decode</function> is given invalid hex data
— including when given an odd number of characters.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
In addition, it is possible to cast integral values to and from type
<type>bytea</type>. Casting an integer to <type>bytea</type> produces
2, 4, or 8 bytes, depending on the width of the integer type. The result
is the two's complement representation of the integer, with the most
significant byte first. Some examples:
<programlisting>
1234::smallint::bytea <lineannotation>\x04d2</lineannotation>
cast(1234 as bytea) <lineannotation>\x000004d2</lineannotation>
cast(-1234 as bytea) <lineannotation>\xfffffb2e</lineannotation>
'\x8000'::bytea::smallint <lineannotation>-32768</lineannotation>
'\x8000'::bytea::integer <lineannotation>32768</lineannotation>
</programlisting>
Casting a <type>bytea</type> to an integer will raise an error if the
length of the <type>bytea</type> exceeds the width of the integer type.
</para>
<para>
See also the aggregate function <function>string_agg</function> in
<xref linkend="functions-aggregate"/> and the large object functions
in <xref linkend="lo-funcs"/>.
</para>
</sect1>
<sect1 id="functions-bitstring">
<title>Bit String Functions and Operators</title>
<indexterm zone="functions-bitstring">
<primary>bit strings</primary>
<secondary>functions</secondary>
</indexterm>
<para>
This section describes functions and operators for examining and
manipulating bit strings, that is values of the types
<type>bit</type> and <type>bit varying</type>. (While only
type <type>bit</type> is mentioned in these tables, values of
type <type>bit varying</type> can be used interchangeably.)
Bit strings support the usual comparison operators shown in
<xref linkend="functions-comparison-op-table"/>, as well as the
operators shown in <xref linkend="functions-bit-string-op-table"/>.
</para>
<table id="functions-bit-string-op-table">
<title>Bit String Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Operator
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>||</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Concatenation
</para>
<para>
<literal>B'10001' || B'011'</literal>
<returnvalue>10001011</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>&</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise AND (inputs must be of equal length)
</para>
<para>
<literal>B'10001' & B'01101'</literal>
<returnvalue>00001</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>|</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise OR (inputs must be of equal length)
</para>
<para>
<literal>B'10001' | B'01101'</literal>
<returnvalue>11101</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>#</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise exclusive OR (inputs must be of equal length)
</para>
<para>
<literal>B'10001' # B'01101'</literal>
<returnvalue>11100</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<literal>~</literal> <type>bit</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise NOT
</para>
<para>
<literal>~ B'10001'</literal>
<returnvalue>01110</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal><<</literal> <type>integer</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise shift left
(string length is preserved)
</para>
<para>
<literal>B'10001' << 3</literal>
<returnvalue>01000</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>bit</type> <literal>>></literal> <type>integer</type>
<returnvalue>bit</returnvalue>
</para>
<para>
Bitwise shift right
(string length is preserved)
</para>
<para>
<literal>B'10001' >> 2</literal>
<returnvalue>00100</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Some of the functions available for binary strings are also available
for bit strings, as shown in <xref linkend="functions-bit-string-table"/>.
</para>
<table id="functions-bit-string-table">
<title>Bit String Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>bit_count</primary>
</indexterm>
<function>bit_count</function> ( <type>bit</type> )
<returnvalue>bigint</returnvalue>
</para>
<para>
Returns the number of bits set in the bit string (also known as
<quote>popcount</quote>).
</para>
<para>
<literal>bit_count(B'10111')</literal>
<returnvalue>4</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>bit_length</primary>
</indexterm>
<function>bit_length</function> ( <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bits in the bit string.
</para>
<para>
<literal>bit_length(B'10111')</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>length</primary>
</indexterm>
<indexterm>
<primary>bit string</primary>
<secondary>length</secondary>
</indexterm>
<function>length</function> ( <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bits in the bit string.
</para>
<para>
<literal>length(B'10111')</literal>
<returnvalue>5</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>octet_length</primary>
</indexterm>
<function>octet_length</function> ( <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns number of bytes in the bit string.
</para>
<para>
<literal>octet_length(B'1011111011')</literal>
<returnvalue>2</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>overlay</primary>
</indexterm>
<function>overlay</function> ( <parameter>bits</parameter> <type>bit</type> <literal>PLACING</literal> <parameter>newsubstring</parameter> <type>bit</type> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bit</returnvalue>
</para>
<para>
Replaces the substring of <parameter>bits</parameter> that starts at
the <parameter>start</parameter>'th bit and extends
for <parameter>count</parameter> bits
with <parameter>newsubstring</parameter>.
If <parameter>count</parameter> is omitted, it defaults to the length
of <parameter>newsubstring</parameter>.
</para>
<para>
<literal>overlay(B'01010101010101010' placing B'11111' from 2 for 3)</literal>
<returnvalue>0111110101010101010</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>position</primary>
</indexterm>
<function>position</function> ( <parameter>substring</parameter> <type>bit</type> <literal>IN</literal> <parameter>bits</parameter> <type>bit</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Returns first starting index of the specified <parameter>substring</parameter>
within <parameter>bits</parameter>, or zero if it's not present.
</para>
<para>
<literal>position(B'010' in B'000001101011')</literal>
<returnvalue>8</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>substring</primary>
</indexterm>
<function>substring</function> ( <parameter>bits</parameter> <type>bit</type> <optional> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> </optional> <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
<returnvalue>bit</returnvalue>
</para>
<para>
Extracts the substring of <parameter>bits</parameter> starting at
the <parameter>start</parameter>'th bit if that is specified,
and stopping after <parameter>count</parameter> bits if that is
specified. Provide at least one of <parameter>start</parameter>
and <parameter>count</parameter>.
</para>
<para>
<literal>substring(B'110010111111' from 3 for 2)</literal>
<returnvalue>00</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>get_bit</primary>
</indexterm>
<function>get_bit</function> ( <parameter>bits</parameter> <type>bit</type>,
<parameter>n</parameter> <type>integer</type> )
<returnvalue>integer</returnvalue>
</para>
<para>
Extracts <parameter>n</parameter>'th bit
from bit string; the first (leftmost) bit is bit 0.
</para>
<para>
<literal>get_bit(B'101010101010101010', 6)</literal>
<returnvalue>1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_bit</primary>
</indexterm>
<function>set_bit</function> ( <parameter>bits</parameter> <type>bit</type>,
<parameter>n</parameter> <type>integer</type>,
<parameter>newvalue</parameter> <type>integer</type> )
<returnvalue>bit</returnvalue>
</para>
<para>
Sets <parameter>n</parameter>'th bit in
bit string to <parameter>newvalue</parameter>;
the first (leftmost) bit is bit 0.
</para>
<para>
<literal>set_bit(B'101010101010101010', 6, 0)</literal>
<returnvalue>101010001010101010</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
In addition, it is possible to cast integral values to and from type
<type>bit</type>.
Casting an integer to <type>bit(n)</type> copies the rightmost
<literal>n</literal> bits. Casting an integer to a bit string width wider
than the integer itself will sign-extend on the left.
Some examples:
<programlisting>
44::bit(10) <lineannotation>0000101100</lineannotation>
44::bit(3) <lineannotation>100</lineannotation>
cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
'1110'::bit(4)::integer <lineannotation>14</lineannotation>
</programlisting>
Note that casting to just <quote>bit</quote> means casting to
<literal>bit(1)</literal>, and so will deliver only the least significant
bit of the integer.
</para>
</sect1>
<sect1 id="functions-matching">
<title>Pattern Matching</title>
<indexterm zone="functions-matching">
<primary>pattern matching</primary>
</indexterm>
<para>
There are three separate approaches to pattern matching provided
by <productname>PostgreSQL</productname>: the traditional
<acronym>SQL</acronym> <function>LIKE</function> operator, the
more recent <function>SIMILAR TO</function> operator (added in
SQL:1999), and <acronym>POSIX</acronym>-style regular
expressions. Aside from the basic <quote>does this string match
this pattern?</quote> operators, functions are available to extract
or replace matching substrings and to split a string at matching
locations.
</para>
<tip>
<para>
If you have pattern matching needs that go beyond this,
consider writing a user-defined function in Perl or Tcl.
</para>
</tip>
<caution>
<para>
While most regular-expression searches can be executed very quickly,
regular expressions can be contrived that take arbitrary amounts of
time and memory to process. Be wary of accepting regular-expression
search patterns from hostile sources. If you must do so, it is
advisable to impose a statement timeout.
</para>
<para>
Searches using <function>SIMILAR TO</function> patterns have the same
security hazards, since <function>SIMILAR TO</function> provides many
of the same capabilities as <acronym>POSIX</acronym>-style regular
expressions.
</para>
<para>
<function>LIKE</function> searches, being much simpler than the other
two options, are safer to use with possibly-hostile pattern sources.
</para>
</caution>
<para>
<function>SIMILAR TO</function> and <acronym>POSIX</acronym>-style regular
expressions do not support nondeterministic collations. If required, use
<function>LIKE</function> or apply a different collation to the expression
to work around this limitation.
</para>
<sect2 id="functions-like">
<title><function>LIKE</function></title>
<indexterm>
<primary>LIKE</primary>
</indexterm>
<synopsis>
<replaceable>string</replaceable> LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
<replaceable>string</replaceable> NOT LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
</synopsis>
<para>
The <function>LIKE</function> expression returns true if the
<replaceable>string</replaceable> matches the supplied
<replaceable>pattern</replaceable>. (As
expected, the <function>NOT LIKE</function> expression returns
false if <function>LIKE</function> returns true, and vice versa.
An equivalent expression is
<literal>NOT (<replaceable>string</replaceable> LIKE
<replaceable>pattern</replaceable>)</literal>.)
</para>
<para>
If <replaceable>pattern</replaceable> does not contain percent
signs or underscores, then the pattern only represents the string
itself; in that case <function>LIKE</function> acts like the
equals operator. An underscore (<literal>_</literal>) in
<replaceable>pattern</replaceable> stands for (matches) any single
character; a percent sign (<literal>%</literal>) matches any sequence
of zero or more characters.
</para>
<para>
Some examples:
<programlisting>
'abc' LIKE 'abc' <lineannotation>true</lineannotation>
'abc' LIKE 'a%' <lineannotation>true</lineannotation>
'abc' LIKE '_b_' <lineannotation>true</lineannotation>
'abc' LIKE 'c' <lineannotation>false</lineannotation>
</programlisting>
</para>
<para>
<function>LIKE</function> pattern matching supports nondeterministic
collations (see <xref linkend="collation-nondeterministic"/>), such as
case-insensitive collations or collations that, say, ignore punctuation.
So with a case-insensitive collation, one could have:
<programlisting>
'AbC' LIKE 'abc' COLLATE case_insensitive <lineannotation>true</lineannotation>
'AbC' LIKE 'a%' COLLATE case_insensitive <lineannotation>true</lineannotation>
</programlisting>
With collations that ignore certain characters or in general that consider
strings of different lengths equal, the semantics can become a bit more
complicated. Consider these examples:
<programlisting>
'.foo.' LIKE 'foo' COLLATE ign_punct <lineannotation>true</lineannotation>
'.foo.' LIKE 'f_o' COLLATE ign_punct <lineannotation>true</lineannotation>
'.foo.' LIKE '_oo' COLLATE ign_punct <lineannotation>false</lineannotation>
</programlisting>
The way the matching works is that the pattern is partitioned into
sequences of wildcards and non-wildcard strings (wildcards being
<literal>_</literal> and <literal>%</literal>). For example, the pattern
<literal>f_o</literal> is partitioned into <literal>f, _, o</literal>, the
pattern <literal>_oo</literal> is partitioned into <literal>_,
oo</literal>. The input string matches the pattern if it can be
partitioned in such a way that the wildcards match one character or any
number of characters respectively and the non-wildcard partitions are
equal under the applicable collation. So for example, <literal>'.foo.'
LIKE 'f_o' COLLATE ign_punct</literal> is true because one can partition
<literal>.foo.</literal> into <literal>.f, o, o.</literal>, and then
<literal>'.f' = 'f' COLLATE ign_punct</literal>, <literal>'o'</literal>
matches the <literal>_</literal> wildcard, and <literal>'o.' = 'o' COLLATE
ign_punct</literal>. But <literal>'.foo.' LIKE '_oo' COLLATE
ign_punct</literal> is false because <literal>.foo.</literal> cannot be
partitioned in a way that the first character is any character and the
rest of the string compares equal to <literal>oo</literal>. (Note that
the single-character wildcard always matches exactly one character,
independent of the collation. So in this example, the
<literal>_</literal> would match <literal>.</literal>, but then the rest
of the input string won't match the rest of the pattern.)
</para>
<para>
<function>LIKE</function> pattern matching always covers the entire
string. Therefore, if it's desired to match a sequence anywhere within
a string, the pattern must start and end with a percent sign.
</para>
<para>
To match a literal underscore or percent sign without matching
other characters, the respective character in
<replaceable>pattern</replaceable> must be
preceded by the escape character. The default escape
character is the backslash but a different one can be selected by
using the <literal>ESCAPE</literal> clause. To match the escape
character itself, write two escape characters.
</para>
<note>
<para>
If you have <xref linkend="guc-standard-conforming-strings"/> turned off,
any backslashes you write in literal string constants will need to be
doubled. See <xref linkend="sql-syntax-strings"/> for more information.
</para>
</note>
<para>
It's also possible to select no escape character by writing
<literal>ESCAPE ''</literal>. This effectively disables the
escape mechanism, which makes it impossible to turn off the
special meaning of underscore and percent signs in the pattern.
</para>
<para>
According to the SQL standard, omitting <literal>ESCAPE</literal>
means there is no escape character (rather than defaulting to a
backslash), and a zero-length <literal>ESCAPE</literal> value is
disallowed. <productname>PostgreSQL</productname>'s behavior in
this regard is therefore slightly nonstandard.
</para>
<para>
The key word <token>ILIKE</token> can be used instead of
<token>LIKE</token> to make the match case-insensitive according to the
active locale. (But this does not support nondeterministic collations.)
This is not in the <acronym>SQL</acronym> standard but is a
<productname>PostgreSQL</productname> extension.
</para>
<para>
The operator <literal>~~</literal> is equivalent to
<function>LIKE</function>, and <literal>~~*</literal> corresponds to
<function>ILIKE</function>. There are also
<literal>!~~</literal> and <literal>!~~*</literal> operators that
represent <function>NOT LIKE</function> and <function>NOT
ILIKE</function>, respectively. All of these operators are
<productname>PostgreSQL</productname>-specific. You may see these
operator names in <command>EXPLAIN</command> output and similar
places, since the parser actually translates <function>LIKE</function>
et al. to these operators.
</para>
<para>
The phrases <function>LIKE</function>, <function>ILIKE</function>,
<function>NOT LIKE</function>, and <function>NOT ILIKE</function> are
generally treated as operators
in <productname>PostgreSQL</productname> syntax; for example they can
be used in <replaceable>expression</replaceable>
<replaceable>operator</replaceable> ANY
(<replaceable>subquery</replaceable>) constructs, although
an <literal>ESCAPE</literal> clause cannot be included there. In some
obscure cases it may be necessary to use the underlying operator names
instead.
</para>
<para>
Also see the starts-with operator <literal>^@</literal> and the
corresponding <function>starts_with()</function> function, which are
useful in cases where simply matching the beginning of a string is
needed.
</para>
</sect2>
<sect2 id="functions-similarto-regexp">
<title><function>SIMILAR TO</function> Regular Expressions</title>
<indexterm>
<primary>regular expression</primary>
<!-- <seealso>pattern matching</seealso> breaks index build -->
</indexterm>
<indexterm>
<primary>SIMILAR TO</primary>
</indexterm>
<indexterm>
<primary>substring</primary>
</indexterm>
<synopsis>
<replaceable>string</replaceable> SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
<replaceable>string</replaceable> NOT SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
</synopsis>
<para>
The <function>SIMILAR TO</function> operator returns true or
false depending on whether its pattern matches the given string.
It is similar to <function>LIKE</function>, except that it
interprets the pattern using the SQL standard's definition of a
regular expression. SQL regular expressions are a curious cross
between <function>LIKE</function> notation and common (POSIX) regular
expression notation.
</para>
<para>
Like <function>LIKE</function>, the <function>SIMILAR TO</function>
operator succeeds only if its pattern matches the entire string;
this is unlike common regular expression behavior where the pattern
can match any part of the string.
Also like
<function>LIKE</function>, <function>SIMILAR TO</function> uses
<literal>_</literal> and <literal>%</literal> as wildcard characters denoting
any single character and any string, respectively (these are
comparable to <literal>.</literal> and <literal>.*</literal> in POSIX regular
expressions).
</para>
<para>
In addition to these facilities borrowed from <function>LIKE</function>,
<function>SIMILAR TO</function> supports these pattern-matching
metacharacters borrowed from POSIX regular expressions:
<itemizedlist>
<listitem>
<para>
<literal>|</literal> denotes alternation (either of two alternatives).
</para>
</listitem>
<listitem>
<para>
<literal>*</literal> denotes repetition of the previous item zero
or more times.
</para>
</listitem>
<listitem>
<para>
<literal>+</literal> denotes repetition of the previous item one
or more times.
</para>
</listitem>
<listitem>
<para>
<literal>?</literal> denotes repetition of the previous item zero
or one time.
</para>
</listitem>
<listitem>
<para>
<literal>{</literal><replaceable>m</replaceable><literal>}</literal> denotes repetition
of the previous item exactly <replaceable>m</replaceable> times.
</para>
</listitem>
<listitem>
<para>
<literal>{</literal><replaceable>m</replaceable><literal>,}</literal> denotes repetition
of the previous item <replaceable>m</replaceable> or more times.
</para>
</listitem>
<listitem>
<para>
<literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable><literal>}</literal>
denotes repetition of the previous item at least <replaceable>m</replaceable> and
not more than <replaceable>n</replaceable> times.
</para>
</listitem>
<listitem>
<para>
Parentheses <literal>()</literal> can be used to group items into
a single logical item.
</para>
</listitem>
<listitem>
<para>
A bracket expression <literal>[...]</literal> specifies a character
class, just as in POSIX regular expressions.
</para>
</listitem>
</itemizedlist>
Notice that the period (<literal>.</literal>) is not a metacharacter
for <function>SIMILAR TO</function>.
</para>
<para>
As with <function>LIKE</function>, a backslash disables the special
meaning of any of these metacharacters. A different escape character
can be specified with <literal>ESCAPE</literal>, or the escape
capability can be disabled by writing <literal>ESCAPE ''</literal>.
</para>
<para>
According to the SQL standard, omitting <literal>ESCAPE</literal>
means there is no escape character (rather than defaulting to a
backslash), and a zero-length <literal>ESCAPE</literal> value is
disallowed. <productname>PostgreSQL</productname>'s behavior in
this regard is therefore slightly nonstandard.
</para>
<para>
Another nonstandard extension is that following the escape character
with a letter or digit provides access to the escape sequences
defined for POSIX regular expressions; see
<xref linkend="posix-character-entry-escapes-table"/>,
<xref linkend="posix-class-shorthand-escapes-table"/>, and
<xref linkend="posix-constraint-escapes-table"/> below.
</para>
<para>
Some examples:
<programlisting>
'abc' SIMILAR TO 'abc' <lineannotation>true</lineannotation>
'abc' SIMILAR TO 'a' <lineannotation>false</lineannotation>
'abc' SIMILAR TO '%(b|d)%' <lineannotation>true</lineannotation>
'abc' SIMILAR TO '(b|c)%' <lineannotation>false</lineannotation>
'-abc-' SIMILAR TO '%\mabc\M%' <lineannotation>true</lineannotation>
'xabcy' SIMILAR TO '%\mabc\M%' <lineannotation>false</lineannotation>
</programlisting>
</para>
<para>
The <function>substring</function> function with three parameters
provides extraction of a substring that matches an SQL
regular expression pattern. The function can be written according
to standard SQL syntax:
<synopsis>
substring(<replaceable>string</replaceable> similar <replaceable>pattern</replaceable> escape <replaceable>escape-character</replaceable>)
</synopsis>
or using the now obsolete SQL:1999 syntax:
<synopsis>
substring(<replaceable>string</replaceable> from <replaceable>pattern</replaceable> for <replaceable>escape-character</replaceable>)
</synopsis>
or as a plain three-argument function:
<synopsis>
substring(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>, <replaceable>escape-character</replaceable>)
</synopsis>
As with <literal>SIMILAR TO</literal>, the
specified pattern must match the entire data string, or else the
function fails and returns null. To indicate the part of the
pattern for which the matching data sub-string is of interest,
the pattern should contain
two occurrences of the escape character followed by a double quote
(<literal>"</literal>). <!-- " font-lock sanity -->
The text matching the portion of the pattern
between these separators is returned when the match is successful.
</para>
<para>
The escape-double-quote separators actually
divide <function>substring</function>'s pattern into three independent
regular expressions; for example, a vertical bar (<literal>|</literal>)
in any of the three sections affects only that section. Also, the first
and third of these regular expressions are defined to match the smallest
possible amount of text, not the largest, when there is any ambiguity
about how much of the data string matches which pattern. (In POSIX
parlance, the first and third regular expressions are forced to be
non-greedy.)
</para>
<para>
As an extension to the SQL standard, <productname>PostgreSQL</productname>
allows there to be just one escape-double-quote separator, in which case
the third regular expression is taken as empty; or no separators, in which
case the first and third regular expressions are taken as empty.
</para>
<para>
Some examples, with <literal>#"</literal> delimiting the return string:
<programlisting>
substring('foobar' similar '%#"o_b#"%' escape '#') <lineannotation>oob</lineannotation>
substring('foobar' similar '#"o_b#"%' escape '#') <lineannotation>NULL</lineannotation>
</programlisting>
</para>
</sect2>
<sect2 id="functions-posix-regexp">
<title><acronym>POSIX</acronym> Regular Expressions</title>
<indexterm zone="functions-posix-regexp">
<primary>regular expression</primary>
<seealso>pattern matching</seealso>
</indexterm>
<indexterm>
<primary>substring</primary>
</indexterm>
<indexterm>
<primary>regexp_count</primary>
</indexterm>
<indexterm>
<primary>regexp_instr</primary>
</indexterm>
<indexterm>
<primary>regexp_like</primary>
</indexterm>
<indexterm>
<primary>regexp_match</primary>
</indexterm>
<indexterm>
<primary>regexp_matches</primary>
</indexterm>
<indexterm>
<primary>regexp_replace</primary>
</indexterm>
<indexterm>
<primary>regexp_split_to_table</primary>
</indexterm>
<indexterm>
<primary>regexp_split_to_array</primary>
</indexterm>
<indexterm>
<primary>regexp_substr</primary>
</indexterm>
<para>
<xref linkend="functions-posix-table"/> lists the available
operators for pattern matching using POSIX regular expressions.
</para>
<table id="functions-posix-table">
<title>Regular Expression Match Operators</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Operator
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>text</type> <literal>~</literal> <type>text</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
String matches regular expression, case sensitively
</para>
<para>
<literal>'thomas' ~ 't.*ma'</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>text</type> <literal>~*</literal> <type>text</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
String matches regular expression, case-insensitively
</para>
<para>
<literal>'thomas' ~* 'T.*ma'</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>text</type> <literal>!~</literal> <type>text</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
String does not match regular expression, case sensitively
</para>
<para>
<literal>'thomas' !~ 't.*max'</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<type>text</type> <literal>!~*</literal> <type>text</type>
<returnvalue>boolean</returnvalue>
</para>
<para>
String does not match regular expression, case-insensitively
</para>
<para>
<literal>'thomas' !~* 'T.*ma'</literal>
<returnvalue>f</returnvalue>
</para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<acronym>POSIX</acronym> regular expressions provide a more
powerful means for pattern matching than the <function>LIKE</function> and
<function>SIMILAR TO</function> operators.
Many Unix tools such as <command>egrep</command>,
<command>sed</command>, or <command>awk</command> use a pattern
matching language that is similar to the one described here.
</para>
<para>
A regular expression is a character sequence that is an
abbreviated definition of a set of strings (a <firstterm>regular
set</firstterm>). A string is said to match a regular expression
if it is a member of the regular set described by the regular
expression. As with <function>LIKE</function>, pattern characters
match string characters exactly unless they are special characters
in the regular expression language — but regular expressions use
different special characters than <function>LIKE</function> does.
Unlike <function>LIKE</function> patterns, a
regular expression is allowed to match anywhere within a string, unless
the regular expression is explicitly anchored to the beginning or
end of the string.
</para>
<para>
Some examples:
<programlisting>
'abcd' ~ 'bc' <lineannotation>true</lineannotation>
'abcd' ~ 'a.c' <lineannotation>true — dot matches any character</lineannotation>
'abcd' ~ 'a.*d' <lineannotation>true — <literal>*</literal> repeats the preceding pattern item</lineannotation>
'abcd' ~ '(b|x)' <lineannotation>true — <literal>|</literal> means OR, parentheses group</lineannotation>
'abcd' ~ '^a' <lineannotation>true — <literal>^</literal> anchors to start of string</lineannotation>
'abcd' ~ '^(b|c)' <lineannotation>false — would match except for anchoring</lineannotation>
</programlisting>
</para>
<para>
The <acronym>POSIX</acronym> pattern language is described in much
greater detail below.
</para>
<para>
The <function>substring</function> function with two parameters,
<function>substring(<replaceable>string</replaceable> from
<replaceable>pattern</replaceable>)</function>, provides extraction of a
substring
that matches a POSIX regular expression pattern. It returns null if
there is no match, otherwise the first portion of the text that matched the
pattern. But if the pattern contains any parentheses, the portion
of the text that matched the first parenthesized subexpression (the
one whose left parenthesis comes first) is
returned. You can put parentheses around the whole expression
if you want to use parentheses within it without triggering this
exception. If you need parentheses in the pattern before the
subexpression you want to extract, see the non-capturing parentheses
described below.
</para>
<para>
Some examples:
<programlisting>
substring('foobar' from 'o.b') <lineannotation>oob</lineannotation>
substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
</programlisting>
</para>
<para>
The <function>regexp_count</function> function counts the number of
places where a POSIX regular expression pattern matches a string.
It has the syntax
<function>regexp_count</function>(<replaceable>string</replaceable>,
<replaceable>pattern</replaceable>
<optional>, <replaceable>start</replaceable>
<optional>, <replaceable>flags</replaceable>
</optional></optional>).
<replaceable>pattern</replaceable> is searched for
in <replaceable>string</replaceable>, normally from the beginning of
the string, but if the <replaceable>start</replaceable> parameter is
provided then beginning from that character index.
The <replaceable>flags</replaceable> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. For example, including <literal>i</literal> in
<replaceable>flags</replaceable> specifies case-insensitive matching.
Supported flags are described in
<xref linkend="posix-embedded-options-table"/>.
</para>
<para>
Some examples:
<programlisting>
regexp_count('ABCABCAXYaxy', 'A.') <lineannotation>3</lineannotation>
regexp_count('ABCABCAXYaxy', 'A.', 1, 'i') <lineannotation>4</lineannotation>
</programlisting>
</para>
<para>
The <function>regexp_instr</function> function returns the starting or
ending position of the <replaceable>N</replaceable>'th match of a
POSIX regular expression pattern to a string, or zero if there is no
such match. It has the syntax
<function>regexp_instr</function>(<replaceable>string</replaceable>,
<replaceable>pattern</replaceable>
<optional>, <replaceable>start</replaceable>
<optional>, <replaceable>N</replaceable>
<optional>, <replaceable>endoption</replaceable>
<optional>, <replaceable>flags</replaceable>
<optional>, <replaceable>subexpr</replaceable>
</optional></optional></optional></optional></optional>).
<replaceable>pattern</replaceable> is searched for
in <replaceable>string</replaceable>, normally from the beginning of
the string, but if the <replaceable>start</replaceable> parameter is
provided then beginning from that character index.
If <replaceable>N</replaceable> is specified
then the <replaceable>N</replaceable>'th match of the pattern
is located, otherwise the first match is located.
If the <replaceable>endoption</replaceable> parameter is omitted or
specified as zero, the function returns the position of the first
character of the match. Otherwise, <replaceable>endoption</replaceable>
must be one, and the function returns the position of the character
following the match.
The <replaceable>flags</replaceable> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. Supported flags are described
in <xref linkend="posix-embedded-options-table"/>.
For a pattern containing parenthesized
subexpressions, <replaceable>subexpr</replaceable> is an integer
indicating which subexpression is of interest: the result identifies
the position of the substring matching that subexpression.
Subexpressions are numbered in the order of their leading parentheses.
When <replaceable>subexpr</replaceable> is omitted or zero, the result
identifies the position of the whole match regardless of
parenthesized subexpressions.
</para>
<para>
Some examples:
<programlisting>
regexp_instr('number of your street, town zip, FR', '[^,]+', 1, 2)
<lineannotation>23</lineannotation>
regexp_instr(string=>'ABCDEFGHI', pattern=>'(c..)(...)', start=>1, "N"=>1, endoption=>0, flags=>'i', subexpr=>2)
<lineannotation>6</lineannotation>
</programlisting>
</para>
<para>
The <function>regexp_like</function> function checks whether a match
of a POSIX regular expression pattern occurs within a string,
returning boolean true or false. It has the syntax
<function>regexp_like</function>(<replaceable>string</replaceable>,
<replaceable>pattern</replaceable>
<optional>, <replaceable>flags</replaceable> </optional>).
The <replaceable>flags</replaceable> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. Supported flags are described
in <xref linkend="posix-embedded-options-table"/>.
This function has the same results as the <literal>~</literal>
operator if no flags are specified. If only the <literal>i</literal>
flag is specified, it has the same results as
the <literal>~*</literal> operator.
</para>
<para>
Some examples:
<programlisting>
regexp_like('Hello World', 'world') <lineannotation>false</lineannotation>
regexp_like('Hello World', 'world', 'i') <lineannotation>true</lineannotation>
</programlisting>
</para>
<para>
The <function>regexp_match</function> function returns a text array of
matching substring(s) within the first match of a POSIX
regular expression pattern to a string. It has the syntax
<function>regexp_match</function>(<replaceable>string</replaceable>,
<replaceable>pattern</replaceable> <optional>, <replaceable>flags</replaceable> </optional>).
If there is no match, the result is <literal>NULL</literal>.
If a match is found, and the <replaceable>pattern</replaceable> contains no
parenthesized subexpressions, then the result is a single-element text
array containing the substring matching the whole pattern.
If a match is found, and the <replaceable>pattern</replaceable> contains
parenthesized subexpressions, then the result is a text array
whose <replaceable>n</replaceable>'th element is the substring matching
the <replaceable>n</replaceable>'th parenthesized subexpression of
the <replaceable>pattern</replaceable> (not counting <quote>non-capturing</quote>
parentheses; see below for details).
The <replaceable>flags</replaceable> parameter is an optional text string
containing zero or more single-letter flags that change the function's
behavior. Supported flags are described
in <xref linkend="posix-embedded-options-table"/>.
</para>
<para>
Some examples:
<programlisting>
SELECT regexp_match('foobarbequebaz', 'bar.*que');
regexp_match
--------------
{barbeque}
(1 row)
SELECT regexp_match('foobarbequebaz', '(bar)(beque)');
regexp_match
--------------
{bar,beque}
(1 row)
</programlisting>
</para>
<tip>
<para>
In the common case where you just want the whole matching substring
or <literal>NULL</literal> for no match, the best solution is to
use <function>regexp_substr()</function>.
However, <function>regexp_substr()</function> only exists
in <productname>PostgreSQL</productname> version 15 and up. When
working in older versions, you can extract the first element
of <function>regexp_match()</function>'s result, for example:
<programlisting>
SELECT (regexp_match('foobarbequebaz', 'bar.*que'))[1];
regexp_match
--------------
barbeque
(1 row)
</programlisting>
</para>
</tip>
<para>
The <function>regexp_matches</function> function returns a set of text arrays
of matching substring(s) within matches of a POSIX regular
expression pattern to a string. It has the same syntax as
<function>regexp_match</function>.
This function returns no rows if there is no match, one row if there is
a match and the <literal>g</literal> flag is not given, or <replaceable>N</replaceable>
rows if there are <replaceable>N</replaceable> matches and the <literal>g</literal> flag
is given. Each returned row is a text array containing the whole
matched substring or the substrings matching parenthesized
subexpressions of the <replaceable>pattern</replaceable>, just as described above
for <function>regexp_match</function>.
<function>regexp_matches</function> accepts all the flags shown
in <xref linkend="posix-embedded-options-table"/>, plus
the <literal>g</literal> flag which commands it to return all matches, not
just the first one.
</para>
<para>
Some examples:
<programlisting>
SELECT regexp_matches('foo', 'not there');
regexp_matches
----------------
(0 rows)
SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g');
regexp_matches
----------------
{bar,beque}
{bazil,barf}
(2 rows)
</programlisting>
</para>
<tip>
<para>
In most cases <function>regexp_matches()</function> should be used with
the <literal>g</literal> flag, since if you only want the first match, it's
easier and more efficient to use <function>regexp_match()</function>.
However, <function>regexp_match()</function> only exists
in <productname>PostgreSQL</productname> version 10 and up. When working in older
versions, a common trick is to place a <function>regexp_matches()</function>
call in a sub-select, for example:
<programlisting>
SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
</programlisting>
This produces a text array if there's a match, or <literal>NULL</literal> if
not, the same as <function>regexp_match()</function> would do. Without the
sub-select, this query would produce no output at all for table rows
without a match, which is typically not the desired behavior.
</para>
</tip>
<para>
The <function>regexp_replace</function> function provides substitution of
new text for substrings that match POSIX regular expression patterns.
It has the syntax
<function>regexp_replace</function>(<replaceable>string</replaceable>,
<replaceable>pattern</replaceable>, <replaceable>replacement</replaceable>
<optional>, <replaceable>flags</replaceable> </optional>)
or
<function>regexp_replace</function>(<replaceable>string</replaceable>,
<replaceable>pattern</replaceable>, <replaceable>replacement</replaceable>,
<replaceable>start</replaceable>
<optional>, <replaceable>N</replaceable>
<optional>, <replaceable>flags</replaceable> </optional></optional>).
The source <replaceable>string</replaceable> is returned unchanged if
there is no match to the <replaceable>pattern</replaceable>. If there is a
match, the <replaceable>string</replaceable> is returned with the
<replaceable>replacement</replaceable> string substituted for the matching
substring. The <replaceable>replacement</replaceable> string can contain
<literal>\</literal><replaceable>n</replaceable>, where <replaceable>n</replaceable> is 1
through 9, to indicate that the source substring matching the
<replaceable>n</replaceable>'th parenthesized subexpression of the pattern should be
inserted, and it can contain <literal>\&</literal> to indicate that the
substring matching the entire pattern should be inserted. Write
<literal>\\</literal> if you need to put a literal backslash in the replacement
text.
<replaceable>pattern</replaceable> is searched for
in <replaceable>string</replaceable>, normally from the beginning of
the string, but if the <replaceable>start</replaceable> parameter is
provided then beginning from that character index.
By default, only the first match of the pattern is replaced.
If <replaceable>N</replaceable> is specified and is greater than zero,
then the <replaceable>N</replaceable>'th match of the pattern
is replaced.
If the <literal>g</literal> flag is given, or
if <replaceable>N</replaceable> is specified and is zero, then all
matches at or after the <replaceable>start</replaceable> position are
replaced. (The <literal>g</literal> flag is ignored
when <replaceable>N</replaceable> is specified.)
The <replaceable>flags</replaceable> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. Supported flags (though
not <literal>g</literal>) are
described in <xref linkend="posix-embedded-options-table"/>.
</para>
<para>
Some examples:
<programlisting>
regexp_replace('foobarbaz', 'b..', 'X')
<lineannotation>fooXbaz</lineannotation>
regexp_replace('foobarbaz', 'b..', 'X', 'g')
<lineannotation>fooXX</lineannotation>
regexp_replace('foobarbaz', 'b(..)', 'X\1Y', 'g')
<lineannotation>fooXarYXazY</lineannotation>
regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 0, 'i')
<lineannotation>X PXstgrXSQL fXnctXXn</lineannotation>
regexp_replace(string=>'A PostgreSQL function', pattern=>'a|e|i|o|u', replacement=>'X', start=>1, "N"=>3, flags=>'i')
<lineannotation>A PostgrXSQL function</lineannotation>
</programlisting>
</para>
<para>
The <function>regexp_split_to_table</function> function splits a string using a POSIX
regular expression pattern as a delimiter. It has the syntax
<function>regexp_split_to_table</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>
<optional>, <replaceable>flags</replaceable> </optional>).
If there is no match to the <replaceable>pattern</replaceable>, the function returns the
<replaceable>string</replaceable>. If there is at least one match, for each match it returns
the text from the end of the last match (or the beginning of the string)
to the beginning of the match. When there are no more matches, it
returns the text from the end of the last match to the end of the string.
The <replaceable>flags</replaceable> parameter is an optional text string containing
zero or more single-letter flags that change the function's behavior.
<function>regexp_split_to_table</function> supports the flags described in
<xref linkend="posix-embedded-options-table"/>.
</para>
<para>
The <function>regexp_split_to_array</function> function behaves the same as
<function>regexp_split_to_table</function>, except that <function>regexp_split_to_array</function>
returns its result as an array of <type>text</type>. It has the syntax
<function>regexp_split_to_array</function>(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>
<optional>, <replaceable>flags</replaceable> </optional>).
The parameters are the same as for <function>regexp_split_to_table</function>.
</para>
<para>
Some examples:
<programlisting>
SELECT foo FROM regexp_split_to_table('the quick brown fox jumps over the lazy dog', '\s+') AS foo;
foo
-------
the
quick
brown
fox
jumps
over
the
lazy
dog
(9 rows)
SELECT regexp_split_to_array('the quick brown fox jumps over the lazy dog', '\s+');
regexp_split_to_array
-----------------------------------------------
{the,quick,brown,fox,jumps,over,the,lazy,dog}
(1 row)
SELECT foo FROM regexp_split_to_table('the quick brown fox', '\s*') AS foo;
foo
-----
t
h
e
q
u
i
c
k
b
r
o
w
n
f
o
x
(16 rows)
</programlisting>
</para>
<para>
As the last example demonstrates, the regexp split functions ignore
zero-length matches that occur at the start or end of the string
or immediately after a previous match. This is contrary to the strict
definition of regexp matching that is implemented by
the other regexp functions, but is usually the most convenient behavior
in practice. Other software systems such as Perl use similar definitions.
</para>
<para>
The <function>regexp_substr</function> function returns the substring
that matches a POSIX regular expression pattern,
or <literal>NULL</literal> if there is no match. It has the syntax
<function>regexp_substr</function>(<replaceable>string</replaceable>,
<replaceable>pattern</replaceable>
<optional>, <replaceable>start</replaceable>
<optional>, <replaceable>N</replaceable>
<optional>, <replaceable>flags</replaceable>
<optional>, <replaceable>subexpr</replaceable>
</optional></optional></optional></optional>).
<replaceable>pattern</replaceable> is searched for
in <replaceable>string</replaceable>, normally from the beginning of
the string, but if the <replaceable>start</replaceable> parameter is
provided then beginning from that character index.
If <replaceable>N</replaceable> is specified
then the <replaceable>N</replaceable>'th match of the pattern
is returned, otherwise the first match is returned.
The <replaceable>flags</replaceable> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. Supported flags are described
in <xref linkend="posix-embedded-options-table"/>.
For a pattern containing parenthesized
subexpressions, <replaceable>subexpr</replaceable> is an integer
indicating which subexpression is of interest: the result is the
substring matching that subexpression.
Subexpressions are numbered in the order of their leading parentheses.
When <replaceable>subexpr</replaceable> is omitted or zero, the result
is the whole match regardless of parenthesized subexpressions.
</para>
<para>
Some examples:
<programlisting>
regexp_substr('number of your street, town zip, FR', '[^,]+', 1, 2)
<lineannotation> town zip</lineannotation>
regexp_substr('ABCDEFGHI', '(c..)(...)', 1, 1, 'i', 2)
<lineannotation>FGH</lineannotation>
</programlisting>
</para>
<!-- derived from the re_syntax.n man page -->
<sect3 id="posix-syntax-details">
<title>Regular Expression Details</title>
<para>
<productname>PostgreSQL</productname>'s regular expressions are implemented
using a software package written by Henry Spencer. Much of
the description of regular expressions below is copied verbatim from his
manual.
</para>
<para>
Regular expressions (<acronym>RE</acronym>s), as defined in
<acronym>POSIX</acronym> 1003.2, come in two forms:
<firstterm>extended</firstterm> <acronym>RE</acronym>s or <acronym>ERE</acronym>s
(roughly those of <command>egrep</command>), and
<firstterm>basic</firstterm> <acronym>RE</acronym>s or <acronym>BRE</acronym>s
(roughly those of <command>ed</command>).
<productname>PostgreSQL</productname> supports both forms, and
also implements some extensions
that are not in the POSIX standard, but have become widely used
due to their availability in programming languages such as Perl and Tcl.
<acronym>RE</acronym>s using these non-POSIX extensions are called
<firstterm>advanced</firstterm> <acronym>RE</acronym>s or <acronym>ARE</acronym>s
in this documentation. AREs are almost an exact superset of EREs,
but BREs have several notational incompatibilities (as well as being
much more limited).
We first describe the ARE and ERE forms, noting features that apply
only to AREs, and then describe how BREs differ.
</para>
<note>
<para>
<productname>PostgreSQL</productname> always initially presumes that a regular
expression follows the ARE rules. However, the more limited ERE or
BRE rules can be chosen by prepending an <firstterm>embedded option</firstterm>
to the RE pattern, as described in <xref linkend="posix-metasyntax"/>.
This can be useful for compatibility with applications that expect
exactly the <acronym>POSIX</acronym> 1003.2 rules.
</para>
</note>
<para>
A regular expression is defined as one or more
<firstterm>branches</firstterm>, separated by
<literal>|</literal>. It matches anything that matches one of the
branches.
</para>
<para>
A branch is zero or more <firstterm>quantified atoms</firstterm> or
<firstterm>constraints</firstterm>, concatenated.
It matches a match for the first, followed by a match for the second, etc.;
an empty branch matches the empty string.
</para>
<para>
A quantified atom is an <firstterm>atom</firstterm> possibly followed
by a single <firstterm>quantifier</firstterm>.
Without a quantifier, it matches a match for the atom.
With a quantifier, it can match some number of matches of the atom.
An <firstterm>atom</firstterm> can be any of the possibilities
shown in <xref linkend="posix-atoms-table"/>.
The possible quantifiers and their meanings are shown in
<xref linkend="posix-quantifiers-table"/>.
</para>
<para>
A <firstterm>constraint</firstterm> matches an empty string, but matches only when
specific conditions are met. A constraint can be used where an atom
could be used, except it cannot be followed by a quantifier.
The simple constraints are shown in
<xref linkend="posix-constraints-table"/>;
some more constraints are described later.
</para>
<table id="posix-atoms-table">
<title>Regular Expression Atoms</title>
<tgroup cols="2">
<thead>
<row>
<entry>Atom</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>(</literal><replaceable>re</replaceable><literal>)</literal> </entry>
<entry> (where <replaceable>re</replaceable> is any regular expression)
matches a match for
<replaceable>re</replaceable>, with the match noted for possible reporting </entry>
</row>
<row>
<entry> <literal>(?:</literal><replaceable>re</replaceable><literal>)</literal> </entry>
<entry> as above, but the match is not noted for reporting
(a <quote>non-capturing</quote> set of parentheses)
(AREs only) </entry>
</row>
<row>
<entry> <literal>.</literal> </entry>
<entry> matches any single character </entry>
</row>
<row>
<entry> <literal>[</literal><replaceable>chars</replaceable><literal>]</literal> </entry>
<entry> a <firstterm>bracket expression</firstterm>,
matching any one of the <replaceable>chars</replaceable> (see
<xref linkend="posix-bracket-expressions"/> for more detail) </entry>
</row>
<row>
<entry> <literal>\</literal><replaceable>k</replaceable> </entry>
<entry> (where <replaceable>k</replaceable> is a non-alphanumeric character)
matches that character taken as an ordinary character,
e.g., <literal>\\</literal> matches a backslash character </entry>
</row>
<row>
<entry> <literal>\</literal><replaceable>c</replaceable> </entry>
<entry> where <replaceable>c</replaceable> is alphanumeric
(possibly followed by other characters)
is an <firstterm>escape</firstterm>, see <xref linkend="posix-escape-sequences"/>
(AREs only; in EREs and BREs, this matches <replaceable>c</replaceable>) </entry>
</row>
<row>
<entry> <literal>{</literal> </entry>
<entry> when followed by a character other than a digit,
matches the left-brace character <literal>{</literal>;
when followed by a digit, it is the beginning of a
<replaceable>bound</replaceable> (see below) </entry>
</row>
<row>
<entry> <replaceable>x</replaceable> </entry>
<entry> where <replaceable>x</replaceable> is a single character with no other
significance, matches that character </entry>
</row>
</tbody>
</tgroup>
</table>
<para>
An RE cannot end with a backslash (<literal>\</literal>).
</para>
<note>
<para>
If you have <xref linkend="guc-standard-conforming-strings"/> turned off,
any backslashes you write in literal string constants will need to be
doubled. See <xref linkend="sql-syntax-strings"/> for more information.
</para>
</note>
<table id="posix-quantifiers-table">
<title>Regular Expression Quantifiers</title>
<tgroup cols="2">
<thead>
<row>
<entry>Quantifier</entry>
<entry>Matches</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>*</literal> </entry>
<entry> a sequence of 0 or more matches of the atom </entry>
</row>
<row>
<entry> <literal>+</literal> </entry>
<entry> a sequence of 1 or more matches of the atom </entry>
</row>
<row>
<entry> <literal>?</literal> </entry>
<entry> a sequence of 0 or 1 matches of the atom </entry>
</row>
<row>
<entry> <literal>{</literal><replaceable>m</replaceable><literal>}</literal> </entry>
<entry> a sequence of exactly <replaceable>m</replaceable> matches of the atom </entry>
</row>
<row>
<entry> <literal>{</literal><replaceable>m</replaceable><literal>,}</literal> </entry>
<entry> a sequence of <replaceable>m</replaceable> or more matches of the atom </entry>
</row>
<row>
<entry>
<literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable><literal>}</literal> </entry>
<entry> a sequence of <replaceable>m</replaceable> through <replaceable>n</replaceable>
(inclusive) matches of the atom; <replaceable>m</replaceable> cannot exceed
<replaceable>n</replaceable> </entry>
</row>
<row>
<entry> <literal>*?</literal> </entry>
<entry> non-greedy version of <literal>*</literal> </entry>
</row>
<row>
<entry> <literal>+?</literal> </entry>
<entry> non-greedy version of <literal>+</literal> </entry>
</row>
<row>
<entry> <literal>??</literal> </entry>
<entry> non-greedy version of <literal>?</literal> </entry>
</row>
<row>
<entry> <literal>{</literal><replaceable>m</replaceable><literal>}?</literal> </entry>
<entry> non-greedy version of <literal>{</literal><replaceable>m</replaceable><literal>}</literal> </entry>
</row>
<row>
<entry> <literal>{</literal><replaceable>m</replaceable><literal>,}?</literal> </entry>
<entry> non-greedy version of <literal>{</literal><replaceable>m</replaceable><literal>,}</literal> </entry>
</row>
<row>
<entry>
<literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable><literal>}?</literal> </entry>
<entry> non-greedy version of <literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable><literal>}</literal> </entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The forms using <literal>{</literal><replaceable>...</replaceable><literal>}</literal>
are known as <firstterm>bounds</firstterm>.
The numbers <replaceable>m</replaceable> and <replaceable>n</replaceable> within a bound are
unsigned decimal integers with permissible values from 0 to 255 inclusive.
</para>
<para>
<firstterm>Non-greedy</firstterm> quantifiers (available in AREs only) match the
same possibilities as their corresponding normal (<firstterm>greedy</firstterm>)
counterparts, but prefer the smallest number rather than the largest
number of matches.
See <xref linkend="posix-matching-rules"/> for more detail.
</para>
<note>
<para>
A quantifier cannot immediately follow another quantifier, e.g.,
<literal>**</literal> is invalid.
A quantifier cannot
begin an expression or subexpression or follow
<literal>^</literal> or <literal>|</literal>.
</para>
</note>
<table id="posix-constraints-table">
<title>Regular Expression Constraints</title>
<tgroup cols="2">
<thead>
<row>
<entry>Constraint</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>^</literal> </entry>
<entry> matches at the beginning of the string </entry>
</row>
<row>
<entry> <literal>$</literal> </entry>
<entry> matches at the end of the string </entry>
</row>
<row>
<entry> <literal>(?=</literal><replaceable>re</replaceable><literal>)</literal> </entry>
<entry> <firstterm>positive lookahead</firstterm> matches at any point
where a substring matching <replaceable>re</replaceable> begins
(AREs only) </entry>
</row>
<row>
<entry> <literal>(?!</literal><replaceable>re</replaceable><literal>)</literal> </entry>
<entry> <firstterm>negative lookahead</firstterm> matches at any point
where no substring matching <replaceable>re</replaceable> begins
(AREs only) </entry>
</row>
<row>
<entry> <literal>(?<=</literal><replaceable>re</replaceable><literal>)</literal> </entry>
<entry> <firstterm>positive lookbehind</firstterm> matches at any point
where a substring matching <replaceable>re</replaceable> ends
(AREs only) </entry>
</row>
<row>
<entry> <literal>(?<!</literal><replaceable>re</replaceable><literal>)</literal> </entry>
<entry> <firstterm>negative lookbehind</firstterm> matches at any point
where no substring matching <replaceable>re</replaceable> ends
(AREs only) </entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Lookahead and lookbehind constraints cannot contain <firstterm>back
references</firstterm> (see <xref linkend="posix-escape-sequences"/>),
and all parentheses within them are considered non-capturing.
</para>
</sect3>
<sect3 id="posix-bracket-expressions">
<title>Bracket Expressions</title>
<para>
A <firstterm>bracket expression</firstterm> is a list of
characters enclosed in <literal>[]</literal>. It normally matches
any single character from the list (but see below). If the list
begins with <literal>^</literal>, it matches any single character
<emphasis>not</emphasis> from the rest of the list.
If two characters
in the list are separated by <literal>-</literal>, this is
shorthand for the full range of characters between those two
(inclusive) in the collating sequence,
e.g., <literal>[0-9]</literal> in <acronym>ASCII</acronym> matches
any decimal digit. It is illegal for two ranges to share an
endpoint, e.g., <literal>a-c-e</literal>. Ranges are very
collating-sequence-dependent, so portable programs should avoid
relying on them.
</para>
<para>
To include a literal <literal>]</literal> in the list, make it the
first character (after <literal>^</literal>, if that is used). To
include a literal <literal>-</literal>, make it the first or last
character, or the second endpoint of a range. To use a literal
<literal>-</literal> as the first endpoint of a range, enclose it
in <literal>[.</literal> and <literal>.]</literal> to make it a
collating element (see below). With the exception of these characters,
some combinations using <literal>[</literal>
(see next paragraphs), and escapes (AREs only), all other special
characters lose their special significance within a bracket expression.
In particular, <literal>\</literal> is not special when following
ERE or BRE rules, though it is special (as introducing an escape)
in AREs.
</para>
<para>
Within a bracket expression, a collating element (a character, a
multiple-character sequence that collates as if it were a single
character, or a collating-sequence name for either) enclosed in
<literal>[.</literal> and <literal>.]</literal> stands for the
sequence of characters of that collating element. The sequence is
treated as a single element of the bracket expression's list. This
allows a bracket
expression containing a multiple-character collating element to
match more than one character, e.g., if the collating sequence
includes a <literal>ch</literal> collating element, then the RE
<literal>[[.ch.]]*c</literal> matches the first five characters of
<literal>chchcc</literal>.
</para>
<note>
<para>
<productname>PostgreSQL</productname> currently does not support multi-character collating
elements. This information describes possible future behavior.
</para>
</note>
<para>
Within a bracket expression, a collating element enclosed in
<literal>[=</literal> and <literal>=]</literal> is an <firstterm>equivalence
class</firstterm>, standing for the sequences of characters of all collating
elements equivalent to that one, including itself. (If there are
no other equivalent collating elements, the treatment is as if the
enclosing delimiters were <literal>[.</literal> and
<literal>.]</literal>.) For example, if <literal>o</literal> and
<literal>^</literal> are the members of an equivalence class, then
<literal>[[=o=]]</literal>, <literal>[[=^=]]</literal>, and
<literal>[o^]</literal> are all synonymous. An equivalence class
cannot be an endpoint of a range.
</para>
<para>
Within a bracket expression, the name of a character class
enclosed in <literal>[:</literal> and <literal>:]</literal> stands
for the list of all characters belonging to that class. A character
class cannot be used as an endpoint of a range.
The <acronym>POSIX</acronym> standard defines these character class
names:
<literal>alnum</literal> (letters and numeric digits),
<literal>alpha</literal> (letters),
<literal>blank</literal> (space and tab),
<literal>cntrl</literal> (control characters),
<literal>digit</literal> (numeric digits),
<literal>graph</literal> (printable characters except space),
<literal>lower</literal> (lower-case letters),
<literal>print</literal> (printable characters including space),
<literal>punct</literal> (punctuation),
<literal>space</literal> (any white space),
<literal>upper</literal> (upper-case letters),
and <literal>xdigit</literal> (hexadecimal digits).
The behavior of these standard character classes is generally
consistent across platforms for characters in the 7-bit ASCII set.
Whether a given non-ASCII character is considered to belong to one
of these classes depends on the <firstterm>collation</firstterm>
that is used for the regular-expression function or operator
(see <xref linkend="collation"/>), or by default on the
database's <envar>LC_CTYPE</envar> locale setting (see
<xref linkend="locale"/>). The classification of non-ASCII
characters can vary across platforms even in similarly-named
locales. (But the <literal>C</literal> locale never considers any
non-ASCII characters to belong to any of these classes.)
In addition to these standard character
classes, <productname>PostgreSQL</productname> defines
the <literal>word</literal> character class, which is the same as
<literal>alnum</literal> plus the underscore (<literal>_</literal>)
character, and
the <literal>ascii</literal> character class, which contains exactly
the 7-bit ASCII set.
</para>
<para>
There are two special cases of bracket expressions: the bracket
expressions <literal>[[:<:]]</literal> and
<literal>[[:>:]]</literal> are constraints,
matching empty strings at the beginning
and end of a word respectively. A word is defined as a sequence
of word characters that is neither preceded nor followed by word
characters. A word character is any character belonging to the
<literal>word</literal> character class, that is, any letter, digit,
or underscore. This is an extension, compatible with but not
specified by <acronym>POSIX</acronym> 1003.2, and should be used with
caution in software intended to be portable to other systems.
The constraint escapes described below are usually preferable; they
are no more standard, but are easier to type.
</para>
</sect3>
<sect3 id="posix-escape-sequences">
<title>Regular Expression Escapes</title>
<para>
<firstterm>Escapes</firstterm> are special sequences beginning with <literal>\</literal>
followed by an alphanumeric character. Escapes come in several varieties:
character entry, class shorthands, constraint escapes, and back references.
A <literal>\</literal> followed by an alphanumeric character but not constituting
a valid escape is illegal in AREs.
In EREs, there are no escapes: outside a bracket expression,
a <literal>\</literal> followed by an alphanumeric character merely stands for
that character as an ordinary character, and inside a bracket expression,
<literal>\</literal> is an ordinary character.
(The latter is the one actual incompatibility between EREs and AREs.)
</para>
<para>
<firstterm>Character-entry escapes</firstterm> exist to make it easier to specify
non-printing and other inconvenient characters in REs. They are
shown in <xref linkend="posix-character-entry-escapes-table"/>.
</para>
<para>
<firstterm>Class-shorthand escapes</firstterm> provide shorthands for certain
commonly-used character classes. They are
shown in <xref linkend="posix-class-shorthand-escapes-table"/>.
</para>
<para>
A <firstterm>constraint escape</firstterm> is a constraint,
matching the empty string if specific conditions are met,
written as an escape. They are
shown in <xref linkend="posix-constraint-escapes-table"/>.
</para>
<para>
A <firstterm>back reference</firstterm> (<literal>\</literal><replaceable>n</replaceable>) matches the
same string matched by the previous parenthesized subexpression specified
by the number <replaceable>n</replaceable>
(see <xref linkend="posix-constraint-backref-table"/>). For example,
<literal>([bc])\1</literal> matches <literal>bb</literal> or <literal>cc</literal>
but not <literal>bc</literal> or <literal>cb</literal>.
The subexpression must entirely precede the back reference in the RE.
Subexpressions are numbered in the order of their leading parentheses.
Non-capturing parentheses do not define subexpressions.
The back reference considers only the string characters matched by the
referenced subexpression, not any constraints contained in it. For
example, <literal>(^\d)\1</literal> will match <literal>22</literal>.
</para>
<table id="posix-character-entry-escapes-table">
<title>Regular Expression Character-Entry Escapes</title>
<tgroup cols="2">
<thead>
<row>
<entry>Escape</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>\a</literal> </entry>
<entry> alert (bell) character, as in C </entry>
</row>
<row>
<entry> <literal>\b</literal> </entry>
<entry> backspace, as in C </entry>
</row>
<row>
<entry> <literal>\B</literal> </entry>
<entry> synonym for backslash (<literal>\</literal>) to help reduce the need for backslash
doubling </entry>
</row>
<row>
<entry> <literal>\c</literal><replaceable>X</replaceable> </entry>
<entry> (where <replaceable>X</replaceable> is any character) the character whose
low-order 5 bits are the same as those of
<replaceable>X</replaceable>, and whose other bits are all zero </entry>
</row>
<row>
<entry> <literal>\e</literal> </entry>
<entry> the character whose collating-sequence name
is <literal>ESC</literal>,
or failing that, the character with octal value <literal>033</literal> </entry>
</row>
<row>
<entry> <literal>\f</literal> </entry>
<entry> form feed, as in C </entry>
</row>
<row>
<entry> <literal>\n</literal> </entry>
<entry> newline, as in C </entry>
</row>
<row>
<entry> <literal>\r</literal> </entry>
<entry> carriage return, as in C </entry>
</row>
<row>
<entry> <literal>\t</literal> </entry>
<entry> horizontal tab, as in C </entry>
</row>
<row>
<entry> <literal>\u</literal><replaceable>wxyz</replaceable> </entry>
<entry> (where <replaceable>wxyz</replaceable> is exactly four hexadecimal digits)
the character whose hexadecimal value is
<literal>0x</literal><replaceable>wxyz</replaceable>
</entry>
</row>
<row>
<entry> <literal>\U</literal><replaceable>stuvwxyz</replaceable> </entry>
<entry> (where <replaceable>stuvwxyz</replaceable> is exactly eight hexadecimal
digits)
the character whose hexadecimal value is
<literal>0x</literal><replaceable>stuvwxyz</replaceable>
</entry>
</row>
<row>
<entry> <literal>\v</literal> </entry>
<entry> vertical tab, as in C </entry>
</row>
<row>
<entry> <literal>\x</literal><replaceable>hhh</replaceable> </entry>
<entry> (where <replaceable>hhh</replaceable> is any sequence of hexadecimal
digits)
the character whose hexadecimal value is
<literal>0x</literal><replaceable>hhh</replaceable>
(a single character no matter how many hexadecimal digits are used)
</entry>
</row>
<row>
<entry> <literal>\0</literal> </entry>
<entry> the character whose value is <literal>0</literal> (the null byte)</entry>
</row>
<row>
<entry> <literal>\</literal><replaceable>xy</replaceable> </entry>
<entry> (where <replaceable>xy</replaceable> is exactly two octal digits,
and is not a <firstterm>back reference</firstterm>)
the character whose octal value is
<literal>0</literal><replaceable>xy</replaceable> </entry>
</row>
<row>
<entry> <literal>\</literal><replaceable>xyz</replaceable> </entry>
<entry> (where <replaceable>xyz</replaceable> is exactly three octal digits,
and is not a <firstterm>back reference</firstterm>)
the character whose octal value is
<literal>0</literal><replaceable>xyz</replaceable> </entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Hexadecimal digits are <literal>0</literal>-<literal>9</literal>,
<literal>a</literal>-<literal>f</literal>, and <literal>A</literal>-<literal>F</literal>.
Octal digits are <literal>0</literal>-<literal>7</literal>.
</para>
<para>
Numeric character-entry escapes specifying values outside the ASCII range
(0–127) have meanings dependent on the database encoding. When the
encoding is UTF-8, escape values are equivalent to Unicode code points,
for example <literal>\u1234</literal> means the character <literal>U+1234</literal>.
For other multibyte encodings, character-entry escapes usually just
specify the concatenation of the byte values for the character. If the
escape value does not correspond to any legal character in the database
encoding, no error will be raised, but it will never match any data.
</para>
<para>
The character-entry escapes are always taken as ordinary characters.
For example, <literal>\135</literal> is <literal>]</literal> in ASCII, but
<literal>\135</literal> does not terminate a bracket expression.
</para>
<table id="posix-class-shorthand-escapes-table">
<title>Regular Expression Class-Shorthand Escapes</title>
<tgroup cols="2">
<thead>
<row>
<entry>Escape</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>\d</literal> </entry>
<entry> matches any digit, like
<literal>[[:digit:]]</literal> </entry>
</row>
<row>
<entry> <literal>\s</literal> </entry>
<entry> matches any whitespace character, like
<literal>[[:space:]]</literal> </entry>
</row>
<row>
<entry> <literal>\w</literal> </entry>
<entry> matches any word character, like
<literal>[[:word:]]</literal> </entry>
</row>
<row>
<entry> <literal>\D</literal> </entry>
<entry> matches any non-digit, like
<literal>[^[:digit:]]</literal> </entry>
</row>
<row>
<entry> <literal>\S</literal> </entry>
<entry> matches any non-whitespace character, like
<literal>[^[:space:]]</literal> </entry>
</row>
<row>
<entry> <literal>\W</literal> </entry>
<entry> matches any non-word character, like
<literal>[^[:word:]]</literal> </entry>
</row>
</tbody>
</tgroup>
</table>
<para>
The class-shorthand escapes also work within bracket expressions,
although the definitions shown above are not quite syntactically
valid in that context.
For example, <literal>[a-c\d]</literal> is equivalent to
<literal>[a-c[:digit:]]</literal>.
</para>
<table id="posix-constraint-escapes-table">
<title>Regular Expression Constraint Escapes</title>
<tgroup cols="2">
<thead>
<row>
<entry>Escape</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>\A</literal> </entry>
<entry> matches only at the beginning of the string
(see <xref linkend="posix-matching-rules"/> for how this differs from
<literal>^</literal>) </entry>
</row>
<row>
<entry> <literal>\m</literal> </entry>
<entry> matches only at the beginning of a word </entry>
</row>
<row>
<entry> <literal>\M</literal> </entry>
<entry> matches only at the end of a word </entry>
</row>
<row>
<entry> <literal>\y</literal> </entry>
<entry> matches only at the beginning or end of a word </entry>
</row>
<row>
<entry> <literal>\Y</literal> </entry>
<entry> matches only at a point that is not the beginning or end of a
word </entry>
</row>
<row>
<entry> <literal>\Z</literal> </entry>
<entry> matches only at the end of the string
(see <xref linkend="posix-matching-rules"/> for how this differs from
<literal>$</literal>) </entry>
</row>
</tbody>
</tgroup>
</table>
<para>
A word is defined as in the specification of
<literal>[[:<:]]</literal> and <literal>[[:>:]]</literal> above.
Constraint escapes are illegal within bracket expressions.
</para>
<table id="posix-constraint-backref-table">
<title>Regular Expression Back References</title>
<tgroup cols="2">
<thead>
<row>
<entry>Escape</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>\</literal><replaceable>m</replaceable> </entry>
<entry> (where <replaceable>m</replaceable> is a nonzero digit)
a back reference to the <replaceable>m</replaceable>'th subexpression </entry>
</row>
<row>
<entry> <literal>\</literal><replaceable>mnn</replaceable> </entry>
<entry> (where <replaceable>m</replaceable> is a nonzero digit, and
<replaceable>nn</replaceable> is some more digits, and the decimal value
<replaceable>mnn</replaceable> is not greater than the number of closing capturing
parentheses seen so far)
a back reference to the <replaceable>mnn</replaceable>'th subexpression </entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<para>
There is an inherent ambiguity between octal character-entry
escapes and back references, which is resolved by the following heuristics,
as hinted at above.
A leading zero always indicates an octal escape.
A single non-zero digit, not followed by another digit,
is always taken as a back reference.
A multi-digit sequence not starting with a zero is taken as a back
reference if it comes after a suitable subexpression
(i.e., the number is in the legal range for a back reference),
and otherwise is taken as octal.
</para>
</note>
</sect3>
<sect3 id="posix-metasyntax">
<title>Regular Expression Metasyntax</title>
<para>
In addition to the main syntax described above, there are some special
forms and miscellaneous syntactic facilities available.
</para>
<para>
An RE can begin with one of two special <firstterm>director</firstterm> prefixes.
If an RE begins with <literal>***:</literal>,
the rest of the RE is taken as an ARE. (This normally has no effect in
<productname>PostgreSQL</productname>, since REs are assumed to be AREs;
but it does have an effect if ERE or BRE mode had been specified by
the <replaceable>flags</replaceable> parameter to a regex function.)
If an RE begins with <literal>***=</literal>,
the rest of the RE is taken to be a literal string,
with all characters considered ordinary characters.
</para>
<para>
An ARE can begin with <firstterm>embedded options</firstterm>:
a sequence <literal>(?</literal><replaceable>xyz</replaceable><literal>)</literal>
(where <replaceable>xyz</replaceable> is one or more alphabetic characters)
specifies options affecting the rest of the RE.
These options override any previously determined options —
in particular, they can override the case-sensitivity behavior implied by
a regex operator, or the <replaceable>flags</replaceable> parameter to a regex
function.
The available option letters are
shown in <xref linkend="posix-embedded-options-table"/>.
Note that these same option letters are used in the <replaceable>flags</replaceable>
parameters of regex functions.
</para>
<table id="posix-embedded-options-table">
<title>ARE Embedded-Option Letters</title>
<tgroup cols="2">
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>b</literal> </entry>
<entry> rest of RE is a BRE </entry>
</row>
<row>
<entry> <literal>c</literal> </entry>
<entry> case-sensitive matching (overrides operator type) </entry>
</row>
<row>
<entry> <literal>e</literal> </entry>
<entry> rest of RE is an ERE </entry>
</row>
<row>
<entry> <literal>i</literal> </entry>
<entry> case-insensitive matching (see
<xref linkend="posix-matching-rules"/>) (overrides operator type) </entry>
</row>
<row>
<entry> <literal>m</literal> </entry>
<entry> historical synonym for <literal>n</literal> </entry>
</row>
<row>
<entry> <literal>n</literal> </entry>
<entry> newline-sensitive matching (see
<xref linkend="posix-matching-rules"/>) </entry>
</row>
<row>
<entry> <literal>p</literal> </entry>
<entry> partial newline-sensitive matching (see
<xref linkend="posix-matching-rules"/>) </entry>
</row>
<row>
<entry> <literal>q</literal> </entry>
<entry> rest of RE is a literal (<quote>quoted</quote>) string, all ordinary
characters </entry>
</row>
<row>
<entry> <literal>s</literal> </entry>
<entry> non-newline-sensitive matching (default) </entry>
</row>
<row>
<entry> <literal>t</literal> </entry>
<entry> tight syntax (default; see below) </entry>
</row>
<row>
<entry> <literal>w</literal> </entry>
<entry> inverse partial newline-sensitive (<quote>weird</quote>) matching
(see <xref linkend="posix-matching-rules"/>) </entry>
</row>
<row>
<entry> <literal>x</literal> </entry>
<entry> expanded syntax (see below) </entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Embedded options take effect at the <literal>)</literal> terminating the sequence.
They can appear only at the start of an ARE (after the
<literal>***:</literal> director if any).
</para>
<para>
In addition to the usual (<firstterm>tight</firstterm>) RE syntax, in which all
characters are significant, there is an <firstterm>expanded</firstterm> syntax,
available by specifying the embedded <literal>x</literal> option.
In the expanded syntax,
white-space characters in the RE are ignored, as are
all characters between a <literal>#</literal>
and the following newline (or the end of the RE). This
permits paragraphing and commenting a complex RE.
There are three exceptions to that basic rule:
<itemizedlist>
<listitem>
<para>
a white-space character or <literal>#</literal> preceded by <literal>\</literal> is
retained
</para>
</listitem>
<listitem>
<para>
white space or <literal>#</literal> within a bracket expression is retained
</para>
</listitem>
<listitem>
<para>
white space and comments cannot appear within multi-character symbols,
such as <literal>(?:</literal>
</para>
</listitem>
</itemizedlist>
For this purpose, white-space characters are blank, tab, newline, and
any character that belongs to the <replaceable>space</replaceable> character class.
</para>
<para>
Finally, in an ARE, outside bracket expressions, the sequence
<literal>(?#</literal><replaceable>ttt</replaceable><literal>)</literal>
(where <replaceable>ttt</replaceable> is any text not containing a <literal>)</literal>)
is a comment, completely ignored.
Again, this is not allowed between the characters of
multi-character symbols, like <literal>(?:</literal>.
Such comments are more a historical artifact than a useful facility,
and their use is deprecated; use the expanded syntax instead.
</para>
<para>
<emphasis>None</emphasis> of these metasyntax extensions is available if
an initial <literal>***=</literal> director
has specified that the user's input be treated as a literal string
rather than as an RE.
</para>
</sect3>
<sect3 id="posix-matching-rules">
<title>Regular Expression Matching Rules</title>
<para>
In the event that an RE could match more than one substring of a given
string, the RE matches the one starting earliest in the string.
If the RE could match more than one substring starting at that point,
either the longest possible match or the shortest possible match will
be taken, depending on whether the RE is <firstterm>greedy</firstterm> or
<firstterm>non-greedy</firstterm>.
</para>
<para>
Whether an RE is greedy or not is determined by the following rules:
<itemizedlist>
<listitem>
<para>
Most atoms, and all constraints, have no greediness attribute (because
they cannot match variable amounts of text anyway).
</para>
</listitem>
<listitem>
<para>
Adding parentheses around an RE does not change its greediness.
</para>
</listitem>
<listitem>
<para>
A quantified atom with a fixed-repetition quantifier
(<literal>{</literal><replaceable>m</replaceable><literal>}</literal>
or
<literal>{</literal><replaceable>m</replaceable><literal>}?</literal>)
has the same greediness (possibly none) as the atom itself.
</para>
</listitem>
<listitem>
<para>
A quantified atom with other normal quantifiers (including
<literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable><literal>}</literal>
with <replaceable>m</replaceable> equal to <replaceable>n</replaceable>)
is greedy (prefers longest match).
</para>
</listitem>
<listitem>
<para>
A quantified atom with a non-greedy quantifier (including
<literal>{</literal><replaceable>m</replaceable><literal>,</literal><replaceable>n</replaceable><literal>}?</literal>
with <replaceable>m</replaceable> equal to <replaceable>n</replaceable>)
is non-greedy (prefers shortest match).
</para>
</listitem>
<listitem>
<para>
A branch — that is, an RE that has no top-level
<literal>|</literal> operator — has the same greediness as the first
quantified atom in it that has a greediness attribute.
</para>
</listitem>
<listitem>
<para>
An RE consisting of two or more branches connected by the
<literal>|</literal> operator is always greedy.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The above rules associate greediness attributes not only with individual
quantified atoms, but with branches and entire REs that contain quantified
atoms. What that means is that the matching is done in such a way that
the branch, or whole RE, matches the longest or shortest possible
substring <emphasis>as a whole</emphasis>. Once the length of the entire match
is determined, the part of it that matches any particular subexpression
is determined on the basis of the greediness attribute of that
subexpression, with subexpressions starting earlier in the RE taking
priority over ones starting later.
</para>
<para>
An example of what this means:
<screen>
SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');
<lineannotation>Result: </lineannotation><computeroutput>123</computeroutput>
SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<lineannotation>Result: </lineannotation><computeroutput>1</computeroutput>
</screen>
In the first case, the RE as a whole is greedy because <literal>Y*</literal>
is greedy. It can match beginning at the <literal>Y</literal>, and it matches
the longest possible string starting there, i.e., <literal>Y123</literal>.
The output is the parenthesized part of that, or <literal>123</literal>.
In the second case, the RE as a whole is non-greedy because <literal>Y*?</literal>
is non-greedy. It can match beginning at the <literal>Y</literal>, and it matches
the shortest possible string starting there, i.e., <literal>Y1</literal>.
The subexpression <literal>[0-9]{1,3}</literal> is greedy but it cannot change
the decision as to the overall match length; so it is forced to match
just <literal>1</literal>.
</para>
<para>
In short, when an RE contains both greedy and non-greedy subexpressions,
the total match length is either as long as possible or as short as
possible, according to the attribute assigned to the whole RE. The
attributes assigned to the subexpressions only affect how much of that
match they are allowed to <quote>eat</quote> relative to each other.
</para>
<para>
The quantifiers <literal>{1,1}</literal> and <literal>{1,1}?</literal>
can be used to force greediness or non-greediness, respectively,
on a subexpression or a whole RE.
This is useful when you need the whole RE to have a greediness attribute
different from what's deduced from its elements. As an example,
suppose that we are trying to separate a string containing some digits
into the digits and the parts before and after them. We might try to
do that like this:
<screen>
SELECT regexp_match('abc01234xyz', '(.*)(\d+)(.*)');
<lineannotation>Result: </lineannotation><computeroutput>{abc0123,4,xyz}</computeroutput>
</screen>
That didn't work: the first <literal>.*</literal> is greedy so
it <quote>eats</quote> as much as it can, leaving the <literal>\d+</literal> to
match at the last possible place, the last digit. We might try to fix
that by making it non-greedy:
<screen>
SELECT regexp_match('abc01234xyz', '(.*?)(\d+)(.*)');
<lineannotation>Result: </lineannotation><computeroutput>{abc,0,""}</computeroutput>
</screen>
That didn't work either, because now the RE as a whole is non-greedy
and so it ends the overall match as soon as possible. We can get what
we want by forcing the RE as a whole to be greedy:
<screen>
SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
<lineannotation>Result: </lineannotation><computeroutput>{abc,01234,xyz}</computeroutput>
</screen>
Controlling the RE's overall greediness separately from its components'
greediness allows great flexibility in handling variable-length patterns.
</para>
<para>
When deciding what is a longer or shorter match,
match lengths are measured in characters, not collating elements.
An empty string is considered longer than no match at all.
For example:
<literal>bb*</literal>
matches the three middle characters of <literal>abbbc</literal>;
<literal>(week|wee)(night|knights)</literal>
matches all ten characters of <literal>weeknights</literal>;
when <literal>(.*).*</literal>
is matched against <literal>abc</literal> the parenthesized subexpression
matches all three characters; and when
<literal>(a*)*</literal> is matched against <literal>bc</literal>
both the whole RE and the parenthesized
subexpression match an empty string.
</para>
<para>
If case-independent matching is specified,
the effect is much as if all case distinctions had vanished from the
alphabet.
When an alphabetic that exists in multiple cases appears as an
ordinary character outside a bracket expression, it is effectively
transformed into a bracket expression containing both cases,
e.g., <literal>x</literal> becomes <literal>[xX]</literal>.
When it appears inside a bracket expression, all case counterparts
of it are added to the bracket expression, e.g.,
<literal>[x]</literal> becomes <literal>[xX]</literal>
and <literal>[^x]</literal> becomes <literal>[^xX]</literal>.
</para>
<para>
If newline-sensitive matching is specified, <literal>.</literal>
and bracket expressions using <literal>^</literal>
will never match the newline character
(so that matches will not cross lines unless the RE
explicitly includes a newline)
and <literal>^</literal> and <literal>$</literal>
will match the empty string after and before a newline
respectively, in addition to matching at beginning and end of string
respectively.
But the ARE escapes <literal>\A</literal> and <literal>\Z</literal>
continue to match beginning or end of string <emphasis>only</emphasis>.
Also, the character class shorthands <literal>\D</literal>
and <literal>\W</literal> will match a newline regardless of this mode.
(Before <productname>PostgreSQL</productname> 14, they did not match
newlines when in newline-sensitive mode.
Write <literal>[^[:digit:]]</literal>
or <literal>[^[:word:]]</literal> to get the old behavior.)
</para>
<para>
If partial newline-sensitive matching is specified,
this affects <literal>.</literal> and bracket expressions
as with newline-sensitive matching, but not <literal>^</literal>
and <literal>$</literal>.
</para>
<para>
If inverse partial newline-sensitive matching is specified,
this affects <literal>^</literal> and <literal>$</literal>
as with newline-sensitive matching, but not <literal>.</literal>
and bracket expressions.
This isn't very useful but is provided for symmetry.
</para>
</sect3>
<sect3 id="posix-limits-compatibility">
<title>Limits and Compatibility</title>
<para>
No particular limit is imposed on the length of REs in this
implementation. However,
programs intended to be highly portable should not employ REs longer
than 256 bytes,
as a POSIX-compliant implementation can refuse to accept such REs.
</para>
<para>
The only feature of AREs that is actually incompatible with
POSIX EREs is that <literal>\</literal> does not lose its special
significance inside bracket expressions.
All other ARE features use syntax which is illegal or has
undefined or unspecified effects in POSIX EREs;
the <literal>***</literal> syntax of directors likewise is outside the POSIX
syntax for both BREs and EREs.
</para>
<para>
Many of the ARE extensions are borrowed from Perl, but some have
been changed to clean them up, and a few Perl extensions are not present.
Incompatibilities of note include <literal>\b</literal>, <literal>\B</literal>,
the lack of special treatment for a trailing newline,
the addition of complemented bracket expressions to the things
affected by newline-sensitive matching,
the restrictions on parentheses and back references in lookahead/lookbehind
constraints, and the longest/shortest-match (rather than first-match)
matching semantics.
</para>
</sect3>
<sect3 id="posix-basic-regexes">
<title>Basic Regular Expressions</title>
<para>
BREs differ from EREs in several respects.
In BREs, <literal>|</literal>, <literal>+</literal>, and <literal>?</literal>
are ordinary characters and there is no equivalent
for their functionality.
The delimiters for bounds are
<literal>\{</literal> and <literal>\}</literal>,
with <literal>{</literal> and <literal>}</literal>
by themselves ordinary characters.
The parentheses for nested subexpressions are
<literal>\(</literal> and <literal>\)</literal>,
with <literal>(</literal> and <literal>)</literal> by themselves ordinary characters.
<literal>^</literal> is an ordinary character except at the beginning of the
RE or the beginning of a parenthesized subexpression,
<literal>$</literal> is an ordinary character except at the end of the
RE or the end of a parenthesized subexpression,
and <literal>*</literal> is an ordinary character if it appears at the beginning
of the RE or the beginning of a parenthesized subexpression
(after a possible leading <literal>^</literal>).
Finally, single-digit back references are available, and
<literal>\<</literal> and <literal>\></literal>
are synonyms for
<literal>[[:<:]]</literal> and <literal>[[:>:]]</literal>
respectively; no other escapes are available in BREs.
</para>
</sect3>
<!-- end re_syntax.n man page -->
<sect3 id="posix-vs-xquery">
<title>Differences from SQL Standard and XQuery</title>
<indexterm zone="posix-vs-xquery">
<primary>LIKE_REGEX</primary>
</indexterm>
<indexterm zone="posix-vs-xquery">
<primary>OCCURRENCES_REGEX</primary>
</indexterm>
<indexterm zone="posix-vs-xquery">
<primary>POSITION_REGEX</primary>
</indexterm>
<indexterm zone="posix-vs-xquery">
<primary>SUBSTRING_REGEX</primary>
</indexterm>
<indexterm zone="posix-vs-xquery">
<primary>TRANSLATE_REGEX</primary>
</indexterm>
<indexterm zone="posix-vs-xquery">
<primary>XQuery regular expressions</primary>
</indexterm>
<para>
Since SQL:2008, the SQL standard includes regular expression operators
and functions that performs pattern
matching according to the XQuery regular expression
standard:
<itemizedlist>
<listitem><para><literal>LIKE_REGEX</literal></para></listitem>
<listitem><para><literal>OCCURRENCES_REGEX</literal></para></listitem>
<listitem><para><literal>POSITION_REGEX</literal></para></listitem>
<listitem><para><literal>SUBSTRING_REGEX</literal></para></listitem>
<listitem><para><literal>TRANSLATE_REGEX</literal></para></listitem>
</itemizedlist>
<productname>PostgreSQL</productname> does not currently implement these
operators and functions. You can get approximately equivalent
functionality in each case as shown in <xref
linkend="functions-regexp-sql-table"/>. (Various optional clauses on
both sides have been omitted in this table.)
</para>
<table id="functions-regexp-sql-table">
<title>Regular Expression Functions Equivalencies</title>
<tgroup cols="2">
<thead>
<row>
<entry>SQL standard</entry>
<entry><productname>PostgreSQL</productname></entry>
</row>
</thead>
<tbody>
<row>
<entry><literal><replaceable>string</replaceable> LIKE_REGEX <replaceable>pattern</replaceable></literal></entry>
<entry><literal>regexp_like(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>)</literal> or <literal><replaceable>string</replaceable> ~ <replaceable>pattern</replaceable></literal></entry>
</row>
<row>
<entry><literal>OCCURRENCES_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</replaceable>)</literal></entry>
<entry><literal>regexp_count(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>)</literal></entry>
</row>
<row>
<entry><literal>POSITION_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</replaceable>)</literal></entry>
<entry><literal>regexp_instr(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>)</literal></entry>
</row>
<row>
<entry><literal>SUBSTRING_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</replaceable>)</literal></entry>
<entry><literal>regexp_substr(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>)</literal></entry>
</row>
<row>
<entry><literal>TRANSLATE_REGEX(<replaceable>pattern</replaceable> IN <replaceable>string</replaceable> WITH <replaceable>replacement</replaceable>)</literal></entry>
<entry><literal>regexp_replace(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>, <replaceable>replacement</replaceable>)</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Regular expression functions similar to those provided by PostgreSQL are
also available in a number of other SQL implementations, whereas the
SQL-standard functions are not as widely implemented. Some of the
details of the regular expression syntax will likely differ in each
implementation.
</para>
<para>
The SQL-standard operators and functions use XQuery regular expressions,
which are quite close to the ARE syntax described above.
Notable differences between the existing POSIX-based
regular-expression feature and XQuery regular expressions include:
<itemizedlist>
<listitem>
<para>
XQuery character class subtraction is not supported. An example of
this feature is using the following to match only English
consonants: <literal>[a-z-[aeiou]]</literal>.
</para>
</listitem>
<listitem>
<para>
XQuery character class shorthands <literal>\c</literal>,
<literal>\C</literal>, <literal>\i</literal>,
and <literal>\I</literal> are not supported.
</para>
</listitem>
<listitem>
<para>
XQuery character class elements
using <literal>\p{UnicodeProperty}</literal> or the
inverse <literal>\P{UnicodeProperty}</literal> are not supported.
</para>
</listitem>
<listitem>
<para>
POSIX interprets character classes such as <literal>\w</literal>
(see <xref linkend="posix-class-shorthand-escapes-table"/>)
according to the prevailing locale (which you can control by
attaching a <literal>COLLATE</literal> clause to the operator or
function). XQuery specifies these classes by reference to Unicode
character properties, so equivalent behavior is obtained only with
a locale that follows the Unicode rules.
</para>
</listitem>
<listitem>
<para>
The SQL standard (not XQuery itself) attempts to cater for more
variants of <quote>newline</quote> than POSIX does. The
newline-sensitive matching options described above consider only
ASCII NL (<literal>\n</literal>) to be a newline, but SQL would have
us treat CR (<literal>\r</literal>), CRLF (<literal>\r\n</literal>)
(a Windows-style newline), and some Unicode-only characters like
LINE SEPARATOR (U+2028) as newlines as well.
Notably, <literal>.</literal> and <literal>\s</literal> should
count <literal>\r\n</literal> as one character not two according to
SQL.
</para>
</listitem>
<listitem>
<para>
Of the character-entry escapes described in
<xref linkend="posix-character-entry-escapes-table"/>,
XQuery supports only <literal>\n</literal>, <literal>\r</literal>,
and <literal>\t</literal>.
</para>
</listitem>
<listitem>
<para>
XQuery does not support
the <literal>[:<replaceable>name</replaceable>:]</literal> syntax
for character classes within bracket expressions.
</para>
</listitem>
<listitem>
<para>
XQuery does not have lookahead or lookbehind constraints,
nor any of the constraint escapes described in
<xref linkend="posix-constraint-escapes-table"/>.
</para>
</listitem>
<listitem>
<para>
The metasyntax forms described in <xref linkend="posix-metasyntax"/>
do not exist in XQuery.
</para>
</listitem>
<listitem>
<para>
The regular expression flag letters defined by XQuery are
related to but not the same as the option letters for POSIX
(<xref linkend="posix-embedded-options-table"/>). While the
<literal>i</literal> and <literal>q</literal> options behave the
same, others do not:
<itemizedlist>
<listitem>
<para>
XQuery's <literal>s</literal> (allow dot to match newline)
and <literal>m</literal> (allow <literal>^</literal>
and <literal>$</literal> to match at newlines) flags provide
access to the same behaviors as
POSIX's <literal>n</literal>, <literal>p</literal>
and <literal>w</literal> flags, but they
do <emphasis>not</emphasis> match the behavior of
POSIX's <literal>s</literal> and <literal>m</literal> flags.
Note in particular that dot-matches-newline is the default
behavior in POSIX but not XQuery.
</para>
</listitem>
<listitem>
<para>
XQuery's <literal>x</literal> (ignore whitespace in pattern) flag
is noticeably different from POSIX's expanded-mode flag.
POSIX's <literal>x</literal> flag also
allows <literal>#</literal> to begin a comment in the pattern,
and POSIX will not ignore a whitespace character after a
backslash.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="functions-formatting">
<title>Data Type Formatting Functions</title>
<indexterm>
<primary>formatting</primary>
</indexterm>
<para>
The <productname>PostgreSQL</productname> formatting functions
provide a powerful set of tools for converting various data types
(date/time, integer, floating point, numeric) to formatted strings
and for converting from formatted strings to specific data types.
<xref linkend="functions-formatting-table"/> lists them.
These functions all follow a common calling convention: the first
argument is the value to be formatted and the second argument is a
template that defines the output or input format.
</para>
<table id="functions-formatting-table">
<title>Formatting Functions</title>
<tgroup cols="1">
<thead>
<row>
<entry role="func_table_entry"><para role="func_signature">
Function
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>to_char</primary>
</indexterm>
<function>to_char</function> ( <type>timestamp</type>, <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para role="func_signature">
<function>to_char</function> ( <type>timestamp with time zone</type>, <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts time stamp to string according to the given format.
</para>
<para>
<literal>to_char(timestamp '2002-04-20 17:31:12.66', 'HH12:MI:SS')</literal>
<returnvalue>05:31:12</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>to_char</function> ( <type>interval</type>, <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts interval to string according to the given format.
</para>
<para>
<literal>to_char(interval '15h 2m 12s', 'HH24:MI:SS')</literal>
<returnvalue>15:02:12</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>to_char</function> ( <replaceable>numeric_type</replaceable>, <type>text</type> )
<returnvalue>text</returnvalue>
</para>
<para>
Converts number to string according to the given format; available
for <type>integer</type>, <type>bigint</type>, <type>numeric</type>,
<type>real</type>, <type>double precision</type>.
</para>
<para>
<literal>to_char(125, '999')</literal>
<returnvalue>125</returnvalue>
</para>
<para>
<literal>to_char(125.8::real, '999D9')</literal>
<returnvalue>125.8</returnvalue>
</para>
<para>
<literal>to_char(-125.8, '999D99S')</literal>
<returnvalue>125.80-</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>to_date</primary>
</indexterm>
<function>to_date</function> ( <type>text</type>, <type>text</type> )
<returnvalue>date</returnvalue>
</para>
<para>
Converts string to date according to the given format.
</para>
<para>
<literal>to_date('05 Dec 2000', 'DD Mon YYYY')</literal>
<returnvalue>2000-12-05</re
|