Improve documentation for COALESCE and NULLIF. Add references for NVL

and IFNULL.

Backpatch to 8.1.X.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index b6f1a40b4a0a46c293b852be5a352d1e1d43a943..7d603ef97822848a61f278ca0331aabfe6e0e3cd 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.295 2005/11/19 19:44:54 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.296 2005/11/28 23:18:48 momjian Exp $
 PostgreSQL documentation
 -->
 
@@ -7227,6 +7227,14 @@ SELECT ... WHERE CASE WHEN x &lt;&gt; 0 THEN y/x &gt; 1.5 ELSE false END;
    <primary>COALESCE</primary>
   </indexterm>
 
+  <indexterm>
+   <primary>NVL</primary>
+  </indexterm>
+
+  <indexterm>
+   <primary>IFNULL</primary>
+  </indexterm>
+
 <synopsis>
 <function>COALESCE</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
 </synopsis>
@@ -7234,9 +7242,8 @@ SELECT ... WHERE CASE WHEN x &lt;&gt; 0 THEN y/x &gt; 1.5 ELSE false END;
   <para>
    The <function>COALESCE</function> function returns the first of its
    arguments that is not null.  Null is returned only if all arguments
-   are null.  This is often useful to substitute a
-   default value for null values when data is retrieved for display,
-   for example:
+   are null.  It is often used to substitute a default value for 
+   null values when data is retrieved for display, for example:
 <programlisting>
 SELECT COALESCE(description, short_description, '(none)') ...
 </programlisting>
@@ -7246,7 +7253,9 @@ SELECT COALESCE(description, short_description, '(none)') ...
     Like a <token>CASE</token> expression, <function>COALESCE</function> will
     not evaluate arguments that are not needed to determine the result;
     that is, arguments to the right of the first non-null argument are
-    not evaluated.
+    not evaluated.  This SQL-standard function provides capabilities similar
+    to <function>NVL</> and <function>IFNULL</>, which are used in some other
+    database systems.
    </para>
   </sect2>
 
@@ -7262,16 +7271,19 @@ SELECT COALESCE(description, short_description, '(none)') ...
 </synopsis>
 
   <para>
-   The <function>NULLIF</function> function returns a null value if and only
-   if <replaceable>value1</replaceable> and
-   <replaceable>value2</replaceable> are equal.  Otherwise it returns
-   <replaceable>value1</replaceable>.  This can be used to perform the
-   inverse operation of the <function>COALESCE</function> example
-   given above:
+   The <function>NULLIF</function> function returns a null value if
+   <replaceable>value1</replaceable> and <replaceable>value2</replaceable>
+   are equal;  otherwise it returns <replaceable>value1</replaceable>.
+   This can be used to perform the inverse operation of the
+   <function>COALESCE</function> example given above:
 <programlisting>
 SELECT NULLIF(value, '(none)') ...
 </programlisting>
   </para>
+  <para>
+   If <replaceable>value1</replaceable> is <literal>(none)</>, return a null,
+   otherwise return <replaceable>value1</replaceable>.
+  </para>
 
   </sect2>