Include new cidr and inet data types.

3 files changed, 391 insertions, 25 deletions

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 8efb77c24da..f88a66ed803 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -59,6 +59,11 @@ several possibilities for formats, such as date and time types.
     <ENTRY>fixed-length character string</ENTRY>
   </ROW>
   <ROW>
+    <ENTRY>cidr</ENTRY>
+    <ENTRY></ENTRY>
+    <ENTRY>IP version 4 network or host address</ENTRY>
+  </ROW>
+  <ROW>
     <ENTRY>circle</ENTRY>
     <ENTRY></ENTRY>
     <ENTRY>circle in 2D plane</ENTRY>
@@ -79,6 +84,11 @@ several possibilities for formats, such as date and time types.
     <ENTRY>double-precision floating-point number</ENTRY>
   </ROW>
   <ROW>
+    <ENTRY>inet</ENTRY>
+    <ENTRY></ENTRY>
+    <ENTRY>IP version 4 network or host address</ENTRY>
+  </ROW>
+  <ROW>
     <ENTRY>int2</ENTRY>
     <ENTRY>smallint</ENTRY>
     <ENTRY>signed two-byte integer</ENTRY>
@@ -163,6 +173,14 @@ several possibilities for formats, such as date and time types.
 </TABLE>
 </Para>
 
+<para>
+<note>
+<para>
+The <type>cidr</type> and <type>inet</type> types are designed to handle any IP type 
+but only ipv4 is handled in the current implementation.  
+Everything here that talks about ipv4 will apply to ipv6 in a future release.
+</note>
+
 <Para>
 <TABLE TOCENTRY="1">
 <TITLE><ProductName>Postgres</ProductName> Function Constants</TITLE>
@@ -500,17 +518,21 @@ This is set at compile time and may change in a future release.
 
 <Para>
 There are two fundamental kinds of date and time measurements:
- clock time and time interval.
-Both quantities have continuity and smoothness, as does time itself.
+ absolute clock times and relative time intervals.
+Both quantities should demonstrate continuity and smoothness, as does time itself.
 <ProductName>Postgres</ProductName> supplies two primary user-oriented 
 date and time types,
-<Type>datetime</Type> and timespan, as well as 
-the related <acronym>SQL92</acronym> types date and time.
+<Type>datetime</Type> and <Type>timespan</Type>, as well as 
+the related <acronym>SQL92</acronym> types <Type>timestamp</Type>,
+<Type>interval</Type>,
+<Type>date</Type> and <Type>time</Type>.
 </Para>
 
 <Para>
-Other date and time types are available
-also, mostly
+In a future release, <Type>datetime</Type> and <Type>timespan</Type> are likely
+to merge with the <acronym>SQL92</acronym> types <Type>timestamp</Type>,
+<Type>interval</Type>.
+Other date and time types are also available, mostly
 for historical reasons.
 </Para>
 
@@ -579,6 +601,9 @@ for historical reasons.
 </TBODY>
 </TGROUP>
 </TABLE>
+
+<type>timestamp</type> is currently implemented separately from
+<type>datetime</type>, although they share input and output routines.
 </Para>
 
 <Para>
@@ -652,13 +677,26 @@ for historical reasons.
 <ProductName>Postgres</ProductName> endevours to be compatible with
 <Acronym>SQL92</Acronym> definitions for typical usage.
 The <Acronym>SQL92</Acronym> standard has an odd mix of date and
-time types and capabilities. For example, although the date type 
+time types and capabilities. Two obvious problems are:
+
+<itemizedlist>
+<listitem>
+<para>
+Although the <type>date</type> type 
 does not have an associated time zone, the
-time type can. The default time zone is specified as a constant offset 
-from GMT/UTC;
- however, time zones in the real world can have no meaning unless 
-associated with a date as well
-as a time since the offset will vary through the year.
+<type>time</type> type can or does.
+
+<listitem>
+<para>
+The default time zone is specified as a constant integer offset 
+from GMT/UTC.
+
+</itemizedlist>
+
+However, time zones in the real world can have no meaning unless 
+associated with a date as well as a time
+since the offset may vary through the year with daylight savings
+time boundaries.
 
 <Para>
 To address these difficulties, <ProductName>Postgres</ProductName> 
@@ -1412,3 +1450,127 @@ Circles are output using the first syntax.
 
 </Sect1>
 
