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

diff --git a/contrib/citext/Makefile b/contrib/citext/Makefile
index 35db6eac8c44829c4f9eeb537dd62d01a649ef7d..b9b3713f537c490e072cda7a54f87162fdb6ecca 100644 (file)
--- 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 (file)
index 0000000..d30ce3e
--- /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 ccf445475d020b3a948311d5f66e5105f6c4c4a8..f82265b3347a8a1447f511ddab043593ae95cad3 100644 (file)
--- 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 9770ab3ac64647013bac2c7a4e2d476a9f869ebc..40cdd0d2f186b8d32b7b8a8317881ca58f3abf44 100644 (file)
--- 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 fd5699f4d8582405179834becb0fcb447f44d0a7..b669ab7f97765ea3a3259813482cae7f10d3ef9d 100644 (file)
--- 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
          <primary>regexp_replace</primary>
         </indexterm>
         <function>regexp_replace</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type>
-         [, <parameter>start</parameter> <type>integer</type> ]
          [, <parameter>flags</parameter> <type>text</type> ] )
         <returnvalue>text</returnvalue>
        </para>
@@ -3445,20 +3444,27 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <function>regexp_replace</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type>,
-         <parameter>start</parameter> <type>integer</type>,
-         <parameter>N</parameter> <type>integer</type>
-         [, <parameter>flags</parameter> <type>text</type> ] )
+         <parameter>start</parameter> <type>integer</type>
+         [, <parameter>N</parameter> <type>integer</type>
+         [, <parameter>flags</parameter> <type>text</type> ] ] )
         <returnvalue>text</returnvalue>
        </para>
        <para>
         Replaces the substring that is the <parameter>N</parameter>'th
         match to the POSIX regular expression <parameter>pattern</parameter>,
-        or all such matches if <parameter>N</parameter> is zero; see
+        or all such matches if <parameter>N</parameter> is zero, with the
+        search beginning at the <parameter>start</parameter>'th character
+        of <parameter>string</parameter>.  If <parameter>N</parameter> is
+        omitted, it defaults to 1.  See
         <xref linkend="functions-posix-regexp"/>.
        </para>
        <para>
         <literal>regexp_replace('Thomas', '.', 'X', 3, 2)</literal>
         <returnvalue>ThoXas</returnvalue>
+       </para>
+       <para>
+        <literal>regexp_replace(string=>'hello world', pattern=>'l', replacement=>'XX', start=>1, "N"=>2)</literal>
+        <returnvalue>helXXo world</returnvalue>
        </para></entry>
       </row>
 
@@ -5963,7 +5969,7 @@ regexp_count('ABCABCAXYaxy', 'A.', 1, 'i')  <lineannotation>4</lineannotation>
 <programlisting>
 regexp_instr('number of your street, town zip, FR', '[^,]+', 1, 2)
                                    <lineannotation>23</lineannotation>
-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)
                                    <lineannotation>6</lineannotation>
 </programlisting>
     </para>
@@ -6109,7 +6115,7 @@ SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
      The <function>regexp_replace</function> function provides substitution of
      new text for substrings that match POSIX regular expression patterns.
      It has the syntax
-     <function>regexp_replace</function>(<replaceable>source</replaceable>,
+     <function>regexp_replace</function>(<replaceable>string</replaceable>,
      <replaceable>pattern</replaceable>, <replaceable>replacement</replaceable>
      <optional>, <replaceable>start</replaceable>
      <optional>, <replaceable>N</replaceable>
@@ -6118,9 +6124,9 @@ SELECT col1, (SELECT regexp_matches(col2, '(bar)(beque)')) FROM tab;
      (Notice that <replaceable>N</replaceable> cannot be specified
      unless <replaceable>start</replaceable> is,
      but <replaceable>flags</replaceable> can be given in any case.)
-     The <replaceable>source</replaceable> string is returned unchanged if
+     The source <replaceable>string</replaceable> is returned unchanged if
      there is no match to the <replaceable>pattern</replaceable>.  If there is a
-     match, the <replaceable>source</replaceable> string is returned with the
+     match, the <replaceable>string</replaceable> is returned with the
      <replaceable>replacement</replaceable> string substituted for the matching
      substring.  The <replaceable>replacement</replaceable> string can contain
      <literal>\</literal><replaceable>n</replaceable>, where <replaceable>n</replaceable> is 1
@@ -6161,7 +6167,7 @@ regexp_replace('foobarbaz', 'b(..)', 'X\1Y', 'g')
                                    <lineannotation>fooXarYXazY</lineannotation>
 regexp_replace('A PostgreSQL function', 'a|e|i|o|u', 'X', 1, 0, 'i')
                                    <lineannotation>X PXstgrXSQL fXnctXXn</lineannotation>
-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')
                                    <lineannotation>A PostgrXSQL function</lineannotation>
 </programlisting>
    </para>

diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h
index 4c88ea1034f62bfe8e4e64e2a8afadbf2e447078..2f221b6ad0a49076238a5a338b628684a43e3365 100644 (file)
--- 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 d14a94b9873467a69d07ce96774b285536a97e44..06b2f4ba66c7569527225e0d2878676485946be3 100644 (file)
--- 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' },