Hi,
on a regular basis I remember a builtin function's name, or can figure it out
using \df etc, but can't remember the argument order. A typical example is
regexp_*, where I never remember whether the pattern or the input string comes
first.
Unfortunatly \df does not really help with that:
=# \df regexp_split_to_table
┌────────────┬───────────────────────┬──────────────────┬─────────────────────┬──────┐
│ Schema │ Name │ Result data type │ Argument data types │ Type │
├────────────┼───────────────────────┼──────────────────┼─────────────────────┼──────┤
│ pg_catalog │ regexp_split_to_table │ SETOF text │ text, text │ func │
│ pg_catalog │ regexp_split_to_table │ SETOF text │ text, text, text │ func │
└────────────┴───────────────────────┴──────────────────┴─────────────────────┴──────┘
If the parameters were named however, it'd be clear:
=# CREATE OR REPLACE FUNCTION pg_catalog.regexp_split_to_table(string text, pattern text)
RETURNS SETOF text
LANGUAGE internal
IMMUTABLE PARALLEL SAFE STRICT
AS $function$regexp_split_to_table_no_flags$function$
=# \df regexp_split_to_table
┌────────────┬───────────────────────┬──────────────────┬──────────────────────────┬──────┐
│ Schema │ Name │ Result data type │ Argument data types │ Type │
├────────────┼───────────────────────┼──────────────────┼──────────────────────────┼──────┤
│ pg_catalog │ regexp_split_to_table │ SETOF text │ string text, pattern text │ func │
│ pg_catalog │ regexp_split_to_table │ SETOF text │ text, text, text │ func │
└────────────┴───────────────────────┴──────────────────┴──────────────────────────┴──────┘
(I intentionally left the three parameter version unchanged, to show the difference)
In the docs we already name the parameters using SQL like syntax, see [1]. How
about we actually do so for at least the more common / complicated functions?
It may not be worth adding operator names for every comparator, but for
functions we expect to be used directly it seems worthwhile?
It sure would be some initial work, but it seems doable.
Comments?
A mildly related note: It's a bit annoying that the "Pattern Matching"
documentation page [2] does not appear to contain a link to the documentation
about the individual pattern matching functions [1]. Am I missing something?
Greetings,
Andres Freund
[1] https://www.postgresql.org/docs/current/functions-string.html#FUNCTIONS-STRING-OTHER
[2] https://www.postgresql.org/docs/current/functions-matching.html