+<Sect1>
+<Title>IP Version 4 Networks and Host Addresses</Title>
+
+<Para>
+The <Type>cidr</Type> type stores networks specified 
+in <acronym>CIDR</acronym> notation.
+The <Type>inet</Type> type stores hosts and networks in CIDR notation.
+</Para>
+
+<Para>
+<TABLE TOCENTRY="1">
+<TITLE><ProductName>Postgres</ProductName>IP Version 4 Type</TITLE>
+<TITLEABBREV>IPV4</TITLEABBREV>
+<TGROUP COLS="4">
+<THEAD>
+  <ROW>
+    <ENTRY>IPV4 Type</ENTRY>
+    <ENTRY>Storage</ENTRY>
+    <ENTRY>Description</ENTRY>
+    <ENTRY>Range</ENTRY>
+  </ROW>
+</THEAD>
+<TBODY>
+  <ROW>
+    <ENTRY>cidr</ENTRY>
+    <ENTRY>variable</ENTRY>
+    <ENTRY>CIDR networks</ENTRY>
+    <ENTRY>Valid IPV4 CIDR blocks</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>inet</ENTRY>
+    <ENTRY>variable</ENTRY>
+    <ENTRY>nets and hosts</ENTRY>
+    <ENTRY>Valid IPV4 CIDR blocks</ENTRY>
+  </ROW>
+</TBODY>
+</TGROUP>
+</TABLE>
+</Para>
+
+<Sect2>
+<Title><type>inet</type> for IP Networks</Title>
+
+<Para>
+The cidr type holds a CIDR network.
+The format for specifying networks is "x.x.x.x/y" where "x.x.x.x" is the
+network and "/y" is the number of bits in the netmask.
+If the "/y" part is left off, it is calculated using assumptions from
+the old class system except that it is extended to include at least
+all of the octets in the input.
+Here are some examples.
+
+<!-- There's a lot of examples here.
+  -- Take some out if you think there are too many...
+  -->
+
+<Para> 
+<TABLE TOCENTRY="1">
+<TGROUP COLS="4">
+<THEAD> 
+  <ROW> 
+    <ENTRY>Input</ENTRY>
+	<ENTRY>Output</ENTRY>
+</THEAD>
+<TBODY>
+  <ROW>
+    <ENTRY>select '192.168.1'::cidr</ENTRY>
+    <ENTRY>192.168.1/24</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>select '192.168'::cidr</ENTRY>
+    <ENTRY>192.168.0/24</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>select '128.1'::cidr</ENTRY>
+    <ENTRY>128.1/16</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>select '128':::cidr</ENTRY>
+    <ENTRY>128.0/16</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>select '128.1.2'::cidr</ENTRY>
+    <ENTRY>128.1.2/24</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>select '10.1.2'::cidr</ENTRY>
+    <ENTRY>10.1.2/24</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>select '10.1'::cidr</ENTRY>
+    <ENTRY>10.1/16</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY>select '10'::cidr</ENTRY>
+    <ENTRY>10/8</ENTRY>
+  </ROW>
+</TBODY>
+</TGROUP>
+</TABLE>
+</Para>
+
+<Sect2>
+<Title><type>inet</type> for IP Networks</Title>
+
+<Para>
+The inet type is designed to hold, in one field, all of the information
+about a host including the CIDR style subnet that it is in.
+Note that if you want to store proper CIDR networks, see the cidr type.
+The inet type is similar to the cidr 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 function is "x.x.x.x/y" where "x.x.x.x" is
+an internet host and y is the number of bits in the netmask.
+If the "/y" part is left off, it is treated as "/32."
+On output, the "/y" part is not printed if it is /32.
+This allows the type to be used as a straight host type by just leaving of
+the bits part.
+</Sect1>
+
+</chapter>
\ No newline at end of file
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index d72170e2788..a1103964f8d 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -624,5 +624,64 @@ support functions.
 </TABLE>
 </Para>
 
+<sect1>
+<title id="cidr-funcs">IP V4 Functions</title>
+
+<Para>
+<TABLE TOCENTRY="1">
+<TITLE><ProductName>Postgres</ProductName>IP V4 Functions</TITLE>
+<TGROUP COLS="4">
+<THEAD>
+  <ROW>
+    <ENTRY>Function</ENTRY>
+    <ENTRY>Returns</ENTRY>
+    <ENTRY>Description</ENTRY>
+    <ENTRY>Example</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') ==> '192.168.1.255' </ENTRY>
+  </ROW>
+  <ROW>
+<ENTRY> broadcast(inet) </ENTRY>
+<ENTRY> text </ENTRY>
+<ENTRY> construct broadcast address as text </ENTRY>
+<ENTRY> broadcast('192.168.1.5/24') ==> '192.168.1.255' </ENTRY>
+  </ROW>
+  <ROW>
+<ENTRY> host(inet) </ENTRY>
+<ENTRY> text </ENTRY>
+<ENTRY> extract host address as text </ENTRY>
+<ENTRY> host('192.168.1.5/24') ==> '192.168.1.5' </ENTRY>
+  </ROW>
+  <ROW>
+<ENTRY> masklen(cidr) </ENTRY>
+<ENTRY> int4 </ENTRY>
+<ENTRY> calculate netmask length </ENTRY>
+<ENTRY> masklen('192.168.1.5/24') ==> 24</ENTRY>
+  </ROW>
+  <ROW>
+<ENTRY> masklen(inet) </ENTRY>
+<ENTRY> int4 </ENTRY>
+<ENTRY> calculate netmask length </ENTRY>
+<ENTRY> masklen('192.168.1.5/24') ==> 24 </ENTRY>
+  </ROW>
+  <ROW>
+<ENTRY> netmask(inet) </ENTRY>
+<ENTRY> text </ENTRY>
+<ENTRY> construct netmask as text </ENTRY>
+<ENTRY> netmask('192.168.1.5/24') ==> '255.255.255.0' </ENTRY>
+  </ROW>
+</TBODY>
+</TGROUP>
+</TABLE>
+</Para>
+
+</Sect1>
+
 </chapter>
 
