Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1m491x-0007ra-Ng for pgsql-docs@arkaria.postgresql.org; Thu, 15 Jul 2021 21:36:29 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1m491w-0005E0-Mv for pgsql-docs@arkaria.postgresql.org; Thu, 15 Jul 2021 21:36:28 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1m491w-0005Ds-Gq for pgsql-docs@lists.postgresql.org; Thu, 15 Jul 2021 21:36:28 +0000 Received: from momjian.us ([72.94.173.45]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1m491t-0001BT-O0 for pgsql-docs@lists.postgresql.org; Thu, 15 Jul 2021 21:36:28 +0000 Received: from bruce by momjian.us with local (Exim 4.92) (envelope-from ) id 1m491r-0006c3-Ls; Thu, 15 Jul 2021 17:36:23 -0400 Date: Thu, 15 Jul 2021 17:36:23 -0400 From: Bruce Momjian To: troy@frericks.us, pgsql-docs@lists.postgresql.org Subject: Re: Manua correction Message-ID: <20210715213623.GC14027@momjian.us> References: <162614304115.701.2392941350859387646@wrigleys.postgresql.org> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="EeQfGwPcQSOJBaQU" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <162614304115.701.2392941350859387646@wrigleys.postgresql.org> User-Agent: Mutt/1.10.1 (2018-07-13) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --EeQfGwPcQSOJBaQU Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit 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 https://momjian.us EDB https://enterprisedb.com If only the physical world exists, free will is an illusion. --EeQfGwPcQSOJBaQU Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="substring.diff" 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) PgPgPgPg text - Extracts substring matching POSIX regular expression; see + Extracts the first substring matching POSIX regular expression; see . @@ -2629,7 +2629,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. @@ -3109,7 +3109,7 @@ repeat('Pg', 4) PgPgPgPg text[] - 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 string; see . @@ -3128,7 +3128,7 @@ repeat('Pg', 4) PgPgPgPg setof text[] - Returns captured substring(s) resulting from matching a POSIX regular + Returns captured substrings resulting from matching a POSIX regular expression to the string; see . @@ -3151,7 +3151,7 @@ repeat('Pg', 4) PgPgPgPg text - Replaces substring(s) matching a POSIX regular expression; see + Replaces substrings matching a POSIX regular expression; see . @@ -3357,7 +3357,7 @@ repeat('Pg', 4) PgPgPgPg integer - Returns starting index of specified substring + Returns first starting index of specified substring within string, or zero if it's not present. (Same as position(substring in string), but note the reversed @@ -3958,7 +3958,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); integer - Returns starting index of specified substring + Returns first starting index of specified substring within bytes, or zero if it's not present. @@ -4885,7 +4885,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three'); integer - Returns starting index of specified substring + Returns first starting index of specified substring within bits, or zero if it's not present. @@ -5511,7 +5511,7 @@ substring('foobar' similar '#"o_b#"%' escape '#') NULLpattern), 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 --EeQfGwPcQSOJBaQU--