Re: substring synopsis section, third argument is optional doc didn't show that - Mailing list pgsql-docs

On Tue, Feb 18, 2025 at 7:06 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Tue, Jan 21, 2025 at 11:29 PM jian he <jian.universality@gmail.com> wrote:
>>
>> in 9.7.2 do you think it's worthwhile changing it to
>>
>> ""
>> As with SIMILAR TO, substring(string, pattern, escape-character)
>> the specified pattern must match the entire data string, or else the
>> function fails and returns null.
>> ""
>> ?
>>
>
> Making reference to any one of the three listed function signatures here doesn't seem to provide value.  If anything
I'dwrite: 
>
> "As with SIMILAR TO, substring matches the specified pattern to the entire data string, returning null otherwise."
>
> I would avoid saying that the function fails in any situation that doesn't produce an actual error.  The transition
of"match everything or returns null" can be bike-shedded though. 
>

thinking about it.
I think the current wording
"As with SIMILAR TO, the specified pattern must match the entire data
string, or else the function fails and returns null"
is fine.

I guess my complaint is that the above sentence is not as explicit as
the 9.7.3 section description.
"
The substring function with two parameters, substring(string from
pattern), provides extraction of a substring that matches a POSIX
regular expression pattern.
It returns null if there is no match, otherwise the first portion of
the text that matched the pattern.
"