Skip to content

Commit 35bccca

Browse files
author
Commitfest Bot
committed
[CF 5524] v5 - add function argument name to substring and substr
This branch was automatically generated by a robot using patches from an email thread registered at: https://commitfest.postgresql.org/patch/5524 The branch will be overwritten each time a new patch version is posted to the thread, and also periodically to check for bitrot caused by changes on the master branch. Patch(es): https://www.postgresql.org/message-id/CAKFQuwZU=eY0F6jE4ekuPs5FMqNr2e-mJ=MTuaZTeDG+Xti1=g@mail.gmail.com Author(s): Jian He
2 parents 43da394 + 37f908b commit 35bccca

File tree

3 files changed

+135
-25
lines changed

3 files changed

+135
-25
lines changed

‎doc/src/sgml/func.sgml

Lines changed: 121 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -2885,7 +2885,8 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in
28852885
</para>
28862886
<para>
28872887
Extracts the first substring matching POSIX regular expression; see
2888-
<xref linkend="functions-posix-regexp"/>.
2888+
<xref linkend="functions-posix-regexp"/>. (Same as
2889+
<literal>substring(string text, pattern text)</literal>.)
28892890
</para>
28902891
<para>
28912892
<literal>substring('Thomas' from '...$')</literal>
@@ -2898,19 +2899,18 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in
28982899
<function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>SIMILAR</literal> <parameter>pattern</parameter> <type>text</type> <literal>ESCAPE</literal> <parameter>escape</parameter> <type>text</type> )
28992900
<returnvalue>text</returnvalue>
29002901
</para>
2901-
<para role="func_signature">
2902-
<function>substring</function> ( <parameter>string</parameter> <type>text</type> <literal>FROM</literal> <parameter>pattern</parameter> <type>text</type> <literal>FOR</literal> <parameter>escape</parameter> <type>text</type> )
2903-
<returnvalue>text</returnvalue>
2904-
</para>
29052902
<para>
29062903
Extracts the first substring matching <acronym>SQL</acronym> regular expression;
2907-
see <xref linkend="functions-similarto-regexp"/>. The first form has
2908-
been specified since SQL:2003; the second form was only in SQL:1999
2909-
and should be considered obsolete.
2904+
see <xref linkend="functions-similarto-regexp"/>. (Same as
2905+
<literal>substring(string text, pattern text, escape text)</literal>.)
29102906
</para>
29112907
<para>
29122908
<literal>substring('Thomas' similar '%#"o_a#"_' escape '#')</literal>
29132909
<returnvalue>oma</returnvalue>
2910+
</para>
2911+
<para>
2912+
Obsolescence note: SQL:1999 introduced this function with <literal>FROM</literal>
2913+
and <literal>FOR</literal> as the keywords but switched to this in SQL:2003.
29142914
</para></entry>
29152915
</row>
29162916

@@ -3806,6 +3806,60 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in
38063806
</para></entry>
38073807
</row>
38083808

