projects / postgresql.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: ab7646f)
Doc: update section 9.12 for new function table layout.
authorTom Lane
Thu, 23 Apr 2020 19:12:42 +0000 (15:12 -0400)
committerTom Lane
Thu, 23 Apr 2020 19:12:42 +0000 (15:12 -0400)
Also rearrange that page a bit for more consistency and less
duplication.

In passing, fix erroneous examples of the results of abbrev(cidr)
in datatype.sgml, and do a bit of copy-editing there.

doc/src/sgml/datatype.sgml patch | blob | blame | history
doc/src/sgml/func.sgml patch | blob | blame | history

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index c2e42f31c0062e7a2b70c65cd02e29c1584e2a84..22eda0f4e9ed4f65abbbf09da4ac5b6a0bea92b1 100644 (file)
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2854,7 +2854,7 @@ SELECT EXTRACT(days from '80 hours'::interval);
           iso_8601
           P1Y2M
           P3DT4H5M6S
-          P-1Y-2M3DT-4H-5M-6S
+          P-1Y-2M3D&zwsp;T-4H-5M-6S
          
         
        
@@ -3559,8 +3559,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
       y
       is the number of bits in the netmask.  If the
       /y
-      portion is missing, the
-      netmask is 32 for IPv4 and 128 for IPv6, so the value represents
+      portion is omitted, the
+      netmask is taken to be 32 for IPv4 or 128 for IPv6,
+      so the value represents
       just a single host.  On display, the
       /y
       portion is suppressed if the netmask specifies a single host.
@@ -3580,7 +3581,8 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
      conventions.
      The format for specifying networks is 
      class="parameter">address/y where 
-     class="parameter">address is the network represented as an
+     class="parameter">address is the network's lowest
+     address represented as an
      IPv4 or IPv6 address, and 
      class="parameter">y is the number of bits in the netmask.  If
      y is omitted, it is calculated
@@ -3668,12 +3670,12 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
         
          2001:4f8:3:ba::/64
          2001:4f8:3:ba::/64
-         2001:4f8:3:ba::/64
+         2001:4f8:3:ba/64
         
         
-         2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128
-         2001:4f8:3:ba:2e0:81ff:fe22:d1f1/128
-         2001:4f8:3:ba:2e0:81ff:fe22:d1f1
+         2001:4f8:3:ba:&zwsp;2e0:81ff:fe22:d1f1/128
+         2001:4f8:3:ba:&zwsp;2e0:81ff:fe22:d1f1/128
+         2001:4f8:3:ba:&zwsp;2e0:81ff:fe22:d1f1/128
         
         
          ::ffff:1.2.3.0/120
@@ -3738,7 +3740,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
       '08002b010203'
      
 
-     These examples would all specify the same address.  Upper and
+     These examples all specify the same address.  Upper and
      lower case is accepted for the digits
      a through f.  Output is always in the
      first of the forms shown.
@@ -3805,14 +3807,17 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
       '08002b0102030405'
      
 
-     These examples would all specify the same address.  Upper and
+     These examples all specify the same address.  Upper and
      lower case is accepted for the digits
      a through f.  Output is always in the
      first of the forms shown.
+    
 
-     The last six input formats that are mentioned above are not part
-     of any standard.
+    
+     The last six input formats shown above are not part of any standard.
+    
 
+    
      To convert a traditional 48 bit MAC address in EUI-48 format to
      modified EUI-64 format to be included as the host portion of an
      IPv6 address, use macaddr8_set7bit as shown:
@@ -4655,7 +4660,8 @@ SELECT * FROM pg_attribute
         regoperator
         pg_operator
         operator with argument types
-        *(integer,integer) or -(NONE,integer)
+        *(integer,&zwsp;integer)
+         or -(NONE,&zwsp;integer)
        
 
        
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 63b870de04898731fccc15d4122d999c79e35c73..606defc51572dd0c8087f828503f45a07f192ef2 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10558,418 +10558,512 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
   Network Address Functions and Operators
 
   
