Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit e9f10b2

Browse files
author
Thomas G. Lockhart
committed
Include new cidr and inet data types.
1 parent 866104b commit e9f10b2

File tree

3 files changed

+391
-25
lines changed

3 files changed

+391
-25
lines changed

‎doc/src/sgml/datatype.sgml

+174-12
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,11 @@ several possibilities for formats, such as date and time types.
5858
<ENTRY>character(n)</ENTRY>
5959
<ENTRY>fixed-length character string</ENTRY>
6060
</ROW>
61+
<ROW>
62+
<ENTRY>cidr</ENTRY>
63+
<ENTRY></ENTRY>
64+
<ENTRY>IP version 4 network or host address</ENTRY>
65+
</ROW>
6166
<ROW>
6267
<ENTRY>circle</ENTRY>
6368
<ENTRY></ENTRY>
@@ -78,6 +83,11 @@ several possibilities for formats, such as date and time types.
7883
<ENTRY>real, double precision</ENTRY>
7984
<ENTRY>double-precision floating-point number</ENTRY>
8085
</ROW>
86+
<ROW>
87+
<ENTRY>inet</ENTRY>
88+
<ENTRY></ENTRY>
89+
<ENTRY>IP version 4 network or host address</ENTRY>
90+
</ROW>
8191
<ROW>
8292
<ENTRY>int2</ENTRY>
8393
<ENTRY>smallint</ENTRY>
@@ -163,6 +173,14 @@ several possibilities for formats, such as date and time types.
163173
</TABLE>
164174
</Para>
165175

176+
<para>
177+
<note>
178+
<para>
179+
The <type>cidr</type> and <type>inet</type> types are designed to handle any IP type
180+
but only ipv4 is handled in the current implementation.
181+
Everything here that talks about ipv4 will apply to ipv6 in a future release.
182+
</note>
183+
166184
<Para>
167185
<TABLE TOCENTRY="1">
168186
<TITLE><ProductName>Postgres</ProductName> Function Constants</TITLE>
@@ -500,17 +518,21 @@ This is set at compile time and may change in a future release.
500518

501519
<Para>
502520
There are two fundamental kinds of date and time measurements:
503-
clock time and time interval.
504-
Both quantities have continuity and smoothness, as does time itself.
521+
absolute clock times and relative time intervals.
522+
Both quantities should demonstrate continuity and smoothness, as does time itself.
505523
<ProductName>Postgres</ProductName> supplies two primary user-oriented
506524
date and time types,
507-
<Type>datetime</Type> and timespan, as well as
508-
the related <acronym>SQL92</acronym> types date and time.
525+
<Type>datetime</Type> and <Type>timespan</Type>, as well as
526+
the related <acronym>SQL92</acronym> types <Type>timestamp</Type>,
527+
<Type>interval</Type>,
528+
<Type>date</Type> and <Type>time</Type>.
509529
</Para>
510530

511531
<Para>
512-
Other date and time types are available
513-
also, mostly
532+
In a future release, <Type>datetime</Type> and <Type>timespan</Type> are likely
533+
to merge with the <acronym>SQL92</acronym> types <Type>timestamp</Type>,
534+
<Type>interval</Type>.
535+
Other date and time types are also available, mostly
514536
for historical reasons.
515537
</Para>
516538

@@ -579,6 +601,9 @@ for historical reasons.
579601
</TBODY>
580602
</TGROUP>
581603
</TABLE>
604+
605+
<type>timestamp</type> is currently implemented separately from
606+
<type>datetime</type>, although they share input and output routines.
582607
</Para>
583608

584609
<Para>
@@ -652,13 +677,26 @@ for historical reasons.
652677
<ProductName>Postgres</ProductName> endevours to be compatible with
653678
<Acronym>SQL92</Acronym> definitions for typical usage.
654679
The <Acronym>SQL92</Acronym> standard has an odd mix of date and
655-
time types and capabilities. For example, although the date type
680+
time types and capabilities. Two obvious problems are:
681+
682+
<itemizedlist>
683+
<listitem>
684+
<para>
685+
Although the <type>date</type> type
656686
does not have an associated time zone, the
657-
time type can. The default time zone is specified as a constant offset
658-
from GMT/UTC;
659-
however, time zones in the real world can have no meaning unless
660-
associated with a date as well
661-
as a time since the offset will vary through the year.
687+
<type>time</type> type can or does.
688+
689+
<listitem>
690+
<para>
691+
The default time zone is specified as a constant integer offset
692+
from GMT/UTC.
693+
694+
</itemizedlist>
695+
696+
However, time zones in the real world can have no meaning unless
697+
associated with a date as well as a time
698+
since the offset may vary through the year with daylight savings
699+
time boundaries.
662700

