Mime-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset=UTF-8
Date: Sun, 07 Jan 2024 19:44:55 -0500
Message-Id: <CY8WQVZ0PK1B.19QRO61WBALCP@nmfay.com>
To: "jian he" <jian.universality@gmail.com>, "Jim Nasby"
 <jim.nasby@gmail.com>
Cc: "Peter Eisentraut" <peter@eisentraut.org>, "PostgreSQL Hackers"
 <pgsql-hackers@lists.postgresql.org>
Subject: Re: add function argument names to regex* functions.
From: "Dian Fay" <di@nmfay.com>
References: <CACJufxG3NFKKsh6x4fRLv8h3V-HvN4W5dA=zNKMxsNcDwOKang@mail.gmail.com> <b550243f-1bd2-4119-82e9-0f0abccc6434@eisentraut.org> <CACJufxHeyc34PMx6OnWb-xoaMtj1Yoax1rM+71zkwCynvmVwdg@mail.gmail.com> <CY3KI01TXYMD.3Q41WQ6U0NFEO@nmfay.com> <0eb3a5d7-75d8-4da5-9c88-a93deccdaa03@gmail.com> <CY5G4TAMVX32.23TH6LFF93ATZ@nmfay.com> <75129a34-14da-48aa-9906-42062fe78664@gmail.com> <CACJufxHBx+AHGVJocDSD-PbX0z32vJR9eEUhB+vsJHbjwnXNcg@mail.gmail.com>
In-Reply-To: <CACJufxHBx+AHGVJocDSD-PbX0z32vJR9eEUhB+vsJHbjwnXNcg@mail.gmail.com>
Archived-At: <https://www.postgresql.org/message-id/CY8WQVZ0PK1B.19QRO61WBALCP%40nmfay.com>
Precedence: bulk

On Thu Jan 4, 2024 at 2:03 AM EST, jian he wrote:
> On Thu, Jan 4, 2024 at 7:26=E2=80=AFAM Jim Nasby <jim.nasby@gmail.com> wr=
ote:
> >
> > On 1/3/24 5:05 PM, Dian Fay wrote:
> >
> > Another possibility is `index`, which is relatively short and not a
> > reserved keyword ^1. `position` is not as precise but would avoid the
> > conceptual overloading of ordinary indices.
> >
> > I'm not a fan of "index" since that leaves the question of
> > whether it's 0 or 1 based. "Position" is a bit better, but I think
> > Jian's suggestion of "occurance" is best.
> >
> > We do have precedent for one-based `index` in Postgres: array types are
> > 1-indexed by default! "Occurrence" removes that ambiguity but it's long
> > and easy to misspell (I looked it up after typing it just now and it
> > _still_ feels off).
> >
> > How's "instance"?
> >
> > Presumably someone referencing arguments by name would have just looked=
 up the names via \df or whatever, so presumably misspelling wouldn't be a =
big issue. But I think "instance" is OK as well.
> >
> > --
> > Jim Nasby, Data Architect, Austin TX
>
> regexp_instr: It has the syntax regexp_instr(string, pattern [, start
> [, N [, endoption [, flags [, subexpr ]]]]])
> oracle:
> REGEXP_INSTR (source_char, pattern,  [, position [, occurrence [,
> return_opt  [, match_param  [, subexpr ]]]]] )
>
> "string" and "source_char" are almost the same descriptive, so maybe
> there is no need to change.
> "start" is better than "position", imho.
> "return_opt" is better than "endoption", (maybe we need change, for
> now I didn't)
> "flags" cannot be changed to "match_param", given it quite everywhere
> in functions-matching.html.
>
> similarly for function regexp_replace, oracle using "repplace_string",
> we use "replacement"(mentioned in the doc).
> so I don't think we need to change to "repplace_string".
>
> Based on how people google[0], I think `occurrence` is ok, even though
> it's verbose.
> to change from `N` to `occurrence`, we also need to change the doc,
> that is why this patch is more larger.
>
>
> [0]: https://www.google.com/search?q=3Dregex+nth+match&oq=3Dregex+nth+mat=
ch&gs_lcrp=3DEgZjaHJvbWUyBggAEEUYOTIGCAEQRRg8MgYIAhBFGDzSAQc2MThqMGo5qAIAsA=
IA&sourceid=3Dchrome&ie=3DUTF-8

The `regexp_replace` summary in table 9.10 is mismatched and still
specifies the first parameter name as `string` instead of `source`.
Since all the other functions use `string`, should `regexp_replace` do
the same or is this a case where an established "standard" diverges?

I noticed the original documentation for some of these functions is
rather disorganized; summaries explain `occurrence` without explaining
the prior `start` parameter, and detailed documentation in 9.7 is
usually a single paragraph per function running pell-mell through ifs
and buts without section headings, so entries in table 9.10 have to
reference the entire section 9.7.3 instead of their specific functions.
It's out of scope here, but should I bring this up on pgsql-docs?