On Tue, Jul 13, 2021 at 02:24:01AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/13/functions-string.html
> Description:
>
> Hopefully the referrer page was kept. I'm referring to the string functions
> page that reads...
> ==
> position ( substring text IN string text ) → integer
> Returns starting index of specified substring within string, or zero if it's
> not present.
> position('om' in 'Thomas') → 3
> ==
>
> should describe the situation where multiple occurrences of substring are in
> the string text... might read...
>
> Returns starting index of the first occurrence of the specified substring
> within string, or zero if it's not present.
Interesting. I see several cases where our docs are not clear we
process only the first match:
SELECT substring ('abc abd' FROM 'b.');
substring
-----------
bc
SELECT regexp_match('abc abd', 'b.');
regexp_match
--------------
{bc}
SELECT regexp_replace ('abc abf', 'b.', 'dd');
regexp_replace
----------------
add abf
SELECT strpos('abcb', 'b');
strpos
--------
2
SELECT position('a' IN 'abca');
position
----------
1
The attached patch improves these. I can backpatch this were
appropriate.
--
Bruce Momjian <br...@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6388385edc..4c8407148b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2610,7 +2610,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>
@@ -2629,7 +2629,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"/>. The first form has
been specified since SQL:2003; the second form was only in SQL:1999
and should be considered obsolete.
@@ -3109,7 +3109,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 substring resulting from the first match of a POSIX
regular expression to the <parameter>string</parameter>; see
<xref linkend="functions-posix-regexp"/>.
</para>
@@ -3128,7 +3128,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>setof text[]</returnvalue>
</para>
<para>
- Returns captured substring(s) resulting from matching a POSIX regular
+ Returns captured substrings resulting from matching a POSIX regular
expression to the <parameter>string</parameter>; see
<xref linkend="functions-posix-regexp"/>.
</para>
@@ -3151,7 +3151,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>text</returnvalue>
</para>
<para>
- Replaces substring(s) matching a POSIX regular expression; see
+ Replaces substrings matching a POSIX regular expression; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
@@ -3357,7 +3357,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 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
@@ -3958,7 +3958,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 specified <parameter>substring</parameter>
within <parameter>bytes</parameter>, or zero if it's not present.
</para>
<para>
@@ -4885,7 +4885,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 specified <parameter>substring</parameter>
within <parameter>bits</parameter>, or zero if it's not present.
</para>
<para>
@@ -5511,7 +5511,7 @@ substring('foobar' similar '#"o_b#"%' escape '#') <lineannotation>NULL</linea
<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
