Manua correction

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.

Bruce Momjian <bruce@momjian.us> writes:

Interesting. I see several cases where our docs are not clear we
process only the first match:

At least two of these changes are flat out wrong. The places
that explicitly mention "substring(s)" are not doing so because
we failed to think about what that meant.

regards, tom lane

On Thu, Jul 15, 2021 at 11:12:38PM -0400, Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

Interesting. I see several cases where our docs are not clear we
process only the first match:

At least two of these changes are flat out wrong. The places
that explicitly mention "substring(s)" are not doing so because
we failed to think about what that meant.

I really don't understand the use of "(s)" except in place where we are
really trying to point out the idea of one or multiple, and I don't see
that being significant in these cases --- can you clarify?

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

If only the physical world exists, free will is an illusion.

Bruce Momjian <bruce@momjian.us> writes:

On Thu, Jul 15, 2021 at 11:12:38PM -0400, Tom Lane wrote:

At least two of these changes are flat out wrong. The places
that explicitly mention "substring(s)" are not doing so because
we failed to think about what that meant.

I really don't understand the use of "(s)" except in place where we are
really trying to point out the idea of one or multiple, and I don't see
that being significant in these cases --- can you clarify?

See the example given for regexp_match:

regression=# select regexp_match('foobarbequebaz', '(bar)(beque)');
regexp_match
--------------
{bar,beque}
(1 row)

There's more than one parenthesized subpattern, so you get more than
one substring in the result. So I think that change is flat out
wrong.

The places where you changed "substring(s)" to "substrings" are maybe
not flat wrong, but I don't think they're improving the text either.
IIRC, in most of them you get one match if you didn't use the 'g'
flag, but possibly multiple matches if you did, and the "substring(s)"
wording is meant to allude to that without taking the space to spell
it out explicitly.

regards, tom lane

On Tue, Jul 20, 2021 at 11:03:09AM -0400, Tom Lane wrote:

Bruce Momjian <bruce@momjian.us> writes:

I really don't understand the use of "(s)" except in place where we are
really trying to point out the idea of one or multiple, and I don't see
that being significant in these cases --- can you clarify?

See the example given for regexp_match:

regression=# select regexp_match('foobarbequebaz', '(bar)(beque)');
regexp_match
--------------
{bar,beque}
(1 row)

There's more than one parenthesized subpattern, so you get more than
one substring in the result. So I think that change is flat out
wrong.

The places where you changed "substring(s)" to "substrings" are maybe
not flat wrong, but I don't think they're improving the text either.
IIRC, in most of them you get one match if you didn't use the 'g'
flag, but possibly multiple matches if you did, and the "substring(s)"
wording is meant to allude to that without taking the space to spell
it out explicitly.

I see what you mean --- there can be multiple capture groups, and
multiple match processing if 'g' is used. I think the text using "(s)"
is too complex, so I spelled out the use 'g' and clarified the case of
multiple groups in a single regex.

Updated patch attached, and I used a larger line context around the
changes to clarify what was being modified.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

If only the physical world exists, free will is an illusion.

On Tue, Jul 20, 2021 at 04:06:17PM -0400, Bruce Momjian wrote:

On Tue, Jul 20, 2021 at 11:03:09AM -0400, Tom Lane wrote:

The places where you changed "substring(s)" to "substrings" are maybe
not flat wrong, but I don't think they're improving the text either.
IIRC, in most of them you get one match if you didn't use the 'g'
flag, but possibly multiple matches if you did, and the "substring(s)"
wording is meant to allude to that without taking the space to spell
it out explicitly.

I see what you mean --- there can be multiple capture groups, and
multiple match processing if 'g' is used. I think the text using "(s)"
is too complex, so I spelled out the use 'g' and clarified the case of
multiple groups in a single regex.

Updated patch attached, and I used a larger line context around the
changes to clarify what was being modified.

Patch applied back to PG 13 --- before that, the text supplied as much
more minimal.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

If only the physical world exists, free will is an illusion.