mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: add cross-references between array_to_string and string_to_array.

Browse Source 
These functions aren't exact inverses, but they're closely related;
yet we document them in two different sections.  Add cross-ref
<link>s to improve that situation.

While here, move the strpos and substr entries to re-alphabetize
Table 9.10.  Also, drop an ancient compatibility note about
string_to_array, which wasn't even on the right page, so probably
few people ever saw it.

Discussion: https://postgr.es/m/164287017550.704.5840412183184961677@wrigleys.postgresql.org
This commit is contained in:
Tom Lane 2022-01-22 15:44:51 -05:00
parent d8fbbb925b
commit 4f02cbcb68
1 changed files with 80 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
doc/src/sgml/func.sgml
View File

@ -3508,6 +3508,84 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>starts_with</primary>
</indexterm>
<function>starts_with</function> ( <parameter>string</parameter> <type>text</type>, <parameter>prefix</parameter> <type>text</type> )
<returnvalue>boolean</returnvalue>
</para>
<para>
Returns true if <parameter>string</parameter> starts
with <parameter>prefix</parameter>.
</para>
<para>
<literal>starts_with('alphabet', 'alph')</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm id="function-string-to-array">
<primary>string_to_array</primary>
</indexterm>
<function>string_to_array</function> ( <parameter>string</parameter> <type>text</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
<returnvalue>text[]</returnvalue>
</para>
<para>
Splits the <parameter>string</parameter> at occurrences
of <parameter>delimiter</parameter> and forms the resulting fields
into a <type>text</type> array.
If <parameter>delimiter</parameter> is <literal>NULL</literal>,
each character in the <parameter>string</parameter> will become a
separate element in the array.
If <parameter>delimiter</parameter> is an empty string, then
the <parameter>string</parameter> is treated as a single field.
If <parameter>null_string</parameter> is supplied and is
not <literal>NULL</literal>, fields matching that string are
replaced by <literal>NULL</literal>.
See also <link linkend="function-array-to-string"><function>array_to_string</function></link>.
</para>
<para>
<literal>string_to_array('xx~~yy~~zz', '~~', 'yy')</literal>
<returnvalue>{xx,NULL,zz}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>string_to_table</primary>
</indexterm>
<function>string_to_table</function> ( <parameter>string</parameter> <type>text</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
<returnvalue>setof text</returnvalue>
</para>
<para>
Splits the <parameter>string</parameter> at occurrences
of <parameter>delimiter</parameter> and returns the resulting fields
as a set of <type>text</type> rows.
If <parameter>delimiter</parameter> is <literal>NULL</literal>,
each character in the <parameter>string</parameter> will become a
separate row of the result.
If <parameter>delimiter</parameter> is an empty string, then
the <parameter>string</parameter> is treated as a single field.
If <parameter>null_string</parameter> is supplied and is
not <literal>NULL</literal>, fields matching that string are
replaced by <literal>NULL</literal>.
</para>
<para>
<literal>string_to_table('xx~^~yy~^~zz', '~^~', 'yy')</literal>
<returnvalue></returnvalue>
<programlisting>
xx
NULL
zz
</programlisting>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
@ -3556,83 +3634,6 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>starts_with</primary>
</indexterm>
<function>starts_with</function> ( <parameter>string</parameter> <type>text</type>, <parameter>prefix</parameter> <type>text</type> )
<returnvalue>boolean</returnvalue>
</para>
<para>
Returns true if <parameter>string</parameter> starts
with <parameter>prefix</parameter>.
</para>
<para>
<literal>starts_with('alphabet', 'alph')</literal>
<returnvalue>t</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>string_to_array</primary>
</indexterm>
<function>string_to_array</function> ( <parameter>string</parameter> <type>text</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
<returnvalue>text[]</returnvalue>
</para>
<para>
Splits the <parameter>string</parameter> at occurrences
of <parameter>delimiter</parameter> and forms the resulting fields
into a <type>text</type> array.
If <parameter>delimiter</parameter> is <literal>NULL</literal>,
each character in the <parameter>string</parameter> will become a
separate element in the array.
If <parameter>delimiter</parameter> is an empty string, then
the <parameter>string</parameter> is treated as a single field.
If <parameter>null_string</parameter> is supplied and is
not <literal>NULL</literal>, fields matching that string are
replaced by <literal>NULL</literal>.
</para>
<para>
<literal>string_to_array('xx~~yy~~zz', '~~', 'yy')</literal>
<returnvalue>{xx,NULL,zz}</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>string_to_table</primary>
</indexterm>
<function>string_to_table</function> ( <parameter>string</parameter> <type>text</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
<returnvalue>setof text</returnvalue>
</para>
<para>
Splits the <parameter>string</parameter> at occurrences
of <parameter>delimiter</parameter> and returns the resulting fields
as a set of <type>text</type> rows.
If <parameter>delimiter</parameter> is <literal>NULL</literal>,
each character in the <parameter>string</parameter> will become a
separate row of the result.
If <parameter>delimiter</parameter> is an empty string, then
the <parameter>string</parameter> is treated as a single field.
If <parameter>null_string</parameter> is supplied and is
not <literal>NULL</literal>, fields matching that string are
replaced by <literal>NULL</literal>.
</para>
<para>
<literal>string_to_table('xx~^~yy~^~zz', '~^~', 'yy')</literal>
<returnvalue></returnvalue>
<programlisting>
xx
NULL
zz
</programlisting>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
@ -18452,7 +18453,7 @@ SELECT NULLIF(value, '(none)') ...
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<indexterm id="function-array-to-string">
<primary>array_to_string</primary>
</indexterm>
<function>array_to_string</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>delimiter</parameter> <type>text</type> <optional>, <parameter>null_string</parameter> <type>text</type> </optional> )
@ -18465,6 +18466,7 @@ SELECT NULLIF(value, '(none)') ...
If <parameter>null_string</parameter> is given and is
not <literal>NULL</literal>, then <literal>NULL</literal> array
entries are represented by that string; otherwise, they are omitted.
See also <link linkend="function-string-to-array"><function>string_to_array</function></link>.
</para>
<para>
<literal>array_to_string(ARRAY[1, 2, 3, NULL, 5], ',', '*')</literal>
@ -18584,18 +18586,6 @@ SELECT NULLIF(value, '(none)') ...
</tgroup>
</table>
<note>
<para>
There are two differences in the behavior of <function>string_to_array</function>
from pre-9.1 versions of <productname>PostgreSQL</productname>.
First, it will return an empty (zero-element) array rather
than <literal>NULL</literal> when the input string is of zero length.
Second, if the delimiter string is <literal>NULL</literal>, the function
splits the input into individual characters, rather than
returning <literal>NULL</literal> as before.
</para>
</note>
<para>
See also <xref linkend="functions-aggregate"/> about the aggregate
function <function>array_agg</function> for use with arrays.