Doc: add cross-references between array_to_string and string_to_array.

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

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 90169a0ce72cc581b9a3a0b7c9b848f78e7b7418..034fecc3a1913d843344cda27ec015603dcf91d2 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -3508,54 +3508,6 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
        </para></entry>
       </row>
 
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
-         <primary>strpos</primary>
-        </indexterm>
-        <function>strpos</function> ( <parameter>string</parameter> <type>text</type>, <parameter>substring</parameter> <type>text</type> )
-        <returnvalue>integer</returnvalue>
-       </para>
-       <para>
-        Returns first starting index of the specified <parameter>substring</parameter>
-        within <parameter>string</parameter>, or zero if it's not present.
-        (Same as <literal>position(<parameter>substring</parameter> in
-        <parameter>string</parameter>)</literal>, but note the reversed
-        argument order.)
-       </para>
-       <para>
-        <literal>strpos('high', 'ig')</literal>
-        <returnvalue>2</returnvalue>
-       </para></entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
-         <primary>substr</primary>
-        </indexterm>
-        <function>substr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
-        <returnvalue>text</returnvalue>
-       </para>
-       <para>
-        Extracts the substring of <parameter>string</parameter> starting at
-        the <parameter>start</parameter>'th character,
-        and extending for <parameter>count</parameter> characters if that is
-        specified.  (Same
-        as <literal>substring(<parameter>string</parameter>
-        from <parameter>start</parameter>
-        for <parameter>count</parameter>)</literal>.)
-       </para>
-       <para>
-        <literal>substr('alphabet', 3)</literal>
-        <returnvalue>phabet</returnvalue>
-       </para>
-       <para>
-        <literal>substr('alphabet', 3, 2)</literal>
-        <returnvalue>ph</returnvalue>
-       </para></entry>
-      </row>
-
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
@@ -3576,7 +3528,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
 
       <row>
        <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
+        <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> )
@@ -3594,6 +3546,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         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>
@@ -3633,6 +3586,54 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
        </para></entry>
       </row>
 
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>strpos</primary>
+        </indexterm>
+        <function>strpos</function> ( <parameter>string</parameter> <type>text</type>, <parameter>substring</parameter> <type>text</type> )
+        <returnvalue>integer</returnvalue>
+       </para>
+       <para>
+        Returns first starting index of the specified <parameter>substring</parameter>
+        within <parameter>string</parameter>, or zero if it's not present.
+        (Same as <literal>position(<parameter>substring</parameter> in
+        <parameter>string</parameter>)</literal>, but note the reversed
+        argument order.)
+       </para>
+       <para>
+        <literal>strpos('high', 'ig')</literal>
+        <returnvalue>2</returnvalue>
+       </para></entry>
+      </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>substr</primary>
+        </indexterm>
+        <function>substr</function> ( <parameter>string</parameter> <type>text</type>, <parameter>start</parameter> <type>integer</type> <optional>, <parameter>count</parameter> <type>integer</type> </optional> )
+        <returnvalue>text</returnvalue>
+       </para>
+       <para>
+        Extracts the substring of <parameter>string</parameter> starting at
+        the <parameter>start</parameter>'th character,
+        and extending for <parameter>count</parameter> characters if that is
+        specified.  (Same
+        as <literal>substring(<parameter>string</parameter>
+        from <parameter>start</parameter>
+        for <parameter>count</parameter>)</literal>.)
+       </para>
+       <para>
+        <literal>substr('alphabet', 3)</literal>
+        <returnvalue>phabet</returnvalue>
+       </para>
+       <para>
+        <literal>substr('alphabet', 3, 2)</literal>
+        <returnvalue>ph</returnvalue>
+       </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.