-    shows the operators
-   available for the cidr and inet types.
-   The operators <<,
-   <<=, >>,
-   >>=, and &&
-   test for subnet inclusion.  They
-   consider only the network parts of the two addresses (ignoring any
-   host part) and determine whether one network is identical to
-   or a subnet of the other.
+   The IP network address types, cidr and inet,
+   support the usual comparison operators shown in
+   
+   as well as the specialized operators and functions shown in
+    and
+   .
   
 
-    
-     <type>cidr</type> and <type>inet</type> Operators
-     
-      
-       
-        Operator
-        Description
-        Example
-       
-      
-      
-       
-         < 
-        is less than
-        inet '192.168.1.5' < inet '192.168.1.6'
-       
-       
-         <= 
-        is less than or equal
-        inet '192.168.1.5' <= inet '192.168.1.5'
-       
-       
-         = 
-        equals
-        inet '192.168.1.5' = inet '192.168.1.5'
-       
-       
-         >= 
-        is greater or equal
-        inet '192.168.1.5' >= inet '192.168.1.5'
-       
-       
-         > 
-        is greater than
-        inet '192.168.1.5' > inet '192.168.1.4'
-       
-       
-         <> 
-        is not equal
-        inet '192.168.1.5' <> inet '192.168.1.4'
-       
-       
-         << 
-        is contained by
-        inet '192.168.1.5' << inet '192.168.1/24'
-       
-       
-         <<= 
-        is contained by or equals
-        inet '192.168.1/24' <<= inet '192.168.1/24'
-       
-       
-         >> 
-        contains
-        inet '192.168.1/24' >> inet '192.168.1.5'
-       
-       
-         >>= 
-        contains or equals
-        inet '192.168.1/24' >>= inet '192.168.1/24'
-       
-       
-         && 
-        contains or is contained by
-        inet '192.168.1/24' && inet '192.168.1.80/28'
-       
-       
-         ~ 
-        bitwise NOT
-        ~ inet '192.168.1.6'
-       
-       
-         & 
-        bitwise AND
-        inet '192.168.1.6' & inet '0.0.0.255'
-       
-       
-         | 
-        bitwise OR
-        inet '192.168.1.6' | inet '0.0.0.255'
-       
-       
-         + 
-        addition
-        inet '192.168.1.6' + 25
-       
-       
-         - 
-        subtraction
-        inet '192.168.1.43' - 36
-       
-       
-         - 
-        subtraction
-        inet '192.168.1.43' - inet '192.168.1.19'
-       
-      
-     
-    
-
   
-    shows the functions
-   available for use with the cidr and inet
-   types.  The abbrev, host,
-   and text
-   functions are primarily intended to offer alternative display
-   formats.
+   Any cidr value can be cast to inet implicitly;
+   therefore, the operators and functions shown below as operating on
+   inet also work on cidr values.  (Where there are
+   separate functions for inet and cidr, it is
+   because the behavior should be different for the two cases.)
+   Also, it is permitted to cast an inet value
+   to cidr.  When this is done, any bits to the right of the
+   netmask are silently zeroed to create a valid cidr value.
   
 
-    
-     <type>cidr</type> and <type>inet</type> Functions
-     
-      
-       
-        Function
-        Return Type
-        Description
-        Example
-        Result
-       
-      
-      
-       
-        
-         
-          abbrev
-         
-         abbrev(inet)
-        
-        text
-        abbreviated display format as text
-        abbrev(inet '10.1.0.0/16')
-        10.1.0.0/16
-       
-       
-        abbrev(cidr)
-        text
-        abbreviated display format as text
-        abbrev(cidr '10.1.0.0/16')
-        10.1/16
-       
-       
-        
-         
-          broadcast
-         
-         broadcast(inet)
-        
-        inet
-        broadcast address for network
-        broadcast('192.168.1.5/24')
-        192.168.1.255/24
-       
-       
-        
-         
-          family
-         
-         family(inet)
-        
-        int
-        extract family of address; 4 for IPv4,
-         6 for IPv6
-        family('::1')
-        6
-       
-       
-        
-         
-          host
-         
-         host(inet)
-        
-        text
-        extract IP address as text
-        host('192.168.1.5/24')
-        192.168.1.5
-       
-       
-        
-         
-          hostmask
-         
-         hostmask(inet)
-        
-        inet
-        construct host mask for network
-        hostmask('192.168.23.20/30')
-        0.0.0.3
-       
-       
-        
-         
-          masklen
-         
-         masklen(inet)
-        
-        int
-        extract netmask length
-        masklen('192.168.1.5/24')
-        24
-       
-       
-        
-         
-          netmask
-         
-         netmask(inet)
-        
-        inet
-        construct netmask for network
-        netmask('192.168.1.5/24')
-        255.255.255.0
-       
-       
-        
-         
-          network
-         
-         network(inet)
-        
-        cidr
-        extract network part of address
-        network('192.168.1.5/24')
-        192.168.1.0/24
-       
-       
-        
-         
-          set_masklen
-         
-         set_masklen(inet, int)
-        
-        inet
-        set netmask length for inet value
-        set_masklen('192.168.1.5/24', 16)
-        192.168.1.5/16
-       
-       
-        set_masklen(cidr, int)
-        cidr
-        set netmask length for cidr value
-        set_masklen('192.168.1.0/24'::cidr, 16)
-        192.168.0.0/16
-       
-       
-        
-         
-          text
-         
-         text(inet)
-        
-        text
-        extract IP address and netmask length as text
-        text(inet '192.168.1.5')
-        192.168.1.5/32
-       
-       
-        
-         
-          inet_same_family
-         
-         inet_same_family(inet, inet)
-        
-        boolean
-        are the addresses from the same family?
-        inet_same_family('192.168.1.5/24', '::1')
-        false
-       
-       
-        
-         
-          inet_merge
-         
-         inet_merge(inet, inet)
-        
-        cidr
-        the smallest network which includes both of the given networks
-        inet_merge('192.168.1.5/24', '192.168.2.5/24')
-        192.168.0.0/22
-       
-      
-     
-    
+   
+    IP Address Operators
+    
+     
+      
+       
+        OperatorDescriptionExample(s)
+       
+      
+     
 
