Add a note to the docs describing NaN's equality and ordering behavior.

Per recent -hackers thread, this is noteworthy because Postgres behaves
differently from most implementations of NaN, including IEEE754.

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 34af82629ed30536215dfacc533ecb427e81ce91..269998a3dde0d771a65330ac94afb8c3aa68d240 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.183 2006/12/22 22:09:31 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.184 2007/01/14 22:37:59 neilc Exp $ -->
 
  <chapter id="datatype">
   <title id="datatype-title">Data Types</title>
@@ -438,10 +438,14 @@
    <sect2 id="datatype-numeric-decimal">
     <title>Arbitrary Precision Numbers</title>
 
-    <indexterm zone="datatype-numeric-decimal">
+    <indexterm>
      <primary>numeric (data type)</primary>
     </indexterm>
 
+   <indexterm>
+    <primary>arbitrary precision numbers</primary>
+   </indexterm>
+
     <indexterm>
      <primary>decimal</primary>
      <see>numeric</see>
@@ -515,6 +519,16 @@ NUMERIC
      plus eight bytes overhead.
     </para>
 
+    <indexterm>
+     <primary>NaN</primary>
+     <see>not a number</see>
+   </indexterm>
+
+    <indexterm>
+     <primary>not a number</primary>
+     <secondary>numeric (data type)</secondary>
+    </indexterm>
+
     <para>
      In addition to ordinary numeric values, the <type>numeric</type>
      type allows the special value <literal>NaN</>, meaning 
@@ -525,6 +539,18 @@ NUMERIC
      the string <literal>NaN</> is recognized in a case-insensitive manner.
     </para>
 
+    <note>
+     <para>
+      In most implementations of the <quote>not-a-number</> concept,
+      <literal>NaN</> is not considered equal to any other numeric
+      value (including <literal>NaN</>).  In order to allow
+      <type>numeric</> values to be sorted and used in tree-based
+      indexes, <productname>PostgreSQL</> treats <literal>NaN</>
+      values as equal, and greater than all non-<literal>NaN</>
+      values.
+     </para>
+    </note>
+
     <para>
      The types <type>decimal</type> and <type>numeric</type> are
      equivalent.  Both types are part of the <acronym>SQL</acronym>
@@ -613,6 +639,11 @@ NUMERIC
      from zero will cause an underflow error.
     </para>
 
+    <indexterm>
+     <primary>not a number</primary>
+     <secondary>double precision</secondary>
+    </indexterm>
+
     <para>
      In addition to ordinary numeric values, the floating-point types
      have several special values:
@@ -631,6 +662,17 @@ NUMERIC
      these strings are recognized in a case-insensitive manner.
     </para>
 
+    <note>
+     <para>
+      IEEE754 specifies that <literal>NaN</> should not compare equal
+      to any other floating-point value (including <literal>NaN</>).
+      In order to allow floating-point values to be sorted and used
+      in tree-based indexes, <productname>PostgreSQL</> treats
+      <literal>NaN</> values as equal, and greater than all
+      non-<literal>NaN</> values.
+     </para>
+    </note>
+
     <para>
      <productname>PostgreSQL</productname> also supports the SQL-standard
      notations <type>float</type> and