From d629fcf4b36ca8c1e4e9677745ff7d725433ee19 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Mon, 26 Jul 2021 22:54:35 -0400
Subject: [PATCH] doc:  for various substring funcs, document if only first
 match

Reported-by: troy@frericks.us

Discussion: https://postgr.es/m/162614304115.701.2392941350859387646@wrigleys.postgresql.org

Backpatch-through: 13
---
 doc/src/sgml/func.sgml | 35 ++++++++++++++++++++---------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 32328de46d..afaa8d0d21 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2626,8 +2626,9 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>integer</returnvalue>
        </para>
        <para>
-        Returns starting index of specified <parameter>substring</parameter>
-        within <parameter>string</parameter>, or zero if it's not present.
+        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>
@@ -2670,7 +2671,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>text</returnvalue>
        </para>
        <para>
-        Extracts substring matching POSIX regular expression; see
+        Extracts the first substring matching POSIX regular expression; see
         <xref linkend="functions-posix-regexp"/>.
        </para>
        <para>
@@ -2685,7 +2686,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>text</returnvalue>
        </para>
        <para>
-        Extracts substring matching <acronym>SQL</acronym> regular expression;
+        Extracts the first substring matching <acronym>SQL</acronym> regular expression;
         see <xref linkend="functions-similarto-regexp"/>.
        </para>
        <para>
@@ -3163,7 +3164,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>text[]</returnvalue>
        </para>
        <para>
-        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 <parameter>string</parameter>; see
         <xref linkend="functions-posix-regexp"/>.
        </para>
@@ -3182,9 +3183,10 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>setof text[]</returnvalue>
        </para>
        <para>
-        Returns captured substring(s) resulting from matching a POSIX regular
-        expression to the <parameter>string</parameter>; see
-        <xref linkend="functions-posix-regexp"/>.
+        Returns captured substrings resulting from the first match of a
+        POSIX regular expression to the <parameter>string</parameter>,
+        or multiple matches if the <literal>g</literal> flag is used;
+        see <xref linkend="functions-posix-regexp"/>.
        </para>
        <para>
         <literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal>
@@ -3205,8 +3207,10 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>text</returnvalue>
        </para>
        <para>
-        Replaces substring(s) matching a POSIX regular expression; see
-        <xref linkend="functions-posix-regexp"/>.
+        Replaces substrings resulting from the first match of a
+        POSIX regular expression, or multiple substring 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>
@@ -3405,7 +3409,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         <returnvalue>integer</returnvalue>
        </para>
        <para>
-        Returns starting index of specified <parameter>substring</parameter>
+        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
@@ -3905,8 +3909,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         <returnvalue>integer</returnvalue>
        </para>
        <para>
-        Returns starting index of specified <parameter>substring</parameter>
-        within <parameter>bytes</parameter>, or zero if it's not present.
+        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>
@@ -4751,7 +4756,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         <returnvalue>integer</returnvalue>
        </para>
        <para>
-        Returns starting index of specified <parameter>substring</parameter>
+        Returns first starting index of the specified <parameter>substring</parameter>
         within <parameter>bits</parameter>, or zero if it's not present.
        </para>
        <para>
@@ -5373,7 +5378,7 @@ substring('foobar' from '#"o_b#"%' for '#')    <lineannotation>NULL</lineannotat
      <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 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