Adjust INET/CIDR display conventions and reimplement some INET/CIDR

functions, per recent discussions on pghackers.  For now, I have called
the verbose-display formatting function text(), but will reconsider if
enough people object.
initdb forced.

3 files changed, 125 insertions, 126 deletions

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index f3e7aa83abf..11ccc2a9a60 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.38 2000/10/04 15:47:45 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.39 2000/11/10 20:13:25 tgl Exp $
 -->
 
  <chapter id="datatype">
@@ -65,7 +65,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.38 2000/10/04 15:47:45 pe
       <row>
        <entry>cidr</entry>
        <entry></entry>
-       <entry>IP version 4 network or host address</entry>
+       <entry>IP network address</entry>
       </row>
       <row>
        <entry>circle</entry>
@@ -95,7 +95,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.38 2000/10/04 15:47:45 pe
       <row>
        <entry>inet</entry>
        <entry></entry>
-       <entry>IP version 4 network or host address</entry>
+       <entry>IP network or host address</entry>
       </row>
       <row>
        <entry>int2</entry>
@@ -1736,7 +1736,7 @@ January 8 04:05:06 1999 PST
 
    <para>
     <productname>Postgres</> offers data types to store IP and MAC
-    addresses.  It is preferrable to use these types over plain text
+    addresses.  It is preferable to use these types over plain text
     types, because these types offer input error checking and several
     specialized operators and functions.
 
@@ -1755,16 +1755,16 @@ January 8 04:05:06 1999 PST
 
        <row>
 	<entry>cidr</entry>
-	<entry>11 bytes</entry>
+	<entry>12 bytes</entry>
 	<entry>IP networks</entry>
 	<entry>valid IPv4 networks</entry>
        </row>
 
        <row>
 	<entry>inet</entry>
-	<entry>11 bytes</entry>
+	<entry>12 bytes</entry>
 	<entry>IP hosts and networks</entry>
-	<entry>valid IPv4 hosts</entry>
+	<entry>valid IPv4 hosts or networks</entry>
        </row>
 
        <row>
@@ -1784,19 +1784,48 @@ January 8 04:05:06 1999 PST
    </para>
 
 
+   <sect2 id="inet-type">
+    <title><type>inet</type></title>
+
+    <para>
+     The <type>inet</type> type holds an IP host address, and
+     optionally the identity of the subnet it is in, all in one field.
+     The subnet identity is represented by the number of bits in the
+     network part of the address (the "netmask").  If the netmask is 32,
+     then the value does not indicate a subnet, only a single host.
+     Note that if you want to accept networks only, you should use the
+     <type>cidr</type> type rather than <type>inet</type>.
+    </para>
+
+    <para>
+     The input format for this type is <replaceable
+     class="parameter">x.x.x.x/y</replaceable> where <replaceable
+     class="parameter">x.x.x.x</replaceable> is an IP address and
+     <replaceable class="parameter">y</replaceable> is the number of
+     bits in the netmask.  If the <replaceable
+     class="parameter">y</replaceable> part is left off, then the
+     netmask is 32, and the value represents just a single host.
+     On display, the <replaceable class="parameter">/y</replaceable>
+     portion is suppressed if the netmask is 32.
+    </para>
+   </sect2>
+
    <sect2 id="cidr-type">
     <title><type>cidr</></title>
 
     <para>
-     The <type>cidr</type> type holds an IP network.  The format for
+     The <type>cidr</type> type holds an IP network specification.
+     Input and output formats follow Classless Internet Domain Routing
+     conventions.
+     The format for
      specifying classless networks is <replaceable
      class="parameter">x.x.x.x/y</> where <replaceable
      class="parameter">x.x.x.x</> is the network and <replaceable
      class="parameter">y</> is the number of bits in the netmask.  If
      <replaceable class="parameter">y</> omitted, it is calculated
-     using assumptions from the older classfull naming system except
-     that it is extended to include at least all of the octets in the
-     input.
+     using assumptions from the older classful numbering system, except
+     that it will be at least large enough to include all of the octets
+     written in the input.
     </para>
 
     <para>
@@ -1817,6 +1846,10 @@ January 8 04:05:06 1999 PST
 	 <entry>192.168.100.128/25</entry>
 	</row>
 	<row>
+	 <entry>192.168/24</entry>
+	 <entry>192.168.0/24</entry>
+	</row>
+	<row>
 	 <entry>192.168/25</entry>
 	 <entry>192.168.0.0/25</entry>
 	</row>
@@ -1856,30 +1889,19 @@ January 8 04:05:06 1999 PST
       </tgroup>
      </table>
     </para>
-   </sect2>
-
-   <sect2 id="inet-type">
-    <title><type>inet</type></title>
 
     <para>