-  
-   Any cidr value can be cast to inet implicitly
-   or explicitly; therefore, the functions shown above as operating on
-   inet also work on cidr values.  (Where there are
-   separate functions for inet and cidr, it is because
-   the behavior should be different for the two cases.)
-   Also, it is permitted to cast an inet value to cidr.
-   When this is done, any bits to the right of the netmask are silently zeroed
-   to create a valid cidr value.
-   In addition,
-   you can cast a text value to inet or cidr
-   using normal casting syntax: for example,
-   inet(expression) or
-   colname::cidr.
-  
+     
+      
+       
+        inet << inet
+        boolean
+       
+        Is subnet strictly contained by subnet?
+        This operator, and the next four, test for subnet inclusion.  They
+        consider only the network parts of the two addresses (ignoring any
+        bits to the right of the netmasks) and determine whether one network
+        is identical to or a subnet of the other.
+       
+        inet '192.168.1.5' << inet '192.168.1/24'
+        t
+       
+        inet '192.168.0.5' << inet '192.168.1/24'
+        f
+       
+        inet '192.168.1/24' << inet '192.168.1/24'
+        f
+       
+      
 
-  
-    shows the functions
-   available for use with the macaddr type.  The function
-   trunc(macaddr) returns a MAC
-   address with the last 3 bytes set to zero.  This can be used to
-   associate the remaining prefix with a manufacturer.
-  
+      
+       
+        inet <<= inet
+        boolean
+       
+        Is subnet contained by or equal to subnet?
+       
+        inet '192.168.1/24' <<= inet '192.168.1/24'
+        t
+       
+      
 
-    
-     <type>macaddr</type> Functions
-     
-      
-       
-        Function
-        Return Type
-        Description
-        Example
-        Result
-       
-      
-      
-       
-        
-         
-          trunc
-         
-         trunc(macaddr)
-        
-        macaddr
-        set last 3 bytes to zero
-        trunc(macaddr '12:34:56:78:90:ab')
-        12:34:56:00:00:00
-       
-      
-     
-    
+      
+       
+        inet >> inet
+        boolean
+       
+        Does subnet strictly contain subnet?
+       
+        inet '192.168.1/24' >> inet '192.168.1.5'
+        t
+       
+      
+
+      
+       
+        inet >>= inet
+        boolean
+       
+        Does subnet contain or equal subnet?
+       
+        inet '192.168.1/24' >>= inet '192.168.1/24'
+        t
+       
+      
+
+      
+       
+        inet && inet
+        boolean
+       
+        Does either subnet contain or equal the other?
+       
+        inet '192.168.1/24' && inet '192.168.1.80/28'
+        t
+       
+        inet '192.168.1/24' && inet '192.168.2.0/28'
+        f
+       
+      
+
+      
+       
+        ~ inet
+        inet
+       
+        Computes bitwise NOT.
+       
+        ~ inet '192.168.1.6'
+        63.87.254.249
+       
+      
 
