pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedUnnecessary use of .* in examples
4+ messages / 3 participants
[nested] [flat]
Commits from this thread:
2021-02-01 9522085ac9 dae5af6c19 Doc: work a little harder on the initial examples for regex matching.
* Unnecessary use of .* in examples
@ 2021-02-01 05:46 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 4+ messages in thread
From: PG Doc comments form @ 2021-02-01 05:46 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: rmzgrimes@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/13/functions-matching.html
Description:
In the table for the ~ (and friends) operator, every example has a pointless
set of '.*' surrounding the text to be matched. These unnecessary operators
add visual clutter making the examples both harder to read and understand,
and since they're official examples, they teach bad habits.
That is to say, 'thomas' ~ 'thom' is the exact same regex as 'thomas' ~
'.*thom.*' but the first is shorter, easier to read and easier to
understand, and, presumably, faster as well.
Operator
Description
Example(s)
text ~ text → boolean
String matches regular expression, case sensitively
'thomas' ~ '.*thom.*' → t
text ~* text → boolean
String matches regular expression, case insensitively
'thomas' ~* '.*Thom.*' → t
text !~ text → boolean
String does not match regular expression, case sensitively
'thomas' !~ '.*thomas.*' → f
text !~* text → boolean
String does not match regular expression, case insensitively
'thomas' !~* '.*vadim.*' → t
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Unnecessary use of .* in examples
@ 2021-02-01 08:53 Laurenz Albe <laurenz.albe@cybertec.at>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 4+ messages in thread
From: Laurenz Albe @ 2021-02-01 08:53 UTC (permalink / raw)
To: rmzgrimes@gmail.com; pgsql-docs@lists.postgresql.org
On Mon, 2021-02-01 at 05:46 +0000, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/13/functions-matching.html
> Description:
>
> In the table for the ~ (and friends) operator, every example has a pointless
> set of '.*' surrounding the text to be matched. These unnecessary operators
> add visual clutter making the examples both harder to read and understand,
> and since they're official examples, they teach bad habits.
>
> That is to say, 'thomas' ~ 'thom' is the exact same regex as 'thomas' ~
> '.*thom.*' but the first is shorter, easier to read and easier to
> understand, and, presumably, faster as well.
>
> Operator
>
> Description
>
> Example(s)
>
> text ~ text → boolean
>
> String matches regular expression, case sensitively
>
> 'thomas' ~ '.*thom.*' → t
>
> text ~* text → boolean
>
> String matches regular expression, case insensitively
>
> 'thomas' ~* '.*Thom.*' → t
>
> text !~ text → boolean
>
> String does not match regular expression, case sensitively
>
> 'thomas' !~ '.*thomas.*' → f
>
> text !~* text → boolean
>
> String does not match regular expression, case insensitively
>
> 'thomas' !~* '.*vadim.*' → t
I agree that that is comewhat confusing for people who understand
regular expressions. On the other hand, the example should show some
special characters, so that people who don't know regular expressions
understand that this is more than substring matching.
Perhaps 'thomas' ~ '^thom' and so on?
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Unnecessary use of .* in examples
@ 2021-02-01 15:08 Tom Lane <tgl@sss.pgh.pa.us>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 4+ messages in thread
From: Tom Lane @ 2021-02-01 15:08 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: rmzgrimes@gmail.com; pgsql-docs@lists.postgresql.org
Laurenz Albe <laurenz.albe@cybertec.at> writes:
> On Mon, 2021-02-01 at 05:46 +0000, PG Doc comments form wrote:
>> In the table for the ~ (and friends) operator, every example has a pointless
>> set of '.*' surrounding the text to be matched. These unnecessary operators
>> add visual clutter making the examples both harder to read and understand,
>> and since they're official examples, they teach bad habits.
> I agree that that is comewhat confusing for people who understand
> regular expressions. On the other hand, the example should show some
> special characters, so that people who don't know regular expressions
> understand that this is more than substring matching.
> Perhaps 'thomas' ~ '^thom' and so on?
There are examples just a bit further down that include special
characters. I agree with the OP that the useless ".*"s add nothing
except confusion as to the semantics; but I don't think we need these
very first examples to use a lot of bells and whistles.
Maybe what would be better is to have an example with embedded .*
such as 'thomas' ~ 't.*m'.
regards, tom lane
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Unnecessary use of .* in examples
@ 2021-02-02 09:54 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 4+ messages in thread
From: Laurenz Albe @ 2021-02-02 09:54 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: rmzgrimes@gmail.com; pgsql-docs@lists.postgresql.org
On Mon, 2021-02-01 at 10:08 -0500, Tom Lane wrote:
> > On Mon, 2021-02-01 at 05:46 +0000, PG Doc comments form wrote:
> > > In the table for the ~ (and friends) operator, every example has a pointless
> > > set of '.*' surrounding the text to be matched. These unnecessary operators
> > > add visual clutter making the examples both harder to read and understand,
> > > and since they're official examples, they teach bad habits.
>
> > I agree that that is comewhat confusing for people who understand
> > regular expressions. On the other hand, the example should show some
> > special characters, so that people who don't know regular expressions
> > understand that this is more than substring matching.
>
> > Perhaps 'thomas' ~ '^thom' and so on?
>
> There are examples just a bit further down that include special
> characters. I agree with the OP that the useless ".*"s add nothing
> except confusion as to the semantics; but I don't think we need these
> very first examples to use a lot of bells and whistles.
>
> Maybe what would be better is to have an example with embedded .*
> such as 'thomas' ~ 't.*m'.
I agree, and thanks for improving it in
https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=9522085ac917af66dba29939af328ae67300f...
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2021-02-02 09:54 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2021-02-01 05:46 Unnecessary use of .* in examples PG Doc comments form <noreply@postgresql.org>
2021-02-01 08:53 ` Laurenz Albe <laurenz.albe@cybertec.at>
2021-02-01 15:08 ` Tom Lane <tgl@sss.pgh.pa.us>
2021-02-02 09:54 ` Laurenz Albe <laurenz.albe@cybertec.at>
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