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

7 files changed, 112 insertions, 32 deletions

diff --git a/contrib/citext/Makefile b/contrib/citext/Makefile
index 35db6eac8c4..b9b3713f537 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 00000000000..d30ce3e5dfe
--- /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 ccf445475d0..f82265b3347 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 9770ab3ac64..40cdd0d2f18 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 fd5699f4d85..b669ab7f977 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
          <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 4c88ea1034f..2f221b6ad0a 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 d14a94b9873..06b2f4ba66c 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' },