663701
<Para>
664702
To address these difficulties, <ProductName>Postgres</ProductName>
@@ -1412,3 +1450,127 @@ Circles are output using the first syntax.
14121450

14131451
</Sect1>
14141452

1453+
<Sect1>
1454+
<Title>IP Version 4 Networks and Host Addresses</Title>
1455+
1456+
<Para>
1457+
The <Type>cidr</Type> type stores networks specified
1458+
in <acronym>CIDR</acronym> notation.
1459+
The <Type>inet</Type> type stores hosts and networks in CIDR notation.
1460+
</Para>
1461+
1462+
<Para>
1463+
<TABLE TOCENTRY="1">
1464+
<TITLE><ProductName>Postgres</ProductName>IP Version 4 Type</TITLE>
1465+
<TITLEABBREV>IPV4</TITLEABBREV>
1466+
<TGROUP COLS="4">
1467+
<THEAD>
1468+
<ROW>
1469+
<ENTRY>IPV4 Type</ENTRY>
1470+
<ENTRY>Storage</ENTRY>
1471+
<ENTRY>Description</ENTRY>
1472+
<ENTRY>Range</ENTRY>
1473+
</ROW>
1474+
</THEAD>
1475+
<TBODY>
1476+
<ROW>
1477+
<ENTRY>cidr</ENTRY>
1478+
<ENTRY>variable</ENTRY>
1479+
<ENTRY>CIDR networks</ENTRY>
1480+
<ENTRY>Valid IPV4 CIDR blocks</ENTRY>
1481+
</ROW>
1482+
<ROW>
1483+
<ENTRY>inet</ENTRY>
1484+
<ENTRY>variable</ENTRY>
1485+
<ENTRY>nets and hosts</ENTRY>
1486+
<ENTRY>Valid IPV4 CIDR blocks</ENTRY>
1487+
</ROW>
1488+
</TBODY>
1489+
</TGROUP>
1490+
</TABLE>
1491+
</Para>
1492+
1493+
<Sect2>
1494+
<Title><type>inet</type> for IP Networks</Title>
1495+
1496+
<Para>
1497+
The cidr type holds a CIDR network.
1498+
The format for specifying networks is "x.x.x.x/y" where "x.x.x.x" is the
1499+
network and "/y" is the number of bits in the netmask.
1500+
If the "/y" part is left off, it is calculated using assumptions from
1501+
the old class system except that it is extended to include at least
1502+
all of the octets in the input.
1503+
Here are some examples.
1504+
1505+
<!-- There's a lot of examples here.
1506+
-- Take some out if you think there are too many...
1507+
-->
1508+
1509+
<Para>
1510+
<TABLE TOCENTRY="1">
1511+
<TGROUP COLS="4">
1512+
<THEAD>
1513+
<ROW>
1514+
<ENTRY>Input</ENTRY>
1515+
<ENTRY>Output</ENTRY>
1516+
</THEAD>
1517+
<TBODY>
1518+
<ROW>
1519+
<ENTRY>select '192.168.1'::cidr</ENTRY>
1520+
<ENTRY>192.168.1/24</ENTRY>
1521+
</ROW>
1522+
<ROW>
1523+
<ENTRY>select '192.168'::cidr</ENTRY>
1524+
<ENTRY>192.168.0/24</ENTRY>
1525+
</ROW>
1526+
<ROW>
1527+
<ENTRY>select '128.1'::cidr</ENTRY>
1528+
<ENTRY>128.1/16</ENTRY>
1529+
</ROW>
1530+
<ROW>
1531+
<ENTRY>select '128':::cidr</ENTRY>
1532+
<ENTRY>128.0/16</ENTRY>
1533+
</ROW>
1534+
<ROW>
1535+
<ENTRY>select '128.1.2'::cidr</ENTRY>
1536+
<ENTRY>128.1.2/24</ENTRY>
1537+
</ROW>
1538+
<ROW>
1539+
<ENTRY>select '10.1.2'::cidr</ENTRY>
1540+
<ENTRY>10.1.2/24</ENTRY>
1541+
</ROW>
1542+
<ROW>
1543+
<ENTRY>select '10.1'::cidr</ENTRY>
1544+
<ENTRY>10.1/16</ENTRY>
1545+
</ROW>
1546+
<ROW>
1547+
<ENTRY>select '10'::cidr</ENTRY>
1548+
<ENTRY>10/8</ENTRY>
1549+
</ROW>
1550+
</TBODY>
1551+
</TGROUP>
1552+
</TABLE>
1553+
</Para>
1554+
1555+
<Sect2>
1556+
<Title><type>inet</type> for IP Networks</Title>
1557+
1558+
<Para>
1559+
The inet type is designed to hold, in one field, all of the information
1560+
about a host including the CIDR style subnet that it is in.
1561+
Note that if you want to store proper CIDR networks, see the cidr type.
1562+
The inet type is similar to the cidr type except that the bits in the
1563+
host part can be non-zero.
1564+
Functions exist to extract the various elements of the field.
1565+
</Para>
1566+
1567+
<Para>
1568+
The input format for this function is "x.x.x.x/y" where "x.x.x.x" is
1569+
an internet host and y is the number of bits in the netmask.
1570+
If the "/y" part is left off, it is treated as "/32."
1571+
On output, the "/y" part is not printed if it is /32.
1572+
This allows the type to be used as a straight host type by just leaving of
1573+
the bits part.
1574+
</Sect1>
1575+
1576+
</chapter>