diff --git a/doc/src/sgml/oper.sgml b/doc/src/sgml/oper.sgml
index 69834fb15e6..2c865ba9059 100644
--- a/doc/src/sgml/oper.sgml
+++ b/doc/src/sgml/oper.sgml
@@ -32,6 +32,25 @@ oprleft|oprright|oprresult|oprcode
 </ProgramListing>
 </Para>
 
+<Para>
+Users may invoke operators using the operator name, as in:
+
+<ProgramListing>
+select * from emp where salary < 40000;
+</ProgramListing>
+
+Alternatively, users may call the functions that implement the
+operators directly.  In this case, the query above would be expressed
+as:
+<ProgramListing>
+select * from emp where int4lt(salary, 40000);
+</ProgramListing>
+
+<Para>
+<Application>psql</Application>
+has a command (<Command>\dd</Command>) to show these operators.
+
+
 <sect1>
 <title>Lexical Precedence</title>
 
@@ -633,23 +652,149 @@ are several operators for this type.
 </TABLE>
 </Para>
 
+<Sect1>
+<title id="cidr-opers">IP V4 Operators</title>
 
 <Para>
-Users may invoke operators using the operator name, as in:
-
-<ProgramListing>
-select * from emp where salary < 40000;
-</ProgramListing>
+<TABLE TOCENTRY="1">
+<TITLE><ProductName>Postgres</ProductName>IP V4 Operators</TITLE>
+<TITLEABBREV>Operators</TITLEABBREV>
+<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>
+</Para>
+</Sect1>
 
-Alternatively, users may call the functions that implement the
-operators directly.  In this case, the query above would be expressed
-as:
-<ProgramListing>
-select * from emp where int4lt(salary, 40000);
-</ProgramListing>
+<Sect1>
+<title id="inet-opers">IP V4 Operators</title>
 
 <Para>
-<Application>psql</Application>
-has a command (<Command>\dd</Command>) to show these operators.
+<TABLE TOCENTRY="1">
+<TITLE><ProductName>Postgres</ProductName>IP V4 Operators</TITLE>
+<TITLEABBREV>Operators</TITLEABBREV>
+<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'::inet &lt; '192.168.1.6'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> &lt;= </ENTRY>
+    <ENTRY>Less than or equal</ENTRY>
+    <ENTRY>'192.168.1.5'::inet &lt;= '192.168.1.5'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> = </ENTRY>
+    <ENTRY>Equals</ENTRY>
+    <ENTRY>'192.168.1.5'::inet = '192.168.1.5'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> %gt;= </ENTRY>
+    <ENTRY>Greater or equal</ENTRY>
+    <ENTRY>'192.168.1.5'::inet &gt;= '192.168.1.5'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> %gt; </ENTRY>
+    <ENTRY>Greater</ENTRY>
+    <ENTRY>'192.168.1.5'::inet %gt; '192.168.1.4'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> &lt;&gt; </ENTRY>
+    <ENTRY>Not equal</ENTRY>
+    <ENTRY>'192.168.1.5'::inet &lt;&gt; '192.168.1.4'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> &lt;&lt; </ENTRY>
+    <ENTRY>is contained within</ENTRY>
+    <ENTRY>'192.168.1.5'::inet &lt;&lt; '192.168.1/24'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> &lt;&lt;= </ENTRY>
+    <ENTRY>is contained within or equals</ENTRY>
+    <ENTRY>'192.168.1/24'::inet &lt;&lt;= '192.168.1/24'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> &gt;&gt; </ENTRY>
+    <ENTRY>contains</ENTRY>
+    <ENTRY>'192.168.1/24'::inet &gt;&gt; '192.168.1.5'::inet</ENTRY>
+  </ROW>
+  <ROW>
+    <ENTRY> &gt;&gt;= </ENTRY>
+    <ENTRY>contains or equals</ENTRY>
+    <ENTRY>'192.168.1/24'::inet &gt;&gt;= '192.168.1/24'::inet</ENTRY>
+  </ROW>
+</TBODY>
+</TGROUP>
+</TABLE>
+</Para>
+</Sect1>
+
 </Chapter>