mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document regexp_matches() better and show example of single-row usage.

Browse Source
This commit is contained in:
Bruce Momjian 2010-06-03 14:40:42 +00:00
parent 3b19a45964
commit 0562820097
1 changed files with 22 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/src/sgml/func.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.515 2010/06/03 02:06:10 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.516 2010/06/03 14:40:42 momjian Exp $ -->
<chapter id="functions"> <chapter id="functions">
<title>Functions and Operators</title> <title>Functions and Operators</title>
@ -3445,19 +3445,22 @@ regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g')
</para> </para>
<para> <para>
The <function>regexp_matches</> function returns all of the captured The <function>regexp_matches</> function returns a text array of
substrings resulting from matching a POSIX regular expression pattern. all of the captured substrings resulting from matching a POSIX
It has the syntax regular expression pattern. It has the syntax
<function>regexp_matches</function>(<replaceable>string</>, <replaceable>pattern</> <function>regexp_matches</function>(<replaceable>string</>, <replaceable>pattern</>
<optional>, <replaceable>flags</> </optional>). <optional>, <replaceable>flags</> </optional>).
If there is no match to the <replaceable>pattern</>, the function returns The function can return no rows, one row, or multiple rows (see
no rows. If there is a match, the function returns a text array whose the <literal>g</> flag below). If the <replaceable>pattern</>
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
<replaceable>n</>'th element is the substring matching the <replaceable>n</>'th element is the substring matching the
<replaceable>n</>'th parenthesized subexpression of the pattern <replaceable>n</>'th parenthesized subexpression of the pattern
(not counting <quote>non-capturing</> parentheses; see below for (not counting <quote>non-capturing</> parentheses; see below for
details). If the pattern does not contain any parenthesized details).
subexpressions, then the result is a single-element text array containing
the substring matching the whole pattern.
The <replaceable>flags</> parameter is an optional text The <replaceable>flags</> parameter is an optional text
string containing zero or more single-letter flags that change the string containing zero or more single-letter flags that change the
function's behavior. Flag <literal>g</> causes the function to find function's behavior. Flag <literal>g</> causes the function to find
@ -3487,6 +3490,16 @@ SELECT regexp_matches('foobarbequebaz', 'barbeque');
---------------- ----------------
{barbeque} {barbeque}
(1 row) (1 row)
</programlisting>
</para>
<para>
It is possible to force <function>regexp_matches()</> to always
return one row by using a sub-select; this is particularly useful
in a <literal>SELECT</> target list when you want all rows
returned, even non-matching ones:
<programlisting>
SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
</programlisting> </programlisting>
</para> </para>