-     The <type>inet</type> type holds an IP host address, and
-     optionally the identity of the subnet it is in, all in one field.
-     Note that if you want to store networks only, you should use the
-     <type>cidr</type> type.  The <type>inet</type> type is similar to
-     the <type>cidr</type> type except that the bits in the host part
-     can be non-zero.  Functions exist to extract the various elements
-     of the field.
-    </para>
-
-    <para>
-     The input format for this type is <replaceable
-     class="parameter">x.x.x.x/y</replaceable> where <replaceable
-     class="parameter">x.x.x.x</replaceable> is an internet host and
-     <replaceable class="parameter">y</replaceable> is the number of
-     bits in the netmask.  If the <replaceable
-     class="parameter">y</replaceable> part is left off, then the
-     netmask is 32 and you are effectively only storing the address of
-     a single host.
+    The essential difference between <type>inet</type> and <type>cidr</type>
+    data types is that <type>inet</type> accepts values with nonzero bits to
+    the right of the netmask, whereas <type>cidr</type> does not.
+
+      <tip>
+        <para>
+	If you do not like the output format for <type>inet</type> or
+	<type>cidr</type> values, try the <function>host</>() and
+	<function>text</>() functions.
+	</para>
+      </tip>
     </para>
    </sect2>
 
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c51e8905e10..655c63a7931 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1480,62 +1480,98 @@ Not defined by this name. Implements the intersection operator '#'
    <para>
     <table tocentry="1" id="cidr-inet-functions">
      <title><type>cidr</> and <type>inet</> Functions</title>
-     <tgroup cols="4">
+     <tgroup cols="5">
       <thead>
        <row>
 	<entry>Function</entry>
 	<entry>Returns</entry>
 	<entry>Description</entry>
 	<entry>Example</entry>
+	<entry>Result</entry>
        </row>
       </thead>
       <tbody>
        <row>
-	<entry>broadcast(cidr)</entry>
-	<entry>text</entry>
-	<entry>construct broadcast address as text</entry>
-	<entry>broadcast('192.168.1.5/24')</entry>
-       </row>
-       <row>
 	<entry>broadcast(inet)</entry>
-	<entry>text</entry>
-	<entry>construct broadcast address as text</entry>
+	<entry>inet</entry>
+	<entry>broadcast address for network</entry>
 	<entry>broadcast('192.168.1.5/24')</entry>
+	<entry>192.168.1.255/24</entry>
        </row>
        <row>
 	<entry>host(inet)</entry>
 	<entry>text</entry>
-	<entry>extract host address as text</entry>
+	<entry>extract IP address as text</entry>
 	<entry>host('192.168.1.5/24')</entry>
-       </row>
-       <row>
-	<entry>masklen(cidr)</entry>
-	<entry>integer</entry>
-	<entry>calculate netmask length</entry>
-	<entry>masklen('192.168.1.5/24')</entry>
+	<entry>192.168.1.5</entry>
        </row>
        <row>
 	<entry>masklen(inet)</entry>
 	<entry>integer</entry>
-	<entry>calculate netmask length</entry>
+	<entry>extract netmask length</entry>
 	<entry>masklen('192.168.1.5/24')</entry>
+	<entry>24</entry>
        </row>
        <row>
 	<entry>netmask(inet)</entry>
-	<entry>text</entry>
-	<entry>construct netmask as text</entry>
+	<entry>inet</entry>
+	<entry>construct netmask for network</entry>
 	<entry>netmask('192.168.1.5/24')</entry>
+	<entry>255.255.255.0</entry>
+       </row>
+       <row>
+	<entry>network(inet)</entry>
+	<entry>cidr</entry>
+	<entry>extract network part of address</entry>
+	<entry>network('192.168.1.5/24')</entry>
+	<entry>192.168.1/24</entry>
+       </row>
+       <row>
+	<entry>text(inet)</entry>
+	<entry>text</entry>
+	<entry>extract IP address and masklen as text</entry>
+	<entry>text(inet '192.168.1.5')</entry>
+	<entry>192.168.1.5/32</entry>
+       </row>
+      </tbody>
+     </tgroup>
+    </table>
+   </para>
+
+   <para>
+    All of the functions for <type>inet</type> can be applied to
+    <type>cidr</type> values as well.  The <function>host</>() and
+    <function>text</>() functions are primarily intended to offer
+    alternative display formats.
+   </para>
+
+   <para>
+    <table tocentry="1" id="macaddr-functions">
+     <title><type>macaddr</> Functions</title>
+     <tgroup cols="5">
+      <thead>
+       <row>
+	<entry>Function</entry>
+	<entry>Returns</entry>
+	<entry>Description</entry>
+	<entry>Example</entry>
+	<entry>Result</entry>
        </row>
