Обсуждение: Manua correction
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. Troy. #
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.