From: Bruce Momjian <bruce@momjian.us>
To: troy@frericks.us
To: pgsql-docs@lists.postgresql.org
Subject: Re: Manua correction
Date: Thu, 15 Jul 2021 17:36:23 -0400
Message-ID: <20210715213623.GC14027@momjian.us> (raw)
In-Reply-To: <162614304115.701.2392941350859387646@wrigleys.postgresql.org>
References: <162614304115.701.2392941350859387646@wrigleys.postgresql.org>
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 <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[text/x-diff] substring.diff (4.2K, ../20210715213623.GC14027@momjian.us/2-substring.diff)
download | inline diff:diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgmlindex 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, troy@frericks.us, pgsql-docs@lists.postgresql.org
Subject: Re: Manua correction
In-Reply-To: <20210715213623.GC14027@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox