| Current File : //usr/share/doc/postgresql-9.2.24/html/functions-matching.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Pattern Matching</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.2.24 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Functions and Operators"
HREF="functions.html"><LINK
REL="PREVIOUS"
TITLE="Bit String Functions and Operators"
HREF="functions-bitstring.html"><LINK
REL="NEXT"
TITLE="Data Type Formatting Functions"
HREF="functions-formatting.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2017-11-06T22:43:11"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.2.24 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Bit String Functions and Operators"
HREF="functions-bitstring.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="functions.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 9. Functions and Operators</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Data Type Formatting Functions"
HREF="functions-formatting.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="FUNCTIONS-MATCHING"
>9.7. Pattern Matching</A
></H1
><P
> There are three separate approaches to pattern matching provided
by <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>: the traditional
<ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> <CODE
CLASS="FUNCTION"
>LIKE</CODE
> operator, the
more recent <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> operator (added in
SQL:1999), and <ACRONYM
CLASS="ACRONYM"
>POSIX</ACRONYM
>-style regular
expressions. Aside from the basic <SPAN
CLASS="QUOTE"
>"does this string match
this pattern?"</SPAN
> operators, functions are available to extract
or replace matching substrings and to split a string at matching
locations.
</P
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
> If you have pattern matching needs that go beyond this,
consider writing a user-defined function in Perl or Tcl.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="CAUTION"
><P
></P
><TABLE
CLASS="CAUTION"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Caution</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
> 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.
</P
><P
> Searches using <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> patterns have the same
security hazards, since <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> provides many
of the same capabilities as <ACRONYM
CLASS="ACRONYM"
>POSIX</ACRONYM
>-style regular
expressions.
</P
><P
> <CODE
CLASS="FUNCTION"
>LIKE</CODE
> searches, being much simpler than the other
two options, are safer to use with possibly-hostile pattern sources.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="FUNCTIONS-LIKE"
>9.7.1. <CODE
CLASS="FUNCTION"
>LIKE</CODE
></A
></H2
><PRE
CLASS="SYNOPSIS"
><TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> LIKE <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> [<SPAN
CLASS="OPTIONAL"
>ESCAPE <TT
CLASS="REPLACEABLE"
><I
>escape-character</I
></TT
></SPAN
>]
<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> NOT LIKE <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> [<SPAN
CLASS="OPTIONAL"
>ESCAPE <TT
CLASS="REPLACEABLE"
><I
>escape-character</I
></TT
></SPAN
>]</PRE
><P
> The <CODE
CLASS="FUNCTION"
>LIKE</CODE
> expression returns true if the
<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> matches the supplied
<TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>. (As
expected, the <CODE
CLASS="FUNCTION"
>NOT LIKE</CODE
> expression returns
false if <CODE
CLASS="FUNCTION"
>LIKE</CODE
> returns true, and vice versa.
An equivalent expression is
<TT
CLASS="LITERAL"
>NOT (<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> LIKE
<TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>)</TT
>.)
</P
><P
> If <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> does not contain percent
signs or underscores, then the pattern only represents the string
itself; in that case <CODE
CLASS="FUNCTION"
>LIKE</CODE
> acts like the
equals operator. An underscore (<TT
CLASS="LITERAL"
>_</TT
>) in
<TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> stands for (matches) any single
character; a percent sign (<TT
CLASS="LITERAL"
>%</TT
>) matches any sequence
of zero or more characters.
</P
><P
> Some examples:
</P><PRE
CLASS="PROGRAMLISTING"
>'abc' LIKE 'abc' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' LIKE 'a%' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' LIKE '_b_' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' LIKE 'c' <I
CLASS="LINEANNOTATION"
>false</I
></PRE
><P>
</P
><P
> <CODE
CLASS="FUNCTION"
>LIKE</CODE
> 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.
</P
><P
> To match a literal underscore or percent sign without matching
other characters, the respective character in
<TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> must be
preceded by the escape character. The default escape
character is the backslash but a different one can be selected by
using the <TT
CLASS="LITERAL"
>ESCAPE</TT
> clause. To match the escape
character itself, write two escape characters.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> If you have <A
HREF="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS"
>standard_conforming_strings</A
> turned off,
any backslashes you write in literal string constants will need to be
doubled. See <A
HREF="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS"
>Section 4.1.2.1</A
> for more information.
</P
></BLOCKQUOTE
></DIV
><P
> It's also possible to select no escape character by writing
<TT
CLASS="LITERAL"
>ESCAPE ''</TT
>. This effectively disables the
escape mechanism, which makes it impossible to turn off the
special meaning of underscore and percent signs in the pattern.
</P
><P
> The key word <TT
CLASS="TOKEN"
>ILIKE</TT
> can be used instead of
<TT
CLASS="TOKEN"
>LIKE</TT
> to make the match case-insensitive according
to the active locale. This is not in the <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> standard but is a
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> extension.
</P
><P
> The operator <TT
CLASS="LITERAL"
>~~</TT
> is equivalent to
<CODE
CLASS="FUNCTION"
>LIKE</CODE
>, and <TT
CLASS="LITERAL"
>~~*</TT
> corresponds to
<CODE
CLASS="FUNCTION"
>ILIKE</CODE
>. There are also
<TT
CLASS="LITERAL"
>!~~</TT
> and <TT
CLASS="LITERAL"
>!~~*</TT
> operators that
represent <CODE
CLASS="FUNCTION"
>NOT LIKE</CODE
> and <CODE
CLASS="FUNCTION"
>NOT
ILIKE</CODE
>, respectively. All of these operators are
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>-specific.
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="FUNCTIONS-SIMILARTO-REGEXP"
>9.7.2. <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> Regular Expressions</A
></H2
><PRE
CLASS="SYNOPSIS"
><TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> SIMILAR TO <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> [<SPAN
CLASS="OPTIONAL"
>ESCAPE <TT
CLASS="REPLACEABLE"
><I
>escape-character</I
></TT
></SPAN
>]
<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> NOT SIMILAR TO <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> [<SPAN
CLASS="OPTIONAL"
>ESCAPE <TT
CLASS="REPLACEABLE"
><I
>escape-character</I
></TT
></SPAN
>]</PRE
><P
> The <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> operator returns true or
false depending on whether its pattern matches the given string.
It is similar to <CODE
CLASS="FUNCTION"
>LIKE</CODE
>, except that it
interprets the pattern using the SQL standard's definition of a
regular expression. SQL regular expressions are a curious cross
between <CODE
CLASS="FUNCTION"
>LIKE</CODE
> notation and common regular
expression notation.
</P
><P
> Like <CODE
CLASS="FUNCTION"
>LIKE</CODE
>, the <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
>
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
<CODE
CLASS="FUNCTION"
>LIKE</CODE
>, <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> uses
<TT
CLASS="LITERAL"
>_</TT
> and <TT
CLASS="LITERAL"
>%</TT
> as wildcard characters denoting
any single character and any string, respectively (these are
comparable to <TT
CLASS="LITERAL"
>.</TT
> and <TT
CLASS="LITERAL"
>.*</TT
> in POSIX regular
expressions).
</P
><P
> In addition to these facilities borrowed from <CODE
CLASS="FUNCTION"
>LIKE</CODE
>,
<CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> supports these pattern-matching
metacharacters borrowed from POSIX regular expressions:
<P
></P
></P><UL
><LI
><P
> <TT
CLASS="LITERAL"
>|</TT
> denotes alternation (either of two alternatives).
</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>*</TT
> denotes repetition of the previous item zero
or more times.
</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>+</TT
> denotes repetition of the previous item one
or more times.
</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>?</TT
> denotes repetition of the previous item zero
or one time.
</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>}</TT
> denotes repetition
of the previous item exactly <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> times.
</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,}</TT
> denotes repetition
of the previous item <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> or more times.
</P
></LI
><LI
><P
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
><TT
CLASS="LITERAL"
>}</TT
>
denotes repetition of the previous item at least <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> and
not more than <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
> times.
</P
></LI
><LI
><P
> Parentheses <TT
CLASS="LITERAL"
>()</TT
> can be used to group items into
a single logical item.
</P
></LI
><LI
><P
> A bracket expression <TT
CLASS="LITERAL"
>[...]</TT
> specifies a character
class, just as in POSIX regular expressions.
</P
></LI
></UL
><P>
Notice that the period (<TT
CLASS="LITERAL"
>.</TT
>) is not a metacharacter
for <CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
>.
</P
><P
> As with <CODE
CLASS="FUNCTION"
>LIKE</CODE
>, a backslash disables the special meaning
of any of these metacharacters; or a different escape character can
be specified with <TT
CLASS="LITERAL"
>ESCAPE</TT
>.
</P
><P
> Some examples:
</P><PRE
CLASS="PROGRAMLISTING"
>'abc' SIMILAR TO 'abc' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' SIMILAR TO 'a' <I
CLASS="LINEANNOTATION"
>false</I
>
'abc' SIMILAR TO '%(b|d)%' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' SIMILAR TO '(b|c)%' <I
CLASS="LINEANNOTATION"
>false</I
></PRE
><P>
</P
><P
> The <CODE
CLASS="FUNCTION"
>substring</CODE
> function with three parameters,
<CODE
CLASS="FUNCTION"
>substring(<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> from
<TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
> for
<TT
CLASS="REPLACEABLE"
><I
>escape-character</I
></TT
>)</CODE
>, provides
extraction of a substring that matches an SQL
regular expression pattern. As with <TT
CLASS="LITERAL"
>SIMILAR TO</TT
>, the
specified pattern must match the entire data string, or else the
function fails and returns null. To indicate the part of the
pattern that should be returned on success, the pattern must contain
two occurrences of the escape character followed by a double quote
(<TT
CLASS="LITERAL"
>"</TT
>).
The text matching the portion of the pattern
between these markers is returned.
</P
><P
> Some examples, with <TT
CLASS="LITERAL"
>#"</TT
> delimiting the return string:
</P><PRE
CLASS="PROGRAMLISTING"
>substring('foobar' from '%#"o_b#"%' for '#') <I
CLASS="LINEANNOTATION"
>oob</I
>
substring('foobar' from '#"o_b#"%' for '#') <I
CLASS="LINEANNOTATION"
>NULL</I
></PRE
><P>
</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="FUNCTIONS-POSIX-REGEXP"
>9.7.3. <ACRONYM
CLASS="ACRONYM"
>POSIX</ACRONYM
> Regular Expressions</A
></H2
><P
> <A
HREF="functions-matching.html#FUNCTIONS-POSIX-TABLE"
>Table 9-12</A
> lists the available
operators for pattern matching using POSIX regular expressions.
</P
><DIV
CLASS="TABLE"
><A
NAME="FUNCTIONS-POSIX-TABLE"
></A
><P
><B
>Table 9-12. Regular Expression Match Operators</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>Operator</TH
><TH
>Description</TH
><TH
>Example</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>~</TT
> </TD
><TD
>Matches regular expression, case sensitive</TD
><TD
><TT
CLASS="LITERAL"
>'thomas' ~ '.*thomas.*'</TT
></TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>~*</TT
> </TD
><TD
>Matches regular expression, case insensitive</TD
><TD
><TT
CLASS="LITERAL"
>'thomas' ~* '.*Thomas.*'</TT
></TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>!~</TT
> </TD
><TD
>Does not match regular expression, case sensitive</TD
><TD
><TT
CLASS="LITERAL"
>'thomas' !~ '.*Thomas.*'</TT
></TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>!~*</TT
> </TD
><TD
>Does not match regular expression, case insensitive</TD
><TD
><TT
CLASS="LITERAL"
>'thomas' !~* '.*vadim.*'</TT
></TD
></TR
></TBODY
></TABLE
></DIV
><P
> <ACRONYM
CLASS="ACRONYM"
>POSIX</ACRONYM
> regular expressions provide a more
powerful means for pattern matching than the <CODE
CLASS="FUNCTION"
>LIKE</CODE
> and
<CODE
CLASS="FUNCTION"
>SIMILAR TO</CODE
> operators.
Many Unix tools such as <TT
CLASS="COMMAND"
>egrep</TT
>,
<TT
CLASS="COMMAND"
>sed</TT
>, or <TT
CLASS="COMMAND"
>awk</TT
> use a pattern
matching language that is similar to the one described here.
</P
><P
> A regular expression is a character sequence that is an
abbreviated definition of a set of strings (a <I
CLASS="FIRSTTERM"
>regular
set</I
>). 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 <CODE
CLASS="FUNCTION"
>LIKE</CODE
>, pattern characters
match string characters exactly unless they are special characters
in the regular expression language — but regular expressions use
different special characters than <CODE
CLASS="FUNCTION"
>LIKE</CODE
> does.
Unlike <CODE
CLASS="FUNCTION"
>LIKE</CODE
> 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.
</P
><P
> Some examples:
</P><PRE
CLASS="PROGRAMLISTING"
>'abc' ~ 'abc' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' ~ '^a' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' ~ '(b|d)' <I
CLASS="LINEANNOTATION"
>true</I
>
'abc' ~ '^(b|c)' <I
CLASS="LINEANNOTATION"
>false</I
></PRE
><P>
</P
><P
> The <ACRONYM
CLASS="ACRONYM"
>POSIX</ACRONYM
> pattern language is described in much
greater detail below.
</P
><P
> The <CODE
CLASS="FUNCTION"
>substring</CODE
> function with two parameters,
<CODE
CLASS="FUNCTION"
>substring(<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
> from
<TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>)</CODE
>, provides extraction of a
substring
that matches a POSIX regular expression pattern. It returns null if
there is no match, otherwise the 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.
</P
><P
> Some examples:
</P><PRE
CLASS="PROGRAMLISTING"
>substring('foobar' from 'o.b') <I
CLASS="LINEANNOTATION"
>oob</I
>
substring('foobar' from 'o(.)b') <I
CLASS="LINEANNOTATION"
>o</I
></PRE
><P>
</P
><P
> The <CODE
CLASS="FUNCTION"
>regexp_replace</CODE
> function provides substitution of
new text for substrings that match POSIX regular expression patterns.
It has the syntax
<CODE
CLASS="FUNCTION"
>regexp_replace</CODE
>(<TT
CLASS="REPLACEABLE"
><I
>source</I
></TT
>,
<TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>, <TT
CLASS="REPLACEABLE"
><I
>replacement</I
></TT
>
[<SPAN
CLASS="OPTIONAL"
>, <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> </SPAN
>]).
The <TT
CLASS="REPLACEABLE"
><I
>source</I
></TT
> string is returned unchanged if
there is no match to the <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>. If there is a
match, the <TT
CLASS="REPLACEABLE"
><I
>source</I
></TT
> string is returned with the
<TT
CLASS="REPLACEABLE"
><I
>replacement</I
></TT
> string substituted for the matching
substring. The <TT
CLASS="REPLACEABLE"
><I
>replacement</I
></TT
> string can contain
<TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>, where <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
> is 1
through 9, to indicate that the source substring matching the
<TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>'th parenthesized subexpression of the pattern should be
inserted, and it can contain <TT
CLASS="LITERAL"
>\&</TT
> to indicate that the
substring matching the entire pattern should be inserted. Write
<TT
CLASS="LITERAL"
>\\</TT
> if you need to put a literal backslash in the replacement
text.
The <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. Flag <TT
CLASS="LITERAL"
>i</TT
> specifies case-insensitive
matching, while flag <TT
CLASS="LITERAL"
>g</TT
> specifies replacement of each matching
substring rather than only the first one. Other supported flags are
described in <A
HREF="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE"
>Table 9-20</A
>.
</P
><P
> Some examples:
</P><PRE
CLASS="PROGRAMLISTING"
>regexp_replace('foobarbaz', 'b..', 'X')
<I
CLASS="LINEANNOTATION"
>fooXbaz</I
>
regexp_replace('foobarbaz', 'b..', 'X', 'g')
<I
CLASS="LINEANNOTATION"
>fooXX</I
>
regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g')
<I
CLASS="LINEANNOTATION"
>fooXarYXazY</I
></PRE
><P>
</P
><P
> The <CODE
CLASS="FUNCTION"
>regexp_matches</CODE
> function returns a text array of
all of the captured substrings resulting from matching a POSIX
regular expression pattern. It has the syntax
<CODE
CLASS="FUNCTION"
>regexp_matches</CODE
>(<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
>, <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>
[<SPAN
CLASS="OPTIONAL"
>, <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> </SPAN
>]).
The function can return no rows, one row, or multiple rows (see
the <TT
CLASS="LITERAL"
>g</TT
> flag below). If the <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>
does not match, the function returns no rows. If the pattern
contains no parenthesized subexpressions, then each row
returned is a single-element text array containing the substring
matching the whole pattern. If the pattern contains parenthesized
subexpressions, the function returns a text array whose
<TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>'th element is the substring matching the
<TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>'th parenthesized subexpression of the pattern
(not counting <SPAN
CLASS="QUOTE"
>"non-capturing"</SPAN
> parentheses; see below for
details).
The <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. Flag <TT
CLASS="LITERAL"
>g</TT
> causes the function to find
each match in the string, not only the first one, and return a row for
each such match. Other supported
flags are described in <A
HREF="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE"
>Table 9-20</A
>.
</P
><P
> Some examples:
</P><PRE
CLASS="PROGRAMLISTING"
>SELECT regexp_matches('foobarbequebaz', '(bar)(beque)');
regexp_matches
----------------
{bar,beque}
(1 row)
SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g');
regexp_matches
----------------
{bar,beque}
{bazil,barf}
(2 rows)
SELECT regexp_matches('foobarbequebaz', 'barbeque');
regexp_matches
----------------
{barbeque}
(1 row)</PRE
><P>
</P
><P
> It is possible to force <CODE
CLASS="FUNCTION"
>regexp_matches()</CODE
> to always
return one row by using a sub-select; this is particularly useful
in a <TT
CLASS="LITERAL"
>SELECT</TT
> target list when you want all rows
returned, even non-matching ones:
</P><PRE
CLASS="PROGRAMLISTING"
>SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;</PRE
><P>
</P
><P
> The <CODE
CLASS="FUNCTION"
>regexp_split_to_table</CODE
> function splits a string using a POSIX
regular expression pattern as a delimiter. It has the syntax
<CODE
CLASS="FUNCTION"
>regexp_split_to_table</CODE
>(<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
>, <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>
[<SPAN
CLASS="OPTIONAL"
>, <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> </SPAN
>]).
If there is no match to the <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>, the function returns the
<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
>. 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 <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> parameter is an optional text string containing
zero or more single-letter flags that change the function's behavior.
<CODE
CLASS="FUNCTION"
>regexp_split_to_table</CODE
> supports the flags described in
<A
HREF="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE"
>Table 9-20</A
>.
</P
><P
> The <CODE
CLASS="FUNCTION"
>regexp_split_to_array</CODE
> function behaves the same as
<CODE
CLASS="FUNCTION"
>regexp_split_to_table</CODE
>, except that <CODE
CLASS="FUNCTION"
>regexp_split_to_array</CODE
>
returns its result as an array of <TT
CLASS="TYPE"
>text</TT
>. It has the syntax
<CODE
CLASS="FUNCTION"
>regexp_split_to_array</CODE
>(<TT
CLASS="REPLACEABLE"
><I
>string</I
></TT
>, <TT
CLASS="REPLACEABLE"
><I
>pattern</I
></TT
>
[<SPAN
CLASS="OPTIONAL"
>, <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> </SPAN
>]).
The parameters are the same as for <CODE
CLASS="FUNCTION"
>regexp_split_to_table</CODE
>.
</P
><P
> Some examples:
</P><PRE
CLASS="PROGRAMLISTING"
> SELECT foo FROM regexp_split_to_table('the quick brown fox jumped over the lazy dog', E'\\s+') AS foo;
foo
--------
the
quick
brown
fox
jumped
over
the
lazy
dog
(9 rows)
SELECT regexp_split_to_array('the quick brown fox jumped over the lazy dog', E'\\s+');
regexp_split_to_array
------------------------------------------------
{the,quick,brown,fox,jumped,over,the,lazy,dog}
(1 row)
SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
foo
-----
t
h
e
q
u
i
c
k
b
r
o
w
n
f
o
x
(16 rows)</PRE
><P>
</P
><P
> 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
<CODE
CLASS="FUNCTION"
>regexp_matches</CODE
>, but is usually the most convenient behavior
in practice. Other software systems such as Perl use similar definitions.
</P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="POSIX-SYNTAX-DETAILS"
>9.7.3.1. Regular Expression Details</A
></H3
><P
> <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>'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.
</P
><P
> Regular expressions (<ACRONYM
CLASS="ACRONYM"
>RE</ACRONYM
>s), as defined in
<ACRONYM
CLASS="ACRONYM"
>POSIX</ACRONYM
> 1003.2, come in two forms:
<I
CLASS="FIRSTTERM"
>extended</I
> <ACRONYM
CLASS="ACRONYM"
>RE</ACRONYM
>s or <ACRONYM
CLASS="ACRONYM"
>ERE</ACRONYM
>s
(roughly those of <TT
CLASS="COMMAND"
>egrep</TT
>), and
<I
CLASS="FIRSTTERM"
>basic</I
> <ACRONYM
CLASS="ACRONYM"
>RE</ACRONYM
>s or <ACRONYM
CLASS="ACRONYM"
>BRE</ACRONYM
>s
(roughly those of <TT
CLASS="COMMAND"
>ed</TT
>).
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> 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
CLASS="ACRONYM"
>RE</ACRONYM
>s using these non-POSIX extensions are called
<I
CLASS="FIRSTTERM"
>advanced</I
> <ACRONYM
CLASS="ACRONYM"
>RE</ACRONYM
>s or <ACRONYM
CLASS="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.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> 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 <I
CLASS="FIRSTTERM"
>embedded option</I
>
to the RE pattern, as described in <A
HREF="functions-matching.html#POSIX-METASYNTAX"
>Section 9.7.3.4</A
>.
This can be useful for compatibility with applications that expect
exactly the <ACRONYM
CLASS="ACRONYM"
>POSIX</ACRONYM
> 1003.2 rules.
</P
></BLOCKQUOTE
></DIV
><P
> A regular expression is defined as one or more
<I
CLASS="FIRSTTERM"
>branches</I
>, separated by
<TT
CLASS="LITERAL"
>|</TT
>. It matches anything that matches one of the
branches.
</P
><P
> A branch is zero or more <I
CLASS="FIRSTTERM"
>quantified atoms</I
> or
<I
CLASS="FIRSTTERM"
>constraints</I
>, concatenated.
It matches a match for the first, followed by a match for the second, etc;
an empty branch matches the empty string.
</P
><P
> A quantified atom is an <I
CLASS="FIRSTTERM"
>atom</I
> possibly followed
by a single <I
CLASS="FIRSTTERM"
>quantifier</I
>.
Without a quantifier, it matches a match for the atom.
With a quantifier, it can match some number of matches of the atom.
An <I
CLASS="FIRSTTERM"
>atom</I
> can be any of the possibilities
shown in <A
HREF="functions-matching.html#POSIX-ATOMS-TABLE"
>Table 9-13</A
>.
The possible quantifiers and their meanings are shown in
<A
HREF="functions-matching.html#POSIX-QUANTIFIERS-TABLE"
>Table 9-14</A
>.
</P
><P
> A <I
CLASS="FIRSTTERM"
>constraint</I
> 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
<A
HREF="functions-matching.html#POSIX-CONSTRAINTS-TABLE"
>Table 9-15</A
>;
some more constraints are described later.
</P
><DIV
CLASS="TABLE"
><A
NAME="POSIX-ATOMS-TABLE"
></A
><P
><B
>Table 9-13. Regular Expression Atoms</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Atom</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>(</TT
><TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
><TT
CLASS="LITERAL"
>)</TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
> is any regular expression)
matches a match for
<TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
>, with the match noted for possible reporting </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>(?:</TT
><TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
><TT
CLASS="LITERAL"
>)</TT
> </TD
><TD
> as above, but the match is not noted for reporting
(a <SPAN
CLASS="QUOTE"
>"non-capturing"</SPAN
> set of parentheses)
(AREs only) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>.</TT
> </TD
><TD
> matches any single character </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>[</TT
><TT
CLASS="REPLACEABLE"
><I
>chars</I
></TT
><TT
CLASS="LITERAL"
>]</TT
> </TD
><TD
> a <I
CLASS="FIRSTTERM"
>bracket expression</I
>,
matching any one of the <TT
CLASS="REPLACEABLE"
><I
>chars</I
></TT
> (see
<A
HREF="functions-matching.html#POSIX-BRACKET-EXPRESSIONS"
>Section 9.7.3.2</A
> for more detail) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>k</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>k</I
></TT
> is a non-alphanumeric character)
matches that character taken as an ordinary character,
e.g., <TT
CLASS="LITERAL"
>\\</TT
> matches a backslash character </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>c</I
></TT
> </TD
><TD
> where <TT
CLASS="REPLACEABLE"
><I
>c</I
></TT
> is alphanumeric
(possibly followed by other characters)
is an <I
CLASS="FIRSTTERM"
>escape</I
>, see <A
HREF="functions-matching.html#POSIX-ESCAPE-SEQUENCES"
>Section 9.7.3.3</A
>
(AREs only; in EREs and BREs, this matches <TT
CLASS="REPLACEABLE"
><I
>c</I
></TT
>) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>{</TT
> </TD
><TD
> when followed by a character other than a digit,
matches the left-brace character <TT
CLASS="LITERAL"
>{</TT
>;
when followed by a digit, it is the beginning of a
<TT
CLASS="REPLACEABLE"
><I
>bound</I
></TT
> (see below) </TD
></TR
><TR
><TD
> <TT
CLASS="REPLACEABLE"
><I
>x</I
></TT
> </TD
><TD
> where <TT
CLASS="REPLACEABLE"
><I
>x</I
></TT
> is a single character with no other
significance, matches that character </TD
></TR
></TBODY
></TABLE
></DIV
><P
> An RE cannot end with a backslash (<TT
CLASS="LITERAL"
>\</TT
>).
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> If you have <A
HREF="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS"
>standard_conforming_strings</A
> turned off,
any backslashes you write in literal string constants will need to be
doubled. See <A
HREF="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS"
>Section 4.1.2.1</A
> for more information.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="POSIX-QUANTIFIERS-TABLE"
></A
><P
><B
>Table 9-14. Regular Expression Quantifiers</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Quantifier</TH
><TH
>Matches</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>*</TT
> </TD
><TD
> a sequence of 0 or more matches of the atom </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>+</TT
> </TD
><TD
> a sequence of 1 or more matches of the atom </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>?</TT
> </TD
><TD
> a sequence of 0 or 1 matches of the atom </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>}</TT
> </TD
><TD
> a sequence of exactly <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> matches of the atom </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,}</TT
> </TD
><TD
> a sequence of <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> or more matches of the atom </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
><TT
CLASS="LITERAL"
>}</TT
> </TD
><TD
> a sequence of <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> through <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>
(inclusive) matches of the atom; <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> cannot exceed
<TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>*?</TT
> </TD
><TD
> non-greedy version of <TT
CLASS="LITERAL"
>*</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>+?</TT
> </TD
><TD
> non-greedy version of <TT
CLASS="LITERAL"
>+</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>??</TT
> </TD
><TD
> non-greedy version of <TT
CLASS="LITERAL"
>?</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>}?</TT
> </TD
><TD
> non-greedy version of <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>}</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,}?</TT
> </TD
><TD
> non-greedy version of <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,}</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
><TT
CLASS="LITERAL"
>}?</TT
> </TD
><TD
> non-greedy version of <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
><TT
CLASS="LITERAL"
>}</TT
> </TD
></TR
></TBODY
></TABLE
></DIV
><P
> The forms using <TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>...</I
></TT
><TT
CLASS="LITERAL"
>}</TT
>
are known as <I
CLASS="FIRSTTERM"
>bounds</I
>.
The numbers <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> and <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
> within a bound are
unsigned decimal integers with permissible values from 0 to 255 inclusive.
</P
><P
> <I
CLASS="FIRSTTERM"
>Non-greedy</I
> quantifiers (available in AREs only) match the
same possibilities as their corresponding normal (<I
CLASS="FIRSTTERM"
>greedy</I
>)
counterparts, but prefer the smallest number rather than the largest
number of matches.
See <A
HREF="functions-matching.html#POSIX-MATCHING-RULES"
>Section 9.7.3.5</A
> for more detail.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> A quantifier cannot immediately follow another quantifier, e.g.,
<TT
CLASS="LITERAL"
>**</TT
> is invalid.
A quantifier cannot
begin an expression or subexpression or follow
<TT
CLASS="LITERAL"
>^</TT
> or <TT
CLASS="LITERAL"
>|</TT
>.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="POSIX-CONSTRAINTS-TABLE"
></A
><P
><B
>Table 9-15. Regular Expression Constraints</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Constraint</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>^</TT
> </TD
><TD
> matches at the beginning of the string </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>$</TT
> </TD
><TD
> matches at the end of the string </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>(?=</TT
><TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
><TT
CLASS="LITERAL"
>)</TT
> </TD
><TD
> <I
CLASS="FIRSTTERM"
>positive lookahead</I
> matches at any point
where a substring matching <TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
> begins
(AREs only) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>(?!</TT
><TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
><TT
CLASS="LITERAL"
>)</TT
> </TD
><TD
> <I
CLASS="FIRSTTERM"
>negative lookahead</I
> matches at any point
where no substring matching <TT
CLASS="REPLACEABLE"
><I
>re</I
></TT
> begins
(AREs only) </TD
></TR
></TBODY
></TABLE
></DIV
><P
> Lookahead constraints cannot contain <I
CLASS="FIRSTTERM"
>back references</I
>
(see <A
HREF="functions-matching.html#POSIX-ESCAPE-SEQUENCES"
>Section 9.7.3.3</A
>),
and all parentheses within them are considered non-capturing.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="POSIX-BRACKET-EXPRESSIONS"
>9.7.3.2. Bracket Expressions</A
></H3
><P
> A <I
CLASS="FIRSTTERM"
>bracket expression</I
> is a list of
characters enclosed in <TT
CLASS="LITERAL"
>[]</TT
>. It normally matches
any single character from the list (but see below). If the list
begins with <TT
CLASS="LITERAL"
>^</TT
>, it matches any single character
<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> from the rest of the list.
If two characters
in the list are separated by <TT
CLASS="LITERAL"
>-</TT
>, this is
shorthand for the full range of characters between those two
(inclusive) in the collating sequence,
e.g., <TT
CLASS="LITERAL"
>[0-9]</TT
> in <ACRONYM
CLASS="ACRONYM"
>ASCII</ACRONYM
> matches
any decimal digit. It is illegal for two ranges to share an
endpoint, e.g., <TT
CLASS="LITERAL"
>a-c-e</TT
>. Ranges are very
collating-sequence-dependent, so portable programs should avoid
relying on them.
</P
><P
> To include a literal <TT
CLASS="LITERAL"
>]</TT
> in the list, make it the
first character (after <TT
CLASS="LITERAL"
>^</TT
>, if that is used). To
include a literal <TT
CLASS="LITERAL"
>-</TT
>, make it the first or last
character, or the second endpoint of a range. To use a literal
<TT
CLASS="LITERAL"
>-</TT
> as the first endpoint of a range, enclose it
in <TT
CLASS="LITERAL"
>[.</TT
> and <TT
CLASS="LITERAL"
>.]</TT
> to make it a
collating element (see below). With the exception of these characters,
some combinations using <TT
CLASS="LITERAL"
>[</TT
>
(see next paragraphs), and escapes (AREs only), all other special
characters lose their special significance within a bracket expression.
In particular, <TT
CLASS="LITERAL"
>\</TT
> is not special when following
ERE or BRE rules, though it is special (as introducing an escape)
in AREs.
</P
><P
> 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
<TT
CLASS="LITERAL"
>[.</TT
> and <TT
CLASS="LITERAL"
>.]</TT
> 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 <TT
CLASS="LITERAL"
>ch</TT
> collating element, then the RE
<TT
CLASS="LITERAL"
>[[.ch.]]*c</TT
> matches the first five characters of
<TT
CLASS="LITERAL"
>chchcc</TT
>.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> currently does not support multi-character collating
elements. This information describes possible future behavior.
</P
></BLOCKQUOTE
></DIV
><P
> Within a bracket expression, a collating element enclosed in
<TT
CLASS="LITERAL"
>[=</TT
> and <TT
CLASS="LITERAL"
>=]</TT
> is an <I
CLASS="FIRSTTERM"
>equivalence
class</I
>, 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 <TT
CLASS="LITERAL"
>[.</TT
> and
<TT
CLASS="LITERAL"
>.]</TT
>.) For example, if <TT
CLASS="LITERAL"
>o</TT
> and
<TT
CLASS="LITERAL"
>^</TT
> are the members of an equivalence class, then
<TT
CLASS="LITERAL"
>[[=o=]]</TT
>, <TT
CLASS="LITERAL"
>[[=^=]]</TT
>, and
<TT
CLASS="LITERAL"
>[o^]</TT
> are all synonymous. An equivalence class
cannot be an endpoint of a range.
</P
><P
> Within a bracket expression, the name of a character class
enclosed in <TT
CLASS="LITERAL"
>[:</TT
> and <TT
CLASS="LITERAL"
>:]</TT
> stands
for the list of all characters belonging to that class. Standard
character class names are: <TT
CLASS="LITERAL"
>alnum</TT
>,
<TT
CLASS="LITERAL"
>alpha</TT
>, <TT
CLASS="LITERAL"
>blank</TT
>,
<TT
CLASS="LITERAL"
>cntrl</TT
>, <TT
CLASS="LITERAL"
>digit</TT
>,
<TT
CLASS="LITERAL"
>graph</TT
>, <TT
CLASS="LITERAL"
>lower</TT
>,
<TT
CLASS="LITERAL"
>print</TT
>, <TT
CLASS="LITERAL"
>punct</TT
>,
<TT
CLASS="LITERAL"
>space</TT
>, <TT
CLASS="LITERAL"
>upper</TT
>,
<TT
CLASS="LITERAL"
>xdigit</TT
>. These stand for the character classes
defined in
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>ctype</SPAN
></SPAN
>.
A locale can provide others. A character class cannot be used as
an endpoint of a range.
</P
><P
> There are two special cases of bracket expressions: the bracket
expressions <TT
CLASS="LITERAL"
>[[:<:]]</TT
> and
<TT
CLASS="LITERAL"
>[[:>:]]</TT
> 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 an <TT
CLASS="LITERAL"
>alnum</TT
> character (as
defined by
<SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>ctype</SPAN
></SPAN
>)
or an underscore. This is an extension, compatible with but not
specified by <ACRONYM
CLASS="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.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="POSIX-ESCAPE-SEQUENCES"
>9.7.3.3. Regular Expression Escapes</A
></H3
><P
> <I
CLASS="FIRSTTERM"
>Escapes</I
> are special sequences beginning with <TT
CLASS="LITERAL"
>\</TT
>
followed by an alphanumeric character. Escapes come in several varieties:
character entry, class shorthands, constraint escapes, and back references.
A <TT
CLASS="LITERAL"
>\</TT
> 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 <TT
CLASS="LITERAL"
>\</TT
> followed by an alphanumeric character merely stands for
that character as an ordinary character, and inside a bracket expression,
<TT
CLASS="LITERAL"
>\</TT
> is an ordinary character.
(The latter is the one actual incompatibility between EREs and AREs.)
</P
><P
> <I
CLASS="FIRSTTERM"
>Character-entry escapes</I
> exist to make it easier to specify
non-printing and other inconvenient characters in REs. They are
shown in <A
HREF="functions-matching.html#POSIX-CHARACTER-ENTRY-ESCAPES-TABLE"
>Table 9-16</A
>.
</P
><P
> <I
CLASS="FIRSTTERM"
>Class-shorthand escapes</I
> provide shorthands for certain
commonly-used character classes. They are
shown in <A
HREF="functions-matching.html#POSIX-CLASS-SHORTHAND-ESCAPES-TABLE"
>Table 9-17</A
>.
</P
><P
> A <I
CLASS="FIRSTTERM"
>constraint escape</I
> is a constraint,
matching the empty string if specific conditions are met,
written as an escape. They are
shown in <A
HREF="functions-matching.html#POSIX-CONSTRAINT-ESCAPES-TABLE"
>Table 9-18</A
>.
</P
><P
> A <I
CLASS="FIRSTTERM"
>back reference</I
> (<TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>) matches the
same string matched by the previous parenthesized subexpression specified
by the number <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>
(see <A
HREF="functions-matching.html#POSIX-CONSTRAINT-BACKREF-TABLE"
>Table 9-19</A
>). For example,
<TT
CLASS="LITERAL"
>([bc])\1</TT
> matches <TT
CLASS="LITERAL"
>bb</TT
> or <TT
CLASS="LITERAL"
>cc</TT
>
but not <TT
CLASS="LITERAL"
>bc</TT
> or <TT
CLASS="LITERAL"
>cb</TT
>.
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.
</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> Keep in mind that an escape's leading <TT
CLASS="LITERAL"
>\</TT
> will need to be
doubled when entering the pattern as an SQL string constant. For example:
</P><PRE
CLASS="PROGRAMLISTING"
>'123' ~ E'^\\d{3}' <I
CLASS="LINEANNOTATION"
>true</I
></PRE
><P>
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="TABLE"
><A
NAME="POSIX-CHARACTER-ENTRY-ESCAPES-TABLE"
></A
><P
><B
>Table 9-16. Regular Expression Character-entry Escapes</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Escape</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>\a</TT
> </TD
><TD
> alert (bell) character, as in C </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\b</TT
> </TD
><TD
> backspace, as in C </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\B</TT
> </TD
><TD
> synonym for backslash (<TT
CLASS="LITERAL"
>\</TT
>) to help reduce the need for backslash
doubling </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\c</TT
><TT
CLASS="REPLACEABLE"
><I
>X</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>X</I
></TT
> is any character) the character whose
low-order 5 bits are the same as those of
<TT
CLASS="REPLACEABLE"
><I
>X</I
></TT
>, and whose other bits are all zero </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\e</TT
> </TD
><TD
> the character whose collating-sequence name
is <TT
CLASS="LITERAL"
>ESC</TT
>,
or failing that, the character with octal value <TT
CLASS="LITERAL"
>033</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\f</TT
> </TD
><TD
> form feed, as in C </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\n</TT
> </TD
><TD
> newline, as in C </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\r</TT
> </TD
><TD
> carriage return, as in C </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\t</TT
> </TD
><TD
> horizontal tab, as in C </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\u</TT
><TT
CLASS="REPLACEABLE"
><I
>wxyz</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>wxyz</I
></TT
> is exactly four hexadecimal digits)
the character whose hexadecimal value is
<TT
CLASS="LITERAL"
>0x</TT
><TT
CLASS="REPLACEABLE"
><I
>wxyz</I
></TT
>
</TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\U</TT
><TT
CLASS="REPLACEABLE"
><I
>stuvwxyz</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>stuvwxyz</I
></TT
> is exactly eight hexadecimal
digits)
the character whose hexadecimal value is
<TT
CLASS="LITERAL"
>0x</TT
><TT
CLASS="REPLACEABLE"
><I
>stuvwxyz</I
></TT
>
</TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\v</TT
> </TD
><TD
> vertical tab, as in C </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\x</TT
><TT
CLASS="REPLACEABLE"
><I
>hhh</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>hhh</I
></TT
> is any sequence of hexadecimal
digits)
the character whose hexadecimal value is
<TT
CLASS="LITERAL"
>0x</TT
><TT
CLASS="REPLACEABLE"
><I
>hhh</I
></TT
>
(a single character no matter how many hexadecimal digits are used)
</TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\0</TT
> </TD
><TD
> the character whose value is <TT
CLASS="LITERAL"
>0</TT
> (the null byte)</TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>xy</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>xy</I
></TT
> is exactly two octal digits,
and is not a <I
CLASS="FIRSTTERM"
>back reference</I
>)
the character whose octal value is
<TT
CLASS="LITERAL"
>0</TT
><TT
CLASS="REPLACEABLE"
><I
>xy</I
></TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>xyz</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>xyz</I
></TT
> is exactly three octal digits,
and is not a <I
CLASS="FIRSTTERM"
>back reference</I
>)
the character whose octal value is
<TT
CLASS="LITERAL"
>0</TT
><TT
CLASS="REPLACEABLE"
><I
>xyz</I
></TT
> </TD
></TR
></TBODY
></TABLE
></DIV
><P
> Hexadecimal digits are <TT
CLASS="LITERAL"
>0</TT
>-<TT
CLASS="LITERAL"
>9</TT
>,
<TT
CLASS="LITERAL"
>a</TT
>-<TT
CLASS="LITERAL"
>f</TT
>, and <TT
CLASS="LITERAL"
>A</TT
>-<TT
CLASS="LITERAL"
>F</TT
>.
Octal digits are <TT
CLASS="LITERAL"
>0</TT
>-<TT
CLASS="LITERAL"
>7</TT
>.
</P
><P
> 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 <TT
CLASS="LITERAL"
>\u1234</TT
> means the character <TT
CLASS="LITERAL"
>U+1234</TT
>.
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.
</P
><P
> The character-entry escapes are always taken as ordinary characters.
For example, <TT
CLASS="LITERAL"
>\135</TT
> is <TT
CLASS="LITERAL"
>]</TT
> in ASCII, but
<TT
CLASS="LITERAL"
>\135</TT
> does not terminate a bracket expression.
</P
><DIV
CLASS="TABLE"
><A
NAME="POSIX-CLASS-SHORTHAND-ESCAPES-TABLE"
></A
><P
><B
>Table 9-17. Regular Expression Class-shorthand Escapes</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Escape</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>\d</TT
> </TD
><TD
> <TT
CLASS="LITERAL"
>[[:digit:]]</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\s</TT
> </TD
><TD
> <TT
CLASS="LITERAL"
>[[:space:]]</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\w</TT
> </TD
><TD
> <TT
CLASS="LITERAL"
>[[:alnum:]_]</TT
>
(note underscore is included) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\D</TT
> </TD
><TD
> <TT
CLASS="LITERAL"
>[^[:digit:]]</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\S</TT
> </TD
><TD
> <TT
CLASS="LITERAL"
>[^[:space:]]</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\W</TT
> </TD
><TD
> <TT
CLASS="LITERAL"
>[^[:alnum:]_]</TT
>
(note underscore is included) </TD
></TR
></TBODY
></TABLE
></DIV
><P
> Within bracket expressions, <TT
CLASS="LITERAL"
>\d</TT
>, <TT
CLASS="LITERAL"
>\s</TT
>,
and <TT
CLASS="LITERAL"
>\w</TT
> lose their outer brackets,
and <TT
CLASS="LITERAL"
>\D</TT
>, <TT
CLASS="LITERAL"
>\S</TT
>, and <TT
CLASS="LITERAL"
>\W</TT
> are illegal.
(So, for example, <TT
CLASS="LITERAL"
>[a-c\d]</TT
> is equivalent to
<TT
CLASS="LITERAL"
>[a-c[:digit:]]</TT
>.
Also, <TT
CLASS="LITERAL"
>[a-c\D]</TT
>, which is equivalent to
<TT
CLASS="LITERAL"
>[a-c^[:digit:]]</TT
>, is illegal.)
</P
><DIV
CLASS="TABLE"
><A
NAME="POSIX-CONSTRAINT-ESCAPES-TABLE"
></A
><P
><B
>Table 9-18. Regular Expression Constraint Escapes</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Escape</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>\A</TT
> </TD
><TD
> matches only at the beginning of the string
(see <A
HREF="functions-matching.html#POSIX-MATCHING-RULES"
>Section 9.7.3.5</A
> for how this differs from
<TT
CLASS="LITERAL"
>^</TT
>) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\m</TT
> </TD
><TD
> matches only at the beginning of a word </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\M</TT
> </TD
><TD
> matches only at the end of a word </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\y</TT
> </TD
><TD
> matches only at the beginning or end of a word </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\Y</TT
> </TD
><TD
> matches only at a point that is not the beginning or end of a
word </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\Z</TT
> </TD
><TD
> matches only at the end of the string
(see <A
HREF="functions-matching.html#POSIX-MATCHING-RULES"
>Section 9.7.3.5</A
> for how this differs from
<TT
CLASS="LITERAL"
>$</TT
>) </TD
></TR
></TBODY
></TABLE
></DIV
><P
> A word is defined as in the specification of
<TT
CLASS="LITERAL"
>[[:<:]]</TT
> and <TT
CLASS="LITERAL"
>[[:>:]]</TT
> above.
Constraint escapes are illegal within bracket expressions.
</P
><DIV
CLASS="TABLE"
><A
NAME="POSIX-CONSTRAINT-BACKREF-TABLE"
></A
><P
><B
>Table 9-19. Regular Expression Back References</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Escape</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> is a nonzero digit)
a back reference to the <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
>'th subexpression </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>\</TT
><TT
CLASS="REPLACEABLE"
><I
>mnn</I
></TT
> </TD
><TD
> (where <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> is a nonzero digit, and
<TT
CLASS="REPLACEABLE"
><I
>nn</I
></TT
> is some more digits, and the decimal value
<TT
CLASS="REPLACEABLE"
><I
>mnn</I
></TT
> is not greater than the number of closing capturing
parentheses seen so far)
a back reference to the <TT
CLASS="REPLACEABLE"
><I
>mnn</I
></TT
>'th subexpression </TD
></TR
></TBODY
></TABLE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
> 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.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="POSIX-METASYNTAX"
>9.7.3.4. Regular Expression Metasyntax</A
></H3
><P
> In addition to the main syntax described above, there are some special
forms and miscellaneous syntactic facilities available.
</P
><P
> An RE can begin with one of two special <I
CLASS="FIRSTTERM"
>director</I
> prefixes.
If an RE begins with <TT
CLASS="LITERAL"
>***:</TT
>,
the rest of the RE is taken as an ARE. (This normally has no effect in
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>, since REs are assumed to be AREs;
but it does have an effect if ERE or BRE mode had been specified by
the <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> parameter to a regex function.)
If an RE begins with <TT
CLASS="LITERAL"
>***=</TT
>,
the rest of the RE is taken to be a literal string,
with all characters considered ordinary characters.
</P
><P
> An ARE can begin with <I
CLASS="FIRSTTERM"
>embedded options</I
>:
a sequence <TT
CLASS="LITERAL"
>(?</TT
><TT
CLASS="REPLACEABLE"
><I
>xyz</I
></TT
><TT
CLASS="LITERAL"
>)</TT
>
(where <TT
CLASS="REPLACEABLE"
><I
>xyz</I
></TT
> 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 <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
> parameter to a regex
function.
The available option letters are
shown in <A
HREF="functions-matching.html#POSIX-EMBEDDED-OPTIONS-TABLE"
>Table 9-20</A
>.
Note that these same option letters are used in the <TT
CLASS="REPLACEABLE"
><I
>flags</I
></TT
>
parameters of regex functions.
</P
><DIV
CLASS="TABLE"
><A
NAME="POSIX-EMBEDDED-OPTIONS-TABLE"
></A
><P
><B
>Table 9-20. ARE Embedded-option Letters</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Option</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
> <TT
CLASS="LITERAL"
>b</TT
> </TD
><TD
> rest of RE is a BRE </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>c</TT
> </TD
><TD
> case-sensitive matching (overrides operator type) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>e</TT
> </TD
><TD
> rest of RE is an ERE </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>i</TT
> </TD
><TD
> case-insensitive matching (see
<A
HREF="functions-matching.html#POSIX-MATCHING-RULES"
>Section 9.7.3.5</A
>) (overrides operator type) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>m</TT
> </TD
><TD
> historical synonym for <TT
CLASS="LITERAL"
>n</TT
> </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>n</TT
> </TD
><TD
> newline-sensitive matching (see
<A
HREF="functions-matching.html#POSIX-MATCHING-RULES"
>Section 9.7.3.5</A
>) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>p</TT
> </TD
><TD
> partial newline-sensitive matching (see
<A
HREF="functions-matching.html#POSIX-MATCHING-RULES"
>Section 9.7.3.5</A
>) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>q</TT
> </TD
><TD
> rest of RE is a literal (<SPAN
CLASS="QUOTE"
>"quoted"</SPAN
>) string, all ordinary
characters </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>s</TT
> </TD
><TD
> non-newline-sensitive matching (default) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>t</TT
> </TD
><TD
> tight syntax (default; see below) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>w</TT
> </TD
><TD
> inverse partial newline-sensitive (<SPAN
CLASS="QUOTE"
>"weird"</SPAN
>) matching
(see <A
HREF="functions-matching.html#POSIX-MATCHING-RULES"
>Section 9.7.3.5</A
>) </TD
></TR
><TR
><TD
> <TT
CLASS="LITERAL"
>x</TT
> </TD
><TD
> expanded syntax (see below) </TD
></TR
></TBODY
></TABLE
></DIV
><P
> Embedded options take effect at the <TT
CLASS="LITERAL"
>)</TT
> terminating the sequence.
They can appear only at the start of an ARE (after the
<TT
CLASS="LITERAL"
>***:</TT
> director if any).
</P
><P
> In addition to the usual (<I
CLASS="FIRSTTERM"
>tight</I
>) RE syntax, in which all
characters are significant, there is an <I
CLASS="FIRSTTERM"
>expanded</I
> syntax,
available by specifying the embedded <TT
CLASS="LITERAL"
>x</TT
> option.
In the expanded syntax,
white-space characters in the RE are ignored, as are
all characters between a <TT
CLASS="LITERAL"
>#</TT
>
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:
<P
></P
></P><UL
><LI
><P
> a white-space character or <TT
CLASS="LITERAL"
>#</TT
> preceded by <TT
CLASS="LITERAL"
>\</TT
> is
retained
</P
></LI
><LI
><P
> white space or <TT
CLASS="LITERAL"
>#</TT
> within a bracket expression is retained
</P
></LI
><LI
><P
> white space and comments cannot appear within multi-character symbols,
such as <TT
CLASS="LITERAL"
>(?:</TT
>
</P
></LI
></UL
><P>
For this purpose, white-space characters are blank, tab, newline, and
any character that belongs to the <TT
CLASS="REPLACEABLE"
><I
>space</I
></TT
> character class.
</P
><P
> Finally, in an ARE, outside bracket expressions, the sequence
<TT
CLASS="LITERAL"
>(?#</TT
><TT
CLASS="REPLACEABLE"
><I
>ttt</I
></TT
><TT
CLASS="LITERAL"
>)</TT
>
(where <TT
CLASS="REPLACEABLE"
><I
>ttt</I
></TT
> is any text not containing a <TT
CLASS="LITERAL"
>)</TT
>)
is a comment, completely ignored.
Again, this is not allowed between the characters of
multi-character symbols, like <TT
CLASS="LITERAL"
>(?:</TT
>.
Such comments are more a historical artifact than a useful facility,
and their use is deprecated; use the expanded syntax instead.
</P
><P
> <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>None</I
></SPAN
> of these metasyntax extensions is available if
an initial <TT
CLASS="LITERAL"
>***=</TT
> director
has specified that the user's input be treated as a literal string
rather than as an RE.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="POSIX-MATCHING-RULES"
>9.7.3.5. Regular Expression Matching Rules</A
></H3
><P
> 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 <I
CLASS="FIRSTTERM"
>greedy</I
> or
<I
CLASS="FIRSTTERM"
>non-greedy</I
>.
</P
><P
> Whether an RE is greedy or not is determined by the following rules:
<P
></P
></P><UL
><LI
><P
> Most atoms, and all constraints, have no greediness attribute (because
they cannot match variable amounts of text anyway).
</P
></LI
><LI
><P
> Adding parentheses around an RE does not change its greediness.
</P
></LI
><LI
><P
> A quantified atom with a fixed-repetition quantifier
(<TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>}</TT
>
or
<TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>}?</TT
>)
has the same greediness (possibly none) as the atom itself.
</P
></LI
><LI
><P
> A quantified atom with other normal quantifiers (including
<TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
><TT
CLASS="LITERAL"
>}</TT
>
with <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> equal to <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>)
is greedy (prefers longest match).
</P
></LI
><LI
><P
> A quantified atom with a non-greedy quantifier (including
<TT
CLASS="LITERAL"
>{</TT
><TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
><TT
CLASS="LITERAL"
>,</TT
><TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
><TT
CLASS="LITERAL"
>}?</TT
>
with <TT
CLASS="REPLACEABLE"
><I
>m</I
></TT
> equal to <TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
>)
is non-greedy (prefers shortest match).
</P
></LI
><LI
><P
> A branch — that is, an RE that has no top-level
<TT
CLASS="LITERAL"
>|</TT
> operator — has the same greediness as the first
quantified atom in it that has a greediness attribute.
</P
></LI
><LI
><P
> An RE consisting of two or more branches connected by the
<TT
CLASS="LITERAL"
>|</TT
> operator is always greedy.
</P
></LI
></UL
><P>
</P
><P
> 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 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>as a whole</I
></SPAN
>. 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.
</P
><P
> An example of what this means:
</P><PRE
CLASS="SCREEN"
>SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');
<I
CLASS="LINEANNOTATION"
>Result: </I
><SAMP
CLASS="COMPUTEROUTPUT"
>123</SAMP
>
SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<I
CLASS="LINEANNOTATION"
>Result: </I
><SAMP
CLASS="COMPUTEROUTPUT"
>1</SAMP
></PRE
><P>
In the first case, the RE as a whole is greedy because <TT
CLASS="LITERAL"
>Y*</TT
>
is greedy. It can match beginning at the <TT
CLASS="LITERAL"
>Y</TT
>, and it matches
the longest possible string starting there, i.e., <TT
CLASS="LITERAL"
>Y123</TT
>.
The output is the parenthesized part of that, or <TT
CLASS="LITERAL"
>123</TT
>.
In the second case, the RE as a whole is non-greedy because <TT
CLASS="LITERAL"
>Y*?</TT
>
is non-greedy. It can match beginning at the <TT
CLASS="LITERAL"
>Y</TT
>, and it matches
the shortest possible string starting there, i.e., <TT
CLASS="LITERAL"
>Y1</TT
>.
The subexpression <TT
CLASS="LITERAL"
>[0-9]{1,3}</TT
> is greedy but it cannot change
the decision as to the overall match length; so it is forced to match
just <TT
CLASS="LITERAL"
>1</TT
>.
</P
><P
> 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 <SPAN
CLASS="QUOTE"
>"eat"</SPAN
> relative to each other.
</P
><P
> The quantifiers <TT
CLASS="LITERAL"
>{1,1}</TT
> and <TT
CLASS="LITERAL"
>{1,1}?</TT
>
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:
</P><PRE
CLASS="SCREEN"
>SELECT regexp_matches('abc01234xyz', '(.*)(\d+)(.*)');
<I
CLASS="LINEANNOTATION"
>Result: </I
><SAMP
CLASS="COMPUTEROUTPUT"
>{abc0123,4,xyz}</SAMP
></PRE
><P>
That didn't work: the first <TT
CLASS="LITERAL"
>.*</TT
> is greedy so
it <SPAN
CLASS="QUOTE"
>"eats"</SPAN
> as much as it can, leaving the <TT
CLASS="LITERAL"
>\d+</TT
> to
match at the last possible place, the last digit. We might try to fix
that by making it non-greedy:
</P><PRE
CLASS="SCREEN"
>SELECT regexp_matches('abc01234xyz', '(.*?)(\d+)(.*)');
<I
CLASS="LINEANNOTATION"
>Result: </I
><SAMP
CLASS="COMPUTEROUTPUT"
>{abc,0,""}</SAMP
></PRE
><P>
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:
</P><PRE
CLASS="SCREEN"
>SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
<I
CLASS="LINEANNOTATION"
>Result: </I
><SAMP
CLASS="COMPUTEROUTPUT"
>{abc,01234,xyz}</SAMP
></PRE
><P>
Controlling the RE's overall greediness separately from its components'
greediness allows great flexibility in handling variable-length patterns.
</P
><P
> 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:
<TT
CLASS="LITERAL"
>bb*</TT
>
matches the three middle characters of <TT
CLASS="LITERAL"
>abbbc</TT
>;
<TT
CLASS="LITERAL"
>(week|wee)(night|knights)</TT
>
matches all ten characters of <TT
CLASS="LITERAL"
>weeknights</TT
>;
when <TT
CLASS="LITERAL"
>(.*).*</TT
>
is matched against <TT
CLASS="LITERAL"
>abc</TT
> the parenthesized subexpression
matches all three characters; and when
<TT
CLASS="LITERAL"
>(a*)*</TT
> is matched against <TT
CLASS="LITERAL"
>bc</TT
>
both the whole RE and the parenthesized
subexpression match an empty string.
</P
><P
> 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., <TT
CLASS="LITERAL"
>x</TT
> becomes <TT
CLASS="LITERAL"
>[xX]</TT
>.
When it appears inside a bracket expression, all case counterparts
of it are added to the bracket expression, e.g.,
<TT
CLASS="LITERAL"
>[x]</TT
> becomes <TT
CLASS="LITERAL"
>[xX]</TT
>
and <TT
CLASS="LITERAL"
>[^x]</TT
> becomes <TT
CLASS="LITERAL"
>[^xX]</TT
>.
</P
><P
> If newline-sensitive matching is specified, <TT
CLASS="LITERAL"
>.</TT
>
and bracket expressions using <TT
CLASS="LITERAL"
>^</TT
>
will never match the newline character
(so that matches will never cross newlines unless the RE
explicitly arranges it)
and <TT
CLASS="LITERAL"
>^</TT
>and <TT
CLASS="LITERAL"
>$</TT
>
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 <TT
CLASS="LITERAL"
>\A</TT
> and <TT
CLASS="LITERAL"
>\Z</TT
>
continue to match beginning or end of string <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>only</I
></SPAN
>.
</P
><P
> If partial newline-sensitive matching is specified,
this affects <TT
CLASS="LITERAL"
>.</TT
> and bracket expressions
as with newline-sensitive matching, but not <TT
CLASS="LITERAL"
>^</TT
>
and <TT
CLASS="LITERAL"
>$</TT
>.
</P
><P
> If inverse partial newline-sensitive matching is specified,
this affects <TT
CLASS="LITERAL"
>^</TT
> and <TT
CLASS="LITERAL"
>$</TT
>
as with newline-sensitive matching, but not <TT
CLASS="LITERAL"
>.</TT
>
and bracket expressions.
This isn't very useful but is provided for symmetry.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="POSIX-LIMITS-COMPATIBILITY"
>9.7.3.6. Limits and Compatibility</A
></H3
><P
> 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.
</P
><P
> The only feature of AREs that is actually incompatible with
POSIX EREs is that <TT
CLASS="LITERAL"
>\</TT
> 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 <TT
CLASS="LITERAL"
>***</TT
> syntax of directors likewise is outside the POSIX
syntax for both BREs and EREs.
</P
><P
> 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 <TT
CLASS="LITERAL"
>\b</TT
>, <TT
CLASS="LITERAL"
>\B</TT
>,
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
constraints, and the longest/shortest-match (rather than first-match)
matching semantics.
</P
><P
> Two significant incompatibilities exist between AREs and the ERE syntax
recognized by pre-7.4 releases of <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>:
<P
></P
></P><UL
><LI
><P
> In AREs, <TT
CLASS="LITERAL"
>\</TT
> followed by an alphanumeric character is either
an escape or an error, while in previous releases, it was just another
way of writing the alphanumeric.
This should not be much of a problem because there was no reason to
write such a sequence in earlier releases.
</P
></LI
><LI
><P
> In AREs, <TT
CLASS="LITERAL"
>\</TT
> remains a special character within
<TT
CLASS="LITERAL"
>[]</TT
>, so a literal <TT
CLASS="LITERAL"
>\</TT
> within a bracket
expression must be written <TT
CLASS="LITERAL"
>\\</TT
>.
</P
></LI
></UL
><P>
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="POSIX-BASIC-REGEXES"
>9.7.3.7. Basic Regular Expressions</A
></H3
><P
> BREs differ from EREs in several respects.
In BREs, <TT
CLASS="LITERAL"
>|</TT
>, <TT
CLASS="LITERAL"
>+</TT
>, and <TT
CLASS="LITERAL"
>?</TT
>
are ordinary characters and there is no equivalent
for their functionality.
The delimiters for bounds are
<TT
CLASS="LITERAL"
>\{</TT
> and <TT
CLASS="LITERAL"
>\}</TT
>,
with <TT
CLASS="LITERAL"
>{</TT
> and <TT
CLASS="LITERAL"
>}</TT
>
by themselves ordinary characters.
The parentheses for nested subexpressions are
<TT
CLASS="LITERAL"
>\(</TT
> and <TT
CLASS="LITERAL"
>\)</TT
>,
with <TT
CLASS="LITERAL"
>(</TT
> and <TT
CLASS="LITERAL"
>)</TT
> by themselves ordinary characters.
<TT
CLASS="LITERAL"
>^</TT
> is an ordinary character except at the beginning of the
RE or the beginning of a parenthesized subexpression,
<TT
CLASS="LITERAL"
>$</TT
> is an ordinary character except at the end of the
RE or the end of a parenthesized subexpression,
and <TT
CLASS="LITERAL"
>*</TT
> is an ordinary character if it appears at the beginning
of the RE or the beginning of a parenthesized subexpression
(after a possible leading <TT
CLASS="LITERAL"
>^</TT
>).
Finally, single-digit back references are available, and
<TT
CLASS="LITERAL"
>\<</TT
> and <TT
CLASS="LITERAL"
>\></TT
>
are synonyms for
<TT
CLASS="LITERAL"
>[[:<:]]</TT
> and <TT
CLASS="LITERAL"
>[[:>:]]</TT
>
respectively; no other escapes are available in BREs.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="functions-bitstring.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="functions-formatting.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Bit String Functions and Operators</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="functions.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Data Type Formatting Functions</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>