3809+
3810+
<row>
3811+
<entry role="func_table_entry"><para role="func_signature">
3812+
<function>substring</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> )
3813+
<returnvalue>text</returnvalue>
3814+
</para>
3815+
<para>
3816+
Extracts the first substring matching POSIX regular expression; see
3817+
<xref linkend="functions-posix-regexp"/>. (Same as
3818+
<literal>substring(string text FROM pattern text)</literal>.)
3819+
</para>
3820+
<para>
3821+
<literal>substring('Thomas', '...$')</literal>
3822+
<returnvalue>mas</returnvalue>
3823+
</para></entry>
3824+
</row>
3825+
3826+
<row>
3827+
<entry role="func_table_entry"><para role="func_signature">
3828+
<function>substring</function> ( <parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>escape </parameter> <type>text</type>)
3829+
<returnvalue>text</returnvalue>
3830+
</para>
3831+
<para>
3832+
Extracts the first substring matching <acronym>SQL</acronym> regular expression;
3833+
see <xref linkend="functions-similarto-regexp"/>. (Same as
3834+
<literal>substring(string text SIMILAR pattern text ESCAPE escape text)</literal>.)
3835+
</para>
3836+
<para>
3837+
<literal>substring('Thomas', '%#"o_a#"_', '#')</literal>
3838+
<returnvalue>oma</returnvalue>
3839+
</para></entry>
3840+
</row>
3841+
3842+
<row>
3843+
<entry role="func_table_entry"><para role="func_signature">
3844+
<indexterm>
3845+
<primary>substring</primary>
3846+
</indexterm>
3847+
<function>substring</function> ( <parameter>string</parameter> <type>text</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
3848+
<returnvalue>text</returnvalue>
3849+
</para>
3850+
<para>
3851+
Extracts the substring of <parameter>string</parameter> starting at
3852+
the <parameter>start</parameter>'th character,
3853+
and stopping after <parameter>count</parameter> characters if that is
3854+
specified.
3855+
</para>
3856+
3857+
<para>
3858+
<literal>substring('Thomas', 2, 3)</literal>
3859+
<returnvalue>hom</returnvalue>
3860+
</para></entry>
3861+
</row>
3862+
38093863
<row>
38103864
<entry role="func_table_entry"><para role="func_signature">
38113865
<indexterm>
@@ -4859,6 +4913,27 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
48594913
<returnvalue>\x5678</returnvalue>
48604914
</para></entry>
48614915
</row>
4916+
4917+
<row>
4918+
<entry role="func_table_entry"><para role="func_signature">
4919+
<indexterm>
4920+
<primary>substring</primary>
4921+
</indexterm>
4922+
<function>substring</function> ( <parameter>bytes</parameter> <type>bytea</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
4923+
<returnvalue>bytea</returnvalue>
4924+
</para>
4925+
<para>
4926+
Extracts the substring of <parameter>bytes</parameter> starting at
4927+
the <parameter>start</parameter>'th byte,
4928+
and stopping after <parameter>count</parameter> bytes if that is
4929+
specified.
4930+
</para>
4931+
<para>
4932+
<literal>substring('\x1234567890'::bytea, 3, 2)</literal>
4933+
<returnvalue>\x5678</returnvalue>
4934+
</para></entry>
4935+
</row>
4936+
48624937
</tbody>
48634938
</tgroup>
48644939
</table>
@@ -5361,6 +5436,26 @@ cast(-1234 as bytea) <lineannotation>\xfffffb2e</lineannotation>
53615436
</para></entry>
53625437
</row>
53635438

5439+
<row>
5440+
<entry role="func_table_entry"><para role="func_signature">
5441+
<indexterm>
5442+
<primary>substring</primary>
5443+
</indexterm>
5444+
<function>substring</function> ( <parameter>bits</parameter> <type>bit</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
5445+
<returnvalue>bit</returnvalue>
5446+
</para>
5447+
<para>
5448+
Extracts the substring of <parameter>bits</parameter> starting at
5449+
the <parameter>start</parameter>'th bit,
5450+
and stopping after <parameter>count</parameter> bits if that is
5451+
specified.
5452+
</para>
5453+
<para>
5454+
<literal>substring(B'110010111111', 3, 2)</literal>
5455+
<returnvalue>00</returnvalue>
5456+
</para></entry>
5457+
</row>
5458+
53645459
<row>
53655460
<entry role="func_table_entry"><para role="func_signature">
53665461
<indexterm>
@@ -5548,8 +5643,8 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
55485643
</indexterm>
55495644

55505645
<synopsis>
5551-
<replaceable>string</replaceable> LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
5552-
<replaceable>string</replaceable> NOT LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
5646+
<replaceable>string</replaceable> LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape</replaceable></optional>
5647+
<replaceable>string</replaceable> NOT LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape</replaceable></optional>
55535648
</synopsis>
55545649

55555650
<para>
@@ -5721,8 +5816,8 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
57215816
</indexterm>
57225817

57235818
<synopsis>
5724-
<replaceable>string</replaceable> SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
5725-
<replaceable>string</replaceable> NOT SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
5819+
<replaceable>string</replaceable> SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape</replaceable></optional>
5820+
<replaceable>string</replaceable> NOT SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape</replaceable></optional>
57265821
</synopsis>
57275822

57285823
<para>
@@ -5856,15 +5951,11 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
58565951
regular expression pattern. The function can be written according
58575952
to standard SQL syntax:
58585953
<synopsis>
5859-
substring(<replaceable>string</replaceable> similar <replaceable>pattern</replaceable> escape <replaceable>escape-character</replaceable>)
5954+
substring(<replaceable>string</replaceable> SIMILAR <replaceable>pattern</replaceable> ESCAPE <replaceable>escape</replaceable>)
58605955
</synopsis>
5861-
or using the now obsolete SQL:1999 syntax:
5956+
It can also written as a plain three-argument function:
58625957
<synopsis>
5863-
substring(<replaceable>string</replaceable> from <replaceable>pattern</replaceable> for <replaceable>escape-character</replaceable>)
5864-
</synopsis>
5865-
or as a plain three-argument function:
5866-
<synopsis>
5867-
substring(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>, <replaceable>escape-character</replaceable>)
5958+
substring(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>, <replaceable>escape</replaceable>)
58685959
</synopsis>
58695960
As with <literal>SIMILAR TO</literal>, the
58705961
specified pattern must match the entire data string, or else the
@@ -6068,11 +6159,17 @@ substring('foobar' similar '#"o_b#"%' escape '#') <lineannotation>NULL</linea
60686159
</para>
60696160

60706161
<para>
6071-
The <function>substring</function> function with two parameters,
6072-
<function>substring(<replaceable>string</replaceable> from
6073-
<replaceable>pattern</replaceable>)</function>, provides extraction of a
6074-
substring
6075-
that matches a POSIX regular expression pattern. It returns null if
6162+
The <function>substring</function> function with two parameters provides extraction of a
6163+
substring that matches a POSIX regular expression pattern.
6164+
The function can be written according to standard SQL syntax:
6165+
<synopsis>
6166+
substring(<replaceable>string</replaceable> FROM <replaceable>pattern</replaceable>)
6167+
</synopsis>
6168+
It can also written as a plain two-argument function:
6169+
<synopsis>
6170+
substring(<replaceable>string</replaceable>, <replaceable>pattern</replaceable>)
6171+
</synopsis>
6172+
It returns null if
60766173
there is no match, otherwise the first portion of the text that matched the
60776174
pattern. But if the pattern contains any parentheses, the portion
60786175
of the text that matched the first parenthesized subexpression (the

‎src/backend/catalog/system_functions.sql

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ CREATE OR REPLACE FUNCTION rpad(text, integer)
4242
IMMUTABLE PARALLEL SAFE STRICT COST 1
4343
RETURN rpad($1, $2, ' ');
4444

45-
CREATE OR REPLACE FUNCTION "substring"(text, text, text)
45+
CREATE OR REPLACE FUNCTION "substring"(string text, pattern text, escape text)
4646
RETURNS text
4747
LANGUAGE sql
4848
IMMUTABLE PARALLEL SAFE STRICT COST 1

‎src/include/catalog/pg_proc.dat

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3705,6 +3705,7 @@
37053705
prosrc => 'rtrim' },
37063706
{ oid => '877', descr => 'extract portion of string',
37073707
proname => 'substr', prorettype => 'text', proargtypes => 'text int4 int4',
3708+
proargnames => '{string, start, count}',
37083709
prosrc => 'text_substr' },
37093710
{ oid => '878', descr => 'map a set of characters appearing in string',
37103711
proname => 'translate', prorettype => 'text', proargtypes => 'text text text',
@@ -3723,6 +3724,7 @@
37233724
prosrc => 'rtrim1' },
37243725
{ oid => '883', descr => 'extract portion of string',
37253726
proname => 'substr', prorettype => 'text', proargtypes => 'text int4',
3727+
proargnames => '{string, start}',
37263728
prosrc => 'text_substr_no_len' },
37273729
{ oid => '884', descr => 'trim selected characters from both ends of string',
37283730
proname => 'btrim', prorettype => 'text', proargtypes => 'text text',
@@ -3733,9 +3735,11 @@
37333735

37343736
{ oid => '936', descr => 'extract portion of string',
37353737
proname => 'substring', prorettype => 'text', proargtypes => 'text int4 int4',
3738+
proargnames => '{string, start, count}',
37363739
prosrc => 'text_substr' },
37373740
{ oid => '937', descr => 'extract portion of string',
37383741
proname => 'substring', prorettype => 'text', proargtypes => 'text int4',
3742+
proargnames => '{string, start}',
37393743
prosrc => 'text_substr_no_len' },
37403744
{ oid => '2087',
37413745
descr => 'replace all occurrences in string of old_substr with new_substr',
@@ -4153,6 +4157,7 @@
41534157
prosrc => 'bitcat' },
41544158
{ oid => '1680', descr => 'extract portion of bitstring',
41554159
proname => 'substring', prorettype => 'bit', proargtypes => 'bit int4 int4',
4160+
proargnames => '{bits, start, count}',
41564161
prosrc => 'bitsubstr' },
41574162
{ oid => '1681', descr => 'bitstring length',
41584163
proname => 'length', prorettype => 'int4', proargtypes => 'bit',
@@ -4182,6 +4187,7 @@
41824187
prosrc => 'bitposition' },
41834188
{ oid => '1699', descr => 'extract portion of bitstring',
41844189
proname => 'substring', prorettype => 'bit', proargtypes => 'bit int4',
4190+
proargnames => '{bits, start}',
41854191
prosrc => 'bitsubstr_no_len' },
41864192

41874193
{ oid => '3030', descr => 'substitute portion of bitstring',
@@ -6279,15 +6285,19 @@
62796285
prosrc => 'byteacat' },
62806286
{ oid => '2012', descr => 'extract portion of string',
62816287
proname => 'substring', prorettype => 'bytea',
6288+
proargnames => '{bytes, start, count}',
62826289
proargtypes => 'bytea int4 int4', prosrc => 'bytea_substr' },
62836290
{ oid => '2013', descr => 'extract portion of string',
62846291
proname => 'substring', prorettype => 'bytea', proargtypes => 'bytea int4',
6292+
proargnames => '{bytes, start}',
62856293
prosrc => 'bytea_substr_no_len' },
62866294
{ oid => '2085', descr => 'extract portion of string',
62876295
proname => 'substr', prorettype => 'bytea', proargtypes => 'bytea int4 int4',
6296+
proargnames => '{bytes, start, count}',
62886297
prosrc => 'bytea_substr' },
62896298
{ oid => '2086', descr => 'extract portion of string',
62906299
proname => 'substr', prorettype => 'bytea', proargtypes => 'bytea int4',
6300+
proargnames => '{bytes, start}',
62916301
prosrc => 'bytea_substr_no_len' },
62926302
{ oid => '2014', descr => 'position of substring',
62936303
proname => 'position', prorettype => 'int4', proargtypes => 'bytea bytea',
@@ -6479,9 +6489,12 @@
64796489

64806490
{ oid => '2073', descr => 'extract text matching regular expression',
64816491
proname => 'substring', prorettype => 'text', proargtypes => 'text text',
6492+
proargnames => '{string, pattern}',
64826493
prosrc => 'textregexsubstr' },
64836494
{ oid => '2074', descr => 'extract text matching SQL regular expression',
64846495
proname => 'substring', prolang => 'sql', prorettype => 'text',
6496+
proargnames => '{string, pattern, escape_character}',
6497+
proargnames => '{string, pattern, escape}',
64856498
proargtypes => 'text text text', prosrc => 'see system_functions.sql' },
64866499

64876500
{ oid => '2075', descr => 'convert int8 to bitstring',

0 commit comments

Comments
 (0)