doc: for various substring funcs, document if only first match

Reported-by: [email protected]
Discussion: https://postgr.es/m/162614304115.701.2392941350859387646@wrigleys.postgresql.org

Backpatch-through: 13

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index f62c33e5c71a01364756c12003aac2b65abf3769..741dfbae4a50a8dc6ee3313c10bb979fb86fa53b 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2573,8 +2573,9 @@ repeat('Pg', 4) PgPgPgPg
         integer
        
        
-        Returns starting index of specified substring
-        within string, or zero if it's not present.
+        Returns first starting index of the specified
+        substring within
+        string, or zero if it's not present.
        
        
         position('om' in 'Thomas')
@@ -2617,7 +2618,7 @@ repeat('Pg', 4) PgPgPgPg
         text
        
        
-        Extracts substring matching POSIX regular expression; see
+        Extracts the first substring matching POSIX regular expression; see
         .
        
        
@@ -2636,7 +2637,7 @@ repeat('Pg', 4) PgPgPgPg
         text
        
        
-        Extracts substring matching SQL regular expression;
+        Extracts the first substring matching SQL regular expression;
         see .  The first form has
         been specified since SQL:2003; the second form was only in SQL:1999
         and should be considered obsolete.
@@ -3116,7 +3117,7 @@ repeat('Pg', 4) PgPgPgPg
         text[]
        
        
-        Returns captured substring(s) resulting from the first match of a POSIX
+        Returns captured substrings resulting from the first match of a POSIX
         regular expression to the string; see
         .
        
@@ -3135,9 +3136,10 @@ repeat('Pg', 4) PgPgPgPg
         setof text[]
        
        
-        Returns captured substring(s) resulting from matching a POSIX regular
-        expression to the string; see
-        .
+        Returns captured substrings resulting from the first match of a
+        POSIX regular expression to the string,
+        or multiple matches if the g flag is used;
+        see .
        
        
         regexp_matches('foobarbequebaz', 'ba.', 'g')
@@ -3158,8 +3160,10 @@ repeat('Pg', 4) PgPgPgPg
         text
        
        
-        Replaces substring(s) matching a POSIX regular expression; see
-        .
+        Replaces substrings resulting from the first match of a
+        POSIX regular expression, or multiple substring matches
+        if the g flag is used; see 
+        linkend="functions-posix-regexp"/>.
        
        
         regexp_replace('Thomas', '.[mN]a.', 'M')
@@ -3364,7 +3368,7 @@ repeat('Pg', 4) PgPgPgPg
         integer
        
        
-        Returns starting index of specified substring
+        Returns first starting index of the specified substring
         within string, or zero if it's not present.
         (Same as position(substring in
         string), but note the reversed
@@ -3965,8 +3969,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         integer
        
        
-        Returns starting index of specified substring
-        within bytes, or zero if it's not present.
+        Returns first starting index of the specified
+        substring within
+        bytes, or zero if it's not present.
        
        
         position('\x5678'::bytea in '\x1234567890'::bytea)
@@ -4892,7 +4897,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         integer
        
        
-        Returns starting index of specified substring
+        Returns first starting index of the specified substring
         within bits, or zero if it's not present.
        
        
@@ -5518,7 +5523,7 @@ substring('foobar' similar '#"o_b#"%' escape '#')    NULL
      pattern), 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
+     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