+      
+       
+        inet & inet
+        inet
+       
+        Computes bitwise AND.
+       
+        inet '192.168.1.6' & inet '0.0.0.255'
+        0.0.0.6
+       
+      
+
+      
+       
+        inet | inet
+        inet
+       
+        Computes bitwise OR.
+       
+        inet '192.168.1.6' | inet '0.0.0.255'
+        192.168.1.255
+       
+      
+
+      
+       
+        inet + bigint
+        inet
+       
+        Adds an offset to an address.
+       
+        inet '192.168.1.6' + 25
+        192.168.1.31
+       
+      
+
+      
+       
+        bigint + inet
+        inet
+       
+        Adds an offset to an address.
+       
+        200 + inet '::ffff:fff0:1'
+        ::ffff:255.240.0.201
+       
+      
+
+      
+       
+        inet - bigint
+        inet
+       
+        Subtracts an offset from an address.
+       
+        inet '192.168.1.43' - 36
+        192.168.1.7
+       
+      
+
+      
+       
+        inet - inet
+        bigint
+       
+        Computes the difference of two addresses.
+       
+        inet '192.168.1.43' - inet '192.168.1.19'
+        24
+       
+        inet '::1' - inet '::ffff:1'
+        -4294901760
+       
+      
+     
+    
+   
+
+   
+    IP Address Functions
+    
+     
+      
+       
+        FunctionDescriptionExample(s)
+       
+      
+     
+
+     
+      
+       
+        
+         abbrev
+        
+        abbrev ( inet )
+        text
+       
+        Creates an abbreviated display format as text.
+        (The result is the same as the inet output function
+        produces; it is abbreviated only in comparison to the
+        result of an explicit cast to text, which for historical
+        reasons will never suppress the netmask part.)
+       
+        abbrev(inet '10.1.0.0/32')
+        10.1.0.0
+       
+      
+
+      
+       
+        abbrev ( cidr )
+        text
+       
+        Creates an abbreviated display format as text.
+        (The abbreviation consists of dropping all-zero octets to the right
+        of the netmask; more examples are in
+        .)
+       
+        abbrev(cidr '10.1.0.0/16')
+        10.1/16
+       
+      
+
+      
+       
+        
+         broadcast
+        
+        broadcast ( inet )
+        inet
+       
+        Computes the broadcast address for the address's network.
+       
+        broadcast(inet '192.168.1.5/24')
+        192.168.1.255/24
+       
+      
+
+      
+       
+        
+         family
+        
+        family ( inet )
+        integer
+       
+        Returns the address's family: 4 for IPv4,
+        6 for IPv6.
+       
+        family(inet '::1')
+        6
+       
+      
+
+      
+       
+        
+         host
+        
+        host ( inet )
+        text
+       
+        Returns the IP address as text, ignoring the netmask.
+       
+        host(inet '192.168.1.0/24')
+        192.168.1.0
+       
+      
+
+      
+       
+        
+         hostmask
+        
+        hostmask ( inet )
+        inet
+       
+        Computes the host mask for the address's network.
+       
+        hostmask(inet '192.168.23.20/30')
+        0.0.0.3
+       
+      
+
+      
+       
+        
+         inet_merge
+        
+        inet_merge ( inet, inet )
+        cidr
+       
+        Computes the smallest network that includes both of the given networks.
+       
+        inet_merge(inet '192.168.1.5/24', inet '192.168.2.5/24')
+        192.168.0.0/22
+       
+      
+
+      
+       
+        
+         inet_same_family
+        
+        inet_same_family ( inet, inet )
+        boolean
+       
+        Tests whether the addresses belong to the same IP family.
+       
+        inet_same_family(inet '192.168.1.5/24', inet '::1')
+        f
+       
+      
+
+      
+       
+        
+         masklen
+        
+        masklen ( inet )
+        integer
+       
+        Returns the netmask length in bits.
+       
+        masklen(inet '192.168.1.5/24')
+        24
+       
+      
+
+      
+       
+        
+         netmask
+        
+        netmask ( inet )
+        inet
+       
+        Computes the network mask for the address's network.
+       
+        netmask(inet '192.168.1.5/24')
+        255.255.255.0
+       
+      
+
+      
+       
+        
+         network
+        
+        network ( inet )
+        cidr
+       
+        Returns the network part of the address, zeroing out
+        whatever is to the right of the netmask.
+        (This is equivalent to casting the value to cidr.)
+       
+        network(inet '192.168.1.5/24')
+        192.168.1.0/24
+       
+      
+
+      
+       
+        
+         set_masklen
+        
+        set_masklen ( inet, integer )
+        inet
+       
+        Sets the netmask length for an inet value.
+        The address part does not change.
+       
+        set_masklen(inet '192.168.1.5/24', 16)
+        192.168.1.5/16
+       
+      
+
+      
+       
+        set_masklen ( cidr, integer )
+        cidr
+       
+        Sets the netmask length for a cidr value.
+        Address bits to the right of the new netmask are set to zero.
+       
+        set_masklen(cidr '192.168.1.0/24', 16)
+        192.168.0.0/16
+       
+      
+
+      
+       
+        
+         text
+        
+        text ( inet )
+        text
+       
+        Returns the unabbreviated IP address and netmask length as text.
+        (This has the same result as an explicit cast to text.)
+       
+        text(inet '192.168.1.5')
+        192.168.1.5/32
+       
+      
+     
+    
+   
+
+  
    
