Message-ID: <259a5d19b504d7cb9bb2f76ea384a045bcc525dc.camel@cybertec.at>
Subject: Re: Unnecessary use of .* in examples
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: rmzgrimes@gmail.com, pgsql-docs@lists.postgresql.org
Date: Mon, 01 Feb 2021 09:53:06 +0100
In-Reply-To: <161215841824.14653.8969016349304314299@wrigleys.postgresql.org>
References: <161215841824.14653.8969016349304314299@wrigleys.postgresql.org>
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.36.5 (3.36.5-2.fc32) 
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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