Further review of range-types patch.

Lots of documentation cleanup today, and still more type_sanity tests.

Author: tglsfdc

doc/src/sgml/catalogs.sgml

@@ -4607,7 +4607,9 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_range</structname> stores information about range types.
+   The catalog <structname>pg_range</structname> stores information about
+   range types.  This is in addition to the types' entries in
+   <link linkend="catalog-pg-type"><structname>pg_type</structname></link>.
   </para>
 
   <table>
@@ -4628,47 +4630,57 @@
       <entry><structfield>rngtypid</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-type"><structname>pg_type</structname></link>.oid</literal></entry>
-      <entry>The type that is a range type</entry>
+      <entry>OID of the range type</entry>
      </row>
 
      <row>
       <entry><structfield>rngsubtype</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-type"><structname>pg_type</structname></link>.oid</literal></entry>
-      <entry>Subtype of this range type, e.g. <type>integer</type> is the subtype of <type>int4range</type></entry>
+      <entry>OID of the element type (subtype) of this range type</entry>
      </row>
 
      <row>
       <entry><structfield>rngcollation</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-collation"><structname>pg_collation</structname></link>.oid</literal></entry>
-      <entry>The collation used when comparing range boundaries</entry>
+      <entry>OID of the collation used for range comparisons, or 0 if none</entry>
      </row>
 
      <row>
       <entry><structfield>rngsubopc</structfield></entry>
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-opclass"><structname>pg_opclass</structname></link>.oid</literal></entry>
-      <entry>The operator class used when comparing range boundaries</entry>
+      <entry>OID of the subtype's operator class used for range comparisons</entry>
      </row>
 
      <row>
       <entry><structfield>rngcanonical</structfield></entry>
       <entry><type>regproc</type></entry>
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>A function to convert a range into its canonical form</entry>
+      <entry>OID of the function to convert a range value into canonical form,
+      or 0 if none</entry>
      </row>
 
      <row>
       <entry><structfield>rngsubdiff</structfield></entry>
       <entry><type>regproc</type></entry>
       <entry><literal><link linkend="catalog-pg-proc"><structname>pg_proc</structname></link>.oid</literal></entry>
-      <entry>A function to return the distance between two lower and upper bound, as a <type>double precision</type>. Used for GiST support</entry>
+      <entry>OID of the function to return the difference between two element
+      values as <type>double precision</type>, or 0 if none</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
 
+  <para>
+   <structfield>rngsubopc</> (plus <structfield>rngcollation</>, if the
+   element type is collatable) determines the sort ordering used by the range
+   type.  <structfield>rngcanonical</> is used when the element type is
+   discrete.  <structfield>rngsubdiff</> is optional but should be supplied to
+   improve performance of GiST indexes on the range type.
+  </para>
+
  </sect1>
 
  <sect1 id="catalog-pg-rewrite">
@@ -6059,7 +6071,8 @@
        <literal>c</literal> for a composite type (e.g., a table's row type),
        <literal>d</literal> for a domain,
        <literal>e</literal> for an enum type,
-       or <literal>p</literal> for a pseudo-type.
+       <literal>p</literal> for a pseudo-type, or
+       <literal>r</literal> for a range type.
        See also <structfield>typrelid</structfield> and
        <structfield>typbasetype</structfield>.
       </entry>
@@ -6429,6 +6442,10 @@
       <entry><literal>P</literal></entry>
       <entry>Pseudo-types</entry>
      </row>
+     <row>
+      <entry><literal>R</literal></entry>
+      <entry>Range types</entry>
+     </row>
      <row>
       <entry><literal>S</literal></entry>
       <entry>String types</entry>

doc/src/sgml/extend.sgml

@@ -200,13 +200,13 @@
     <para>
      Five pseudo-types of special interest are <type>anyelement</>,
      <type>anyarray</>, <type>anynonarray</>, <type>anyenum</>,
-     and <type>anyrange</>, which are collectively
-     called <firstterm>polymorphic types</>.  Any function declared
-     using these types is said to be a <firstterm>polymorphic
-     function</>.  A polymorphic function can operate on many
-     different data types, with the specific data type(s) being
-     determined by the data types actually passed to it in a
-     particular call.
+     and <type>anyrange</>,
+     which are collectively called <firstterm>polymorphic types</>.
+     Any function declared using these types is said to be
+     a <firstterm>polymorphic function</>.  A polymorphic function can
+     operate on many different data types, with the specific data type(s)
+     being determined by the data types actually passed to it in a particular
+     call.
     </para>
 
     <para>
@@ -217,15 +217,16 @@
      data type, but in any given call they must all be the
      <emphasis>same</emphasis> actual type. Each
      position declared as <type>anyarray</type> can have any array data type,
-     but similarly they must all be the same type. If there are
+     but similarly they must all be the same type.  And similarly,
+     positions declared as <type>anyrange</type> must all be the same range
+     type.  Furthermore, if there are
      positions declared <type>anyarray</type> and others declared
      <type>anyelement</type>, the actual array type in the
      <type>anyarray</type> positions must be an array whose elements are
      the same type appearing in the <type>anyelement</type> positions.
      Similarly, if there are positions declared <type>anyrange</type>
-     and others declared
-     <type>anyelement</type>, the actual range type in the
-     <type>anyrange</type> positions must be a range whose subtype is
+     and others declared <type>anyelement</type>, the actual range type in
+     the <type>anyrange</type> positions must be a range whose subtype is
      the same type appearing in the <type>anyelement</type> positions.
      <type>anynonarray</> is treated exactly the same as <type>anyelement</>,
      but adds the additional constraint that the actual type must not be

doc/src/sgml/func.sgml

@@ -10525,18 +10525,32 @@ SELECT NULLIF(value, '(none)') ...
 
        <row>
         <entry> <literal>@&gt;</literal> </entry>
-        <entry>contains</entry>
+        <entry>contains range</entry>
+        <entry><literal>int4range(2,4) @&gt; int4range(2,3)</literal></entry>
+        <entry><literal>t</literal></entry>
+       </row>
+
+       <row>
+        <entry> <literal>@&gt;</literal> </entry>
+        <entry>contains element</entry>
         <entry><literal>'[2011-01-01,2011-03-01)'::tsrange @&gt; '2011-01-10'::timestamp</literal></entry>
         <entry><literal>t</literal></entry>
        </row>
 
        <row>
         <entry> <literal>&lt;@</literal> </entry>
-        <entry>is contained by</entry>
+        <entry>range is contained by</entry>
         <entry><literal>int4range(2,4) &lt;@ int4range(1,7)</literal></entry>
         <entry><literal>t</literal></entry>
        </row>
 
+       <row>
+        <entry> <literal>&lt;@</literal> </entry>
+        <entry>element is contained by</entry>
+        <entry><literal>42 &lt;@ int4range(1,7)</literal></entry>
+        <entry><literal>f</literal></entry>
+       </row>
+
        <row>
         <entry> <literal>&amp;&amp;</literal> </entry>
         <entry>overlap (have points in common)</entry>