+++ /dev/null
-<!-- 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. When using the <literal>libc</literal> locale
- provider, words are sequences of alphanumeric characters separated
- by non-alphanumeric characters; when using the ICU locale provider,
- words are separated according to
- <ulink url="https://www.unicode.org/reports/tr29/#Word_Boundaries">Unicode Standard Annex #29</ulink>.
- </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</returnvalue>
- </para></entry>
- </row>
-
- <row>
- <entry role="func_table_entry"><para role="func_signature">
- <indexterm>
- <primary>to_number</primary>
- </indexterm>
- <function>to_number</function> ( <type>text</type>, <type>text</type> )
- <returnvalue>numeric</returnvalue>
- </para>
- <para>
- Converts string to numeric according to the given format.
- </para>
- <para>
- <literal>to_number('12,454.8-', '99G999D9S')</literal>
- <returnvalue>-12454.8</returnvalue>
- </para></entry>
- </row>
-
- <row>
- <entry role="func_table_entry"><para role="func_signature">
- <indexterm>
- <primary>to_timestamp</primary>
- </indexterm>
- <function>to_timestamp</function> ( <type>text</type>, <type>text</type> )
- <returnvalue>timestamp with time zone</returnvalue>
- </para>
- <para>
- Converts string to time stamp according to the given format.
- (See also <function>to_timestamp(double precision)</function> in
- <xref linkend="functions-datetime-table"/>.)
- </para>
- <para>
- <literal>to_timestamp('05 Dec 2000', 'DD Mon YYYY')</literal>
- <returnvalue>2000-12-05 00:00:00-05</returnvalue>
- </para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <tip>
- <para>
- <function>to_timestamp</function> and <function>to_date</function>
- exist to handle input formats that cannot be converted by
- simple casting. For most standard date/time formats, simply casting the
- source string to the required data type works, and is much easier.
- Similarly, <function>to_number</function> is unnecessary for standard numeric
- representations.
- </para>
- </tip>
-
- <para>
- In a <function>to_char</function> output template string, there are certain
- patterns that are recognized and replaced with appropriately-formatted
- data based on the given value. Any text that is not a template pattern is
- simply copied verbatim. Similarly, in an input template string (for the
- other functions), template patterns identify the values to be supplied by
- the input data string. If there are characters in the template string
- that are not template patterns, the corresponding characters in the input
- data string are simply skipped over (whether or not they are equal to the
- template string characters).
- </para>
-
- <para>
- <xref linkend="functions-formatting-datetime-table"/> shows&nb
projects / users / rhaas / postgres.git / commitdiff