-    The macaddr type also supports the standard relational
-    operators (>, <=, etc.) for
-    lexicographical ordering, and the bitwise arithmetic operators
-    (~, & and |)
-    for NOT, AND and OR.
+    The abbrev, host,
+    and text functions are primarily intended to offer
+    alternative display formats for IP addresses.
    
+  
 
-   
-    shows the functions
-   available for use with the macaddr8 type.  The function
-   trunc(macaddr8) returns a MAC
-   address with the last 5 bytes set to zero.  This can be used to
-   associate the remaining prefix with a manufacturer.
+  
+   The MAC address types, macaddr and macaddr8,
+   support the usual comparison operators shown in
+   
+   as well as the specialized functions shown in
+   .
+   In addition, they support the bitwise logical operators
+   ~, & and |
+   (NOT, AND and OR), just as shown above for IP addresses.
   
 
-    
-     <type>macaddr8</type> Functions
-     
-      
-       
-        Function
-        Return Type
-        Description
-        Example
-        Result
-       
-      
-      
-       
-        
-         
-          trunc
-         
-         trunc(macaddr8)
-        
-        macaddr8
-        set last 5 bytes to zero
-        trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')
-        12:34:56:00:00:00:00:00
-       
-       
-        
-         
-          macaddr8_set7bit
-         
-         macaddr8_set7bit(macaddr8)
-        
-        macaddr8
-        set 7th bit to one, also known as modified EUI-64, for inclusion in an IPv6 address
-        macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')
-        02:34:56:ff:fe:ab:cd:ef
-       
-      
-     
-    
+   
+    MAC Address Functions
+    
+     
+      
+       
+        FunctionDescriptionExample(s)
+       
+      
+     
 
-   
-    The macaddr8 type also supports the standard relational
-    operators (>, <=, etc.) for
-    ordering, and the bitwise arithmetic operators (~,
-    & and |) for NOT, AND and OR.
-   
+     
+      
+       
+        
+         trunc
+        
+        trunc ( macaddr )
+        macaddr
+       
+        Sets the last 3 bytes of the address to zero.  The remaining prefix
+        can be associated with a particular manufacturer (using data not
+        included in PostgreSQL).
+       
+        trunc(macaddr '12:34:56:78:90:ab')
+        12:34:56:00:00:00
+       
+      
+
+      
+       
+        trunc ( macaddr8 )
+        macaddr8
+       
+        Sets the last 5 bytes of the address to zero.  The remaining prefix
+        can be associated with a particular manufacturer (using data not
+        included in PostgreSQL).
+       
+        trunc(macaddr8 '12:34:56:78:90:ab:cd:ef')
+        12:34:56:00:00:00:00:00
+       
+      
+
+      
+       
+        
+         macaddr8_set7bit
+        
+        macaddr8_set7bit ( macaddr8 )
+        macaddr8
+       
+        Sets the 7th bit of the address to one, creating what is known as
+        modified EUI-64, for inclusion in an IPv6 address.
+       
+        macaddr8_set7bit(macaddr8 '00:34:56:ab:cd:ef')
+        02:34:56:ff:fe:ab:cd:ef
+       
+      
+     
+    
+   
 
   
 
This is the main PostgreSQL git repository.