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

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