doc: move ROW IS NULL examples to a different chapter

bmomjian · bmomjian · commit bd8640789212 · 2023-11-13T15:20:54.000-05:00
Also add examples. Reported-by: Wolfgang Walther Discussion: https://postgr.es/m/21ff8e9c-627a-f949-fb00-a41b9ddcc9d3@technowledgy.de Backpatch-through: master
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
@@ -718,7 +718,19 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
     <literal>IS NULL</literal> and <literal>IS NOT NULL</literal> do not always return
     inverse results for row-valued expressions; in particular, a row-valued
     expression that contains both null and non-null fields will return false
-    for both tests.  In some cases, it may be preferable to
+    for both tests.  For example: 
+
+<programlisting>
+SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
+
+SELECT ROW(table.*) IS NULL FROM table;  -- detect all-null rows
+
+SELECT ROW(table.*) IS NOT NULL FROM table;  -- detect all-non-null rows
+
+SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in rows
+</programlisting>
+
+    In some cases, it may be preferable to
     write <replaceable>row</replaceable> <literal>IS DISTINCT FROM NULL</literal>
     or <replaceable>row</replaceable> <literal>IS NOT DISTINCT FROM NULL</literal>,
     which will simply check whether the overall row value is null without any
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
@@ -2479,17 +2479,12 @@ SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
   <para>
    Row constructors can be used to build composite values to be stored
    in a composite-type table column, or to be passed to a function that
-   accepts a composite parameter.  Also,
-   it is possible to compare two row values or test a row with
-   <literal>IS NULL</literal> or <literal>IS NOT NULL</literal>, for example:
-<programlisting>
-SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
-
-SELECT ROW(table.*) IS NULL FROM table;  -- detect all-null rows
-</programlisting>
-   For more detail see <xref linkend="functions-comparisons"/>.
-   Row constructors can also be used in connection with subqueries,
-   as discussed in <xref linkend="functions-subquery"/>.
+   accepts a composite parameter.  Also, it is possible to test rows
+   using the standard comparison operators as described in <xref
+   linkend="functions-comparison"/>, to compare one row against another
+   as described in <xref linkend="functions-comparisons"/>, and to
+   use them in connection with subqueries, as discussed in <xref
+   linkend="functions-subquery"/>,
   </para>
 
   </sect2>
