From 580f8727ca93b7b9a2ce49746b9cdbcb0a2b4a7e Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 25 Jul 2024 14:51:46 -0400 Subject: [PATCH] Add argument names to the regexp_XXX functions. This change allows these functions to be called using named-argument notation, which can be helpful for readability, particularly for the ones with many arguments. There was considerable debate about exactly which names to use, but in the end we settled on the names already shown in our documentation table 9.10. The citext extension provides citext-aware versions of some of these functions, so add argument names to those too. In passing, fix table 9.10's syntax synopses for regexp_match, which were slightly wrong about which combinations of arguments are allowed. Jian He, reviewed by Dian Fay and others Discussion: https://postgr.es/m/CACJufxG3NFKKsh6x4fRLv8h3V-HvN4W5dA=zNKMxsNcDwOKang@mail.gmail.com --- contrib/citext/Makefile | 1 + contrib/citext/citext--1.6--1.7.sql | 45 +++++++++++++++++++ contrib/citext/citext.control | 2 +- contrib/citext/meson.build | 1 + doc/src/sgml/func.sgml | 26 ++++++----- src/include/catalog/catversion.h | 2 +- src/include/catalog/pg_proc.dat | 67 ++++++++++++++++++++--------- 7 files changed, 112 insertions(+), 32 deletions(-) create mode 100644 contrib/citext/citext--1.6--1.7.sql diff --git a/contrib/citext/Makefile b/contrib/citext/Makefile index 35db6eac8c..b9b3713f53 100644 --- a/contrib/citext/Makefile +++ b/contrib/citext/Makefile @@ -4,6 +4,7 @@ MODULES = citext EXTENSION = citext DATA = citext--1.4.sql \ + citext--1.6--1.7.sql \ citext--1.5--1.6.sql \ citext--1.4--1.5.sql \ citext--1.3--1.4.sql \ diff --git a/contrib/citext/citext--1.6--1.7.sql b/contrib/citext/citext--1.6--1.7.sql new file mode 100644 index 0000000000..d30ce3e5df --- /dev/null +++ b/contrib/citext/citext--1.6--1.7.sql @@ -0,0 +1,45 @@ +/* contrib/citext/citext--1.6--1.7.sql */ + +-- complain if script is sourced in psql, rather than via ALTER EXTENSION +\echo Use "ALTER EXTENSION citext UPDATE TO '1.7'" to load this file. \quit + +-- add function argument names +CREATE OR REPLACE FUNCTION regexp_match(string citext, pattern citext) RETURNS TEXT[] AS $$ + SELECT pg_catalog.regexp_match( $1::pg_catalog.text, $2::pg_catalog.text, 'i' ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; + +CREATE OR REPLACE FUNCTION regexp_match(string citext, pattern citext, flags text) RETURNS TEXT[] AS $$ + SELECT pg_catalog.regexp_match( $1::pg_catalog.text, $2::pg_catalog.text, CASE WHEN pg_catalog.strpos($3, 'c') = 0 THEN $3 || 'i' ELSE $3 END ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; + +CREATE OR REPLACE FUNCTION regexp_matches(string citext, pattern citext) RETURNS SETOF TEXT[] AS $$ + SELECT pg_catalog.regexp_matches( $1::pg_catalog.text, $2::pg_catalog.text, 'i' ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE ROWS 1; + +CREATE OR REPLACE FUNCTION regexp_matches(string citext, pattern citext, flags text) RETURNS SETOF TEXT[] AS $$ + SELECT pg_catalog.regexp_matches( $1::pg_catalog.text, $2::pg_catalog.text, CASE WHEN pg_catalog.strpos($3, 'c') = 0 THEN $3 || 'i' ELSE $3 END ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE ROWS 10; + +CREATE OR REPLACE FUNCTION regexp_replace(string citext, pattern citext, replacement text) returns TEXT AS $$ + SELECT pg_catalog.regexp_replace( $1::pg_catalog.text, $2::pg_catalog.text, $3, 'i'); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; + +CREATE OR REPLACE FUNCTION regexp_replace(string citext, pattern citext, replacement text, flags text) returns TEXT AS $$ + SELECT pg_catalog.regexp_replace( $1::pg_catalog.text, $2::pg_catalog.text, $3, CASE WHEN pg_catalog.strpos($4, 'c') = 0 THEN $4 || 'i' ELSE $4 END); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; + +CREATE OR REPLACE FUNCTION regexp_split_to_array(string citext, pattern citext) RETURNS TEXT[] AS $$ + SELECT pg_catalog.regexp_split_to_array( $1::pg_catalog.text, $2::pg_catalog.text, 'i' ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; + +CREATE OR REPLACE FUNCTION regexp_split_to_array(string citext, pattern citext, flags text) RETURNS TEXT[] AS $$ + SELECT pg_catalog.regexp_split_to_array( $1::pg_catalog.text, $2::pg_catalog.text, CASE WHEN pg_catalog.strpos($3, 'c') = 0 THEN $3 || 'i' ELSE $3 END ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; + +CREATE OR REPLACE FUNCTION regexp_split_to_table(string citext, pattern citext) RETURNS SETOF TEXT AS $$ + SELECT pg_catalog.regexp_split_to_table( $1::pg_catalog.text, $2::pg_catalog.text, 'i' ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; + +CREATE OR REPLACE FUNCTION regexp_split_to_table(string citext, pattern citext, flags text) RETURNS SETOF TEXT AS $$ + SELECT pg_catalog.regexp_split_to_table( $1::pg_catalog.text, $2::pg_catalog.text, CASE WHEN pg_catalog.strpos($3, 'c') = 0 THEN $3 || 'i' ELSE $3 END ); +$$ LANGUAGE SQL IMMUTABLE STRICT PARALLEL SAFE; diff --git a/contrib/citext/citext.control b/contrib/citext/citext.control index ccf445475d..f82265b334 100644 --- a/contrib/citext/citext.control +++ b/contrib/citext/citext.control @@ -1,6 +1,6 @@ # citext extension comment = 'data type for case-insensitive character strings' -default_version = '1.6' +default_version = '1.7' module_pathname = '$libdir/citext' relocatable = true trusted = true diff --git a/contrib/citext/meson.build b/contrib/citext/meson.build index 9770ab3ac6..40cdd0d2f1 100644 --- a/contrib/citext/meson.build +++ b/contrib/citext/meson.build @@ -25,6 +25,7 @@ install_data( 'citext--1.4.sql', 'citext--1.4--1.5.sql', 'citext--1.5--1.6.sql', + 'citext--1.6--1.7.sql', kwargs: contrib_data_args, ) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index fd5699f4d8..b669ab7f97 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -3426,7 +3426,6 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in regexp_replace regexp_replace ( string text, pattern text, replacement text - [, start integer ] [, flags text ] ) text @@ -3445,20 +3444,27 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in regexp_replace ( string text, pattern text, replacement text, - start integer, - N integer - [, flags text ] ) + start integer + [, N integer + [, flags text ] ] ) text Replaces the substring that is the N'th match to the POSIX regular expression pattern, - or all such matches if N is zero; see + or all such matches if N is zero, with the + search beginning at the start'th character + of string. If N is + omitted, it defaults to 1. See . regexp_replace('Thomas', '.', 'X', 3, 2) ThoXas + + + regexp_replace(string=>'hello world', pattern=>'l', replacement=>'XX', start=>1, "N"=>2) + helXXo world @@ -5963,7 +5969,7 @@ regexp_count('ABCABCAXYaxy', 'A.', 1, 'i') 4 regexp_instr('number of your street, town zip, FR', '[^,]+', 1, 2) 23 -regexp_instr('ABCDEFGHI', '(c..)(...)', 1, 1, 0, 'i', 2) +regexp_instr(string=>'ABCDEFGHI', pattern=>'(c..)(...)', start=>1, "N"=>1, endoption=>0, flags=>'i', subexpr=>2) 6 @@ -6109,7 +6115,7 @@ SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab; The regexp_replace function provides substitution of new text for substrings that match POSIX regular expression patterns. It has the syntax - regexp_replace(source, + regexp_replace(string, pattern, replacement , start , N @@ -6118,9 +6124,9 @@ SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab; (Notice that N cannot be specified unless start is, but flags can be given in any case.) - The source string is returned unchanged if + The source string is returned unchanged if there is no match to the pattern. If there is a - match, the source string is returned with the + match, the string is returned with the replacement string substituted for the matching substring. The replacement string can contain \n, where n is 1 @@ -6161,7 +6167,7 @@ regexp_replace('foobarbaz', 'b(..)', 'X\1Y', 'g') fooXarYXazY regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 0, 'i') X PXstgrXSQL fXnctXXn -regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 3, 'i') +regexp_replace(string=>'A PostgreSQL function', pattern=>'a|e|i|o|u', replacement=>'X', start=>1, "N"=>3, flags=>'i') A PostgrXSQL function diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h index 4c88ea1034..2f221b6ad0 100644 --- a/src/include/catalog/catversion.h +++ b/src/include/catalog/catversion.h @@ -57,6 +57,6 @@ */ /* yyyymmddN */ -#define CATALOG_VERSION_NO 202407251 +#define CATALOG_VERSION_NO 202407252 #endif diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat index d14a94b987..06b2f4ba66 100644 --- a/src/include/catalog/pg_proc.dat +++ b/src/include/catalog/pg_proc.dat @@ -3623,105 +3623,132 @@ prosrc => 'replace_text' }, { oid => '2284', descr => 'replace text using regexp', proname => 'regexp_replace', prorettype => 'text', - proargtypes => 'text text text', prosrc => 'textregexreplace_noopt' }, + proargtypes => 'text text text', + proargnames => '{string, pattern, replacement}', + prosrc => 'textregexreplace_noopt' }, { oid => '2285', descr => 'replace text using regexp', proname => 'regexp_replace', prorettype => 'text', - proargtypes => 'text text text text', prosrc => 'textregexreplace' }, + proargtypes => 'text text text text', + proargnames => '{string, pattern, replacement, flags}', + prosrc => 'textregexreplace' }, { oid => '6251', descr => 'replace text using regexp', proname => 'regexp_replace', prorettype => 'text', proargtypes => 'text text text int4 int4 text', + proargnames => '{string, pattern, replacement, start, N, flags}', prosrc => 'textregexreplace_extended' }, { oid => '6252', descr => 'replace text using regexp', proname => 'regexp_replace', prorettype => 'text', proargtypes => 'text text text int4 int4', + proargnames => '{string, pattern, replacement, start, N}', prosrc => 'textregexreplace_extended_no_flags' }, { oid => '6253', descr => 'replace text using regexp', proname => 'regexp_replace', prorettype => 'text', proargtypes => 'text text text int4', + proargnames => '{string, pattern, replacement, start}', prosrc => 'textregexreplace_extended_no_n' }, { oid => '3396', descr => 'find first match for regexp', proname => 'regexp_match', prorettype => '_text', proargtypes => 'text text', - prosrc => 'regexp_match_no_flags' }, + proargnames => '{string, pattern}', prosrc => 'regexp_match_no_flags' }, { oid => '3397', descr => 'find first match for regexp', proname => 'regexp_match', prorettype => '_text', - proargtypes => 'text text text', prosrc => 'regexp_match' }, + proargtypes => 'text text text', proargnames => '{string, pattern, flags}', + prosrc => 'regexp_match' }, { oid => '2763', descr => 'find match(es) for regexp', proname => 'regexp_matches', prorows => '1', proretset => 't', prorettype => '_text', proargtypes => 'text text', - prosrc => 'regexp_matches_no_flags' }, + proargnames => '{string, pattern}', prosrc => 'regexp_matches_no_flags' }, { oid => '2764', descr => 'find match(es) for regexp', proname => 'regexp_matches', prorows => '10', proretset => 't', prorettype => '_text', proargtypes => 'text text text', - prosrc => 'regexp_matches' }, + proargnames => '{string, pattern, flags}', prosrc => 'regexp_matches' }, { oid => '6254', descr => 'count regexp matches', proname => 'regexp_count', prorettype => 'int4', proargtypes => 'text text', - prosrc => 'regexp_count_no_start' }, + proargnames => '{string, pattern}', prosrc => 'regexp_count_no_start' }, { oid => '6255', descr => 'count regexp matches', proname => 'regexp_count', prorettype => 'int4', - proargtypes => 'text text int4', prosrc => 'regexp_count_no_flags' }, + proargtypes => 'text text int4', proargnames => '{string, pattern, start}', + prosrc => 'regexp_count_no_flags' }, { oid => '6256', descr => 'count regexp matches', proname => 'regexp_count', prorettype => 'int4', - proargtypes => 'text text int4 text', prosrc => 'regexp_count' }, + proargtypes => 'text text int4 text', + proargnames => '{string, pattern, start, flags}', prosrc => 'regexp_count' }, { oid => '6257', descr => 'position of regexp match', proname => 'regexp_instr', prorettype => 'int4', proargtypes => 'text text', - prosrc => 'regexp_instr_no_start' }, + proargnames => '{string, pattern}', prosrc => 'regexp_instr_no_start' }, { oid => '6258', descr => 'position of regexp match', proname => 'regexp_instr', prorettype => 'int4', - proargtypes => 'text text int4', prosrc => 'regexp_instr_no_n' }, + proargtypes => 'text text int4', proargnames => '{string, pattern, start}', + prosrc => 'regexp_instr_no_n' }, { oid => '6259', descr => 'position of regexp match', proname => 'regexp_instr', prorettype => 'int4', - proargtypes => 'text text int4 int4', prosrc => 'regexp_instr_no_endoption' }, + proargtypes => 'text text int4 int4', + proargnames => '{string, pattern, start, N}', + prosrc => 'regexp_instr_no_endoption' }, { oid => '6260', descr => 'position of regexp match', proname => 'regexp_instr', prorettype => 'int4', proargtypes => 'text text int4 int4 int4', + proargnames => '{string, pattern, start, N, endoption}', prosrc => 'regexp_instr_no_flags' }, { oid => '6261', descr => 'position of regexp match', proname => 'regexp_instr', prorettype => 'int4', proargtypes => 'text text int4 int4 int4 text', + proargnames => '{string, pattern, start, N, endoption, flags}', prosrc => 'regexp_instr_no_subexpr' }, { oid => '6262', descr => 'position of regexp match', proname => 'regexp_instr', prorettype => 'int4', proargtypes => 'text text int4 int4 int4 text int4', + proargnames => '{string, pattern, start, N, endoption, flags, subexpr}', prosrc => 'regexp_instr' }, { oid => '6263', descr => 'test for regexp match', proname => 'regexp_like', prorettype => 'bool', proargtypes => 'text text', - prosrc => 'regexp_like_no_flags' }, + proargnames => '{string, pattern}', prosrc => 'regexp_like_no_flags' }, { oid => '6264', descr => 'test for regexp match', proname => 'regexp_like', prorettype => 'bool', - proargtypes => 'text text text', prosrc => 'regexp_like' }, + proargtypes => 'text text text', proargnames => '{string, pattern,flags}', + prosrc => 'regexp_like' }, { oid => '6265', descr => 'extract substring that matches regexp', proname => 'regexp_substr', prorettype => 'text', proargtypes => 'text text', - prosrc => 'regexp_substr_no_start' }, + proargnames => '{string, pattern}', prosrc => 'regexp_substr_no_start' }, { oid => '6266', descr => 'extract substring that matches regexp', proname => 'regexp_substr', prorettype => 'text', - proargtypes => 'text text int4', prosrc => 'regexp_substr_no_n' }, + proargtypes => 'text text int4', proargnames => '{string, pattern, start}', + prosrc => 'regexp_substr_no_n' }, { oid => '6267', descr => 'extract substring that matches regexp', proname => 'regexp_substr', prorettype => 'text', - proargtypes => 'text text int4 int4', prosrc => 'regexp_substr_no_flags' }, + proargtypes => 'text text int4 int4', + proargnames => '{string, pattern, start, N}', + prosrc => 'regexp_substr_no_flags' }, { oid => '6268', descr => 'extract substring that matches regexp', proname => 'regexp_substr', prorettype => 'text', proargtypes => 'text text int4 int4 text', + proargnames => '{string, pattern, start, N, flags}', prosrc => 'regexp_substr_no_subexpr' }, { oid => '6269', descr => 'extract substring that matches regexp', proname => 'regexp_substr', prorettype => 'text', - proargtypes => 'text text int4 int4 text int4', prosrc => 'regexp_substr' }, + proargtypes => 'text text int4 int4 text int4', + proargnames => '{string, pattern, start, N, flags, subexpr}', + prosrc => 'regexp_substr' }, { oid => '2088', descr => 'split string by field_sep and return field_num', proname => 'split_part', prorettype => 'text', proargtypes => 'text text int4', prosrc => 'split_part' }, { oid => '2765', descr => 'split string by pattern', proname => 'regexp_split_to_table', prorows => '1000', proretset => 't', prorettype => 'text', proargtypes => 'text text', + proargnames => '{string, pattern}', prosrc => 'regexp_split_to_table_no_flags' }, { oid => '2766', descr => 'split string by pattern', proname => 'regexp_split_to_table', prorows => '1000', proretset => 't', prorettype => 'text', proargtypes => 'text text text', + proargnames => '{string, pattern, flags}', prosrc => 'regexp_split_to_table' }, { oid => '2767', descr => 'split string by pattern', proname => 'regexp_split_to_array', prorettype => '_text', - proargtypes => 'text text', prosrc => 'regexp_split_to_array_no_flags' }, + proargtypes => 'text text', proargnames => '{string, pattern}', + prosrc => 'regexp_split_to_array_no_flags' }, { oid => '2768', descr => 'split string by pattern', proname => 'regexp_split_to_array', prorettype => '_text', - proargtypes => 'text text text', prosrc => 'regexp_split_to_array' }, + proargtypes => 'text text text', proargnames => '{string, pattern, flags}', + prosrc => 'regexp_split_to_array' }, { oid => '6330', descr => 'convert int4 number to binary', proname => 'to_bin', prorettype => 'text', proargtypes => 'int4', prosrc => 'to_bin32' },