+      </thead>
+      <tbody>
        <row>
 	<entry>trunc(macaddr)</entry>
 	<entry>macaddr</entry>
 	<entry>set last 3 bytes to zero</entry>
 	<entry>trunc(macaddr '12:34:56:78:90:ab')</entry>
+	<entry>12:34:56:00:00:00</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
+   </para>
 
+   <para>
     The function <function>trunc</>(<type>macaddr</>) returns a MAC
     address with the last 3 bytes set to 0.  This can be used to
     associate the remaining prefix with a manufacturer.  The directory
diff --git a/doc/src/sgml/oper.sgml b/doc/src/sgml/oper.sgml
index deb3d33cde8..8934323cd05 100644
--- a/doc/src/sgml/oper.sgml
+++ b/doc/src/sgml/oper.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/oper.sgml,v 1.21 2000/10/24 20:13:31 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/oper.sgml,v 1.22 2000/11/10 20:13:25 tgl Exp $
 -->
 
  <Chapter Id="operators">
@@ -756,80 +756,11 @@ logical union
   <sect1 id="net-operators">
    <title>Network Address Type Operators</title>
 
-   <sect2 id="cidr-operators">
-    <title><type>cidr</> Operators</title>
+   <sect2 id="cidr-inet-operators">
+    <title><type>cidr</> and <type>inet</> Operators</title>
 
-    <table tocentry="1" id="cidr-operators-table">
-     <title><type>cidr</> Operators</title>
-     <TGROUP COLS="3">
-      <THEAD>
-       <ROW>
-	<ENTRY>Operator</ENTRY>
-	<ENTRY>Description</ENTRY>
-	<ENTRY>Usage</ENTRY>
-       </ROW>
-      </THEAD>
-      <TBODY>
-       <ROW>
-	<ENTRY> &lt; </ENTRY>
-	<ENTRY>Less than</ENTRY>
-	<ENTRY>'192.168.1.5'::cidr &lt; '192.168.1.6'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &lt;= </ENTRY>
-	<ENTRY>Less than or equal</ENTRY>
-	<ENTRY>'192.168.1.5'::cidr &lt;= '192.168.1.5'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> = </ENTRY>
-	<ENTRY>Equals</ENTRY>
-	<ENTRY>'192.168.1.5'::cidr = '192.168.1.5'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &gt;= </ENTRY>
-	<ENTRY>Greater or equal</ENTRY>
-	<ENTRY>'192.168.1.5'::cidr &gt;= '192.168.1.5'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &gt; </ENTRY>
-	<ENTRY>Greater</ENTRY>
-	<ENTRY>'192.168.1.5'::cidr &gt; '192.168.1.4'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &lt;&gt; </ENTRY>
-	<ENTRY>Not equal</ENTRY>
-	<ENTRY>'192.168.1.5'::cidr &lt;&gt; '192.168.1.4'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &lt;&lt; </ENTRY>
-	<ENTRY>is contained within</ENTRY>
-	<ENTRY>'192.168.1.5'::cidr &lt;&lt; '192.168.1/24'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &lt;&lt;= </ENTRY>
-	<ENTRY>is contained within or equals</ENTRY>
-	<ENTRY>'192.168.1/24'::cidr &lt;&lt;= '192.168.1/24'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &gt;&gt; </ENTRY>
-	<ENTRY>contains</ENTRY>
-	<ENTRY>'192.168.1/24'::cidr &gt;&gt; '192.168.1.5'::cidr</ENTRY>
-       </ROW>
-       <ROW>
-	<ENTRY> &gt;&gt;= </ENTRY>
-	<ENTRY>contains or equals</ENTRY>
-	<ENTRY>'192.168.1/24'::cidr &gt;&gt;= '192.168.1/24'::cidr</ENTRY>
-       </ROW>
-      </TBODY>
-     </TGROUP>
-    </TABLE>
-   </sect2>
-
-   <sect2 id="inet-operators">
-   <title><type>inet</> Operators</title>
-   
-    <table tocentry="1" id="inet-operators-table">
-     <title><type>inet</> Operators</title>
+    <table tocentry="1" id="cidr-inet-operators-table">
+     <title><type>cidr</> and <type>inet</> Operators</title>
      <TGROUP COLS="3">
       <THEAD>
        <ROW>
@@ -892,6 +823,16 @@ logical union
       </TBODY>
      </TGROUP>
     </TABLE>
+
+    <para>
+     All of the operators for <type>inet</type> can be applied to
+     <type>cidr</type> values as well.  The operators
+     <literal>&lt;&lt;</> <literal>&lt;&lt;=</>
+     <literal>&gt;&gt;</> <literal>&gt;&gt;=</>
+     test for subnet inclusion: they consider only the network parts
+     of the two addresses, ignoring any host part, and determine whether
+     one network part is identical to or a subnet of the other.
+    </para>
    </sect2>
 
    <sect2 id="macaddr-operators">