‎doc/src/sgml/func.sgml

+59
Original file line numberDiff line numberDiff line change
@@ -624,5 +624,64 @@ support functions.
624624
</TABLE>
625625
</Para>
626626

627+
<sect1>
628+
<title id="cidr-funcs">IP V4 Functions</title>
629+
630+
<Para>
631+
<TABLE TOCENTRY="1">
632+
<TITLE><ProductName>Postgres</ProductName>IP V4 Functions</TITLE>
633+
<TGROUP COLS="4">
634+
<THEAD>
635+
<ROW>
636+
<ENTRY>Function</ENTRY>
637+
<ENTRY>Returns</ENTRY>
638+
<ENTRY>Description</ENTRY>
639+
<ENTRY>Example</ENTRY>
640+
</ROW>
641+
</THEAD>
642+
<TBODY>
643+
<ROW>
644+
<ENTRY> broadcast(cidr) </ENTRY>
645+
<ENTRY> text </ENTRY>
646+
<ENTRY> construct broadcast address as text </ENTRY>
647+
<ENTRY> broadcast('192.168.1.5/24') ==> '192.168.1.255' </ENTRY>
648+
</ROW>
649+
<ROW>
650+
<ENTRY> broadcast(inet) </ENTRY>
651+
<ENTRY> text </ENTRY>
652+
<ENTRY> construct broadcast address as text </ENTRY>
653+
<ENTRY> broadcast('192.168.1.5/24') ==> '192.168.1.255' </ENTRY>
654+
</ROW>
655+
<ROW>
656+
<ENTRY> host(inet) </ENTRY>
657+
<ENTRY> text </ENTRY>
658+
<ENTRY> extract host address as text </ENTRY>
659+
<ENTRY> host('192.168.1.5/24') ==> '192.168.1.5' </ENTRY>
660+
</ROW>
661+
<ROW>
662+
<ENTRY> masklen(cidr) </ENTRY>
663+
<ENTRY> int4 </ENTRY>
664+
<ENTRY> calculate netmask length </ENTRY>
665+
<ENTRY> masklen('192.168.1.5/24') ==> 24</ENTRY>
666+
</ROW>
667+
<ROW>
668+
<ENTRY> masklen(inet) </ENTRY>
669+
<ENTRY> int4 </ENTRY>
670+
<ENTRY> calculate netmask length </ENTRY>
671+
<ENTRY> masklen('192.168.1.5/24') ==> 24 </ENTRY>
672+
</ROW>
673+
<ROW>
674+
<ENTRY> netmask(inet) </ENTRY>
675+
<ENTRY> text </ENTRY>
676+
<ENTRY> construct netmask as text </ENTRY>
677+
<ENTRY> netmask('192.168.1.5/24') ==> '255.255.255.0' </ENTRY>
678+
</ROW>
679+
</TBODY>
680+
</TGROUP>
681+
</TABLE>
682+
</Para>
683+
684+
</Sect1>
685+
627686
</chapter>
628687

0 commit comments

Comments
 (0)