netaddr 1.2.0 → 1.3.0

data/changelog

@@ -1,16 +1,25 @@
 
 ==Version
-*1.2.0*
+====1.3.0
 
+===New Features
+* added CIDR#[]
+* added CIDR#succ (CIDR objects may now be used as args for the standard Ruby Range class)
+* added CIDR#allocate_rfc3531
+* added CIDR#to_i
+* added CIDRv6.unique_local
+* added EUI48#to_eui64
+* added EUI#to_i
+* added EUI#to_s
 
-===Known Issues
+===Changes
+* deprecated 'packed' methods
 
-* users may directly modify CIDR objects stored within a Tree, 
-  essentially invalidating the structure of that Tree
 
+==Version
+====1.2.0
 
 ===Changes
-
 * CIDRv4#new and CIDRv6#new methods have been changed for the sake of speed improvements.
   Please use the CIDR#create method instead.
 * changes to CIDR#wildcard_mask
@@ -20,7 +29,6 @@
 
 
 ===New Features
-
 * speed improvements
 * added CIDR#set_wildcard_mask
 * added <=>, >, <, == methods to CIDR

data/lib/cidr.rb

@@ -1,5 +1,5 @@
 =begin rdoc
- Copyleft (c) 2006 Dustin Spinhirne (www.spinhirne.com) 
+ Copyleft (c) 2006 Dustin Spinhirne
 
  Licensed under the same terms as Ruby, No Warranty is provided.
 =end
@@ -10,21 +10,21 @@ module NetAddr
 #
 #A class & series of methods for creating and manipulating CIDR network
 #addresses. Both IPv4 and IPv6 are supported.
-# 
+#
 #This class accepts a CIDR address, via the CIDR.create method,
 #in (x.x.x.x/yy or xxxx::/yy) format for IPv4 and IPv6, or (x.x.x.x/y.y.y.y) for IPv4.
 #CIDR.create then creates either a CIDRv4 or CIDRv6 object. An optional tag hash may be 
 #provided with each CIDR as a way of adding custom labels.
-# 
+#
 #Upon initialization, the IP version is auto-detected and assigned to the 
 #CIDR. The original IP/Netmask passed within the CIDR is stored and then 
 #used to determine the confines of the CIDR block. Various properties of the
 #CIDR block are accessible via several different methods. There are also
 #methods for modifying the CIDR or creating new derivative CIDR's.
-# 
+#
 #An example CIDR object is as follows:
 #    NetAddr::CIDR.create('192.168.1.20/24')
-# 
+#
 #This would create a CIDR object (192.168.1.0/24) with the following properties:
 #    version = 4
 #    base network = 192.168.1.0
@@ -32,7 +32,7 @@ module NetAddr
 #    netmask = /24 (255.255.255.0)
 #    size = 256 IP addresses
 #    broadcast = 192.168.1.255
-#    
+#
 #You can see how the CIDR object is based around the entire IP space
 #defined by the provided IP/Netmask pair, and not necessarily the individual
 #IP address itself.
@@ -70,52 +70,6 @@ private_class_method :new
         @tag = new_tag
     end
 
-#==============================================================================#
-# initialize()
-#==============================================================================#
-
-# This method performs absolutely no error checking, and is meant to be used only by
-# other internal methods for the sake of the speedier creation of CIDR objects.
-# Please consider using #create unless you know what you are doing with 100% certainty.
-#
-#===Arguments:
-#* ip - Integer representing an ip address
-#* netmask - Integer representing a binary mask
-#* tag - Hash used to append custom tags to CIDR
-#* wildcard_mask - Integer representing a binary mask
-#* wildcard_mask_bit_flipped - indicates whether or not the wildcard_mask is bit-flipped or not
-#
-    def initialize(ip, netmask=nil, tag={}, wildcard_mask=nil, wildcard_mask_bit_flipped=false)
-        @ip = ip
-
-        if ( self.kind_of?(NetAddr::CIDRv4) )
-            @version = 4
-            @address_len = 32
-        else
-            @version = 6
-            @address_len = 128
-        end
-        @all_f = 2**@address_len - 1
-
-        if (netmask)
-            @netmask = netmask
-        else
-            @netmask = 2**@address_len - 1
-        end
-
-        @network = (@ip & @netmask)
-        @hostmask = @netmask ^ @all_f
-        @tag = tag
-
-        if (!wildcard_mask)
-            @wildcard_mask = @netmask
-        else
-            @wildcard_mask = wildcard_mask
-            @wildcard_mask = ~@wildcard_mask if (wildcard_mask_bit_flipped)
-        end
-
-    end
-
 #==============================================================================#
 # create()
 #==============================================================================#
@@ -124,13 +78,13 @@ private_class_method :new
 #Create a new CIDRv4 or CIDRv6 object.
 #CIDR formatted netmasks take precedence over extended formatted ones.
 #CIDR address defaults to a host network (/32 or /128) if netmask not provided.
-#:PackedNetmask takes precedence over netmask given within CIDR addresses.
+#:Mask takes precedence over netmask given within CIDR addresses.
 #Version will be auto-detected if not specified.
 #
 # NetAddr::CIDR.create('192.168.1.1/24')
 # NetAddr::CIDR.create('192.168.1.1 255.255.255.0')
 # NetAddr::CIDR.create(0x0a010001,
-#                      :PackedNetmask => 0xffffff00
+#                      :Mask => 0xffffff00
 #                      :Version => 4)
 # NetAddr::CIDR.create('192.168.1.1',
 #                      :WildcardMask => ['0.7.0.255', true])
@@ -144,9 +98,9 @@ private_class_method :new
 # NetAddr::CIDR.create('::ffff:192.168.1.1/96')
 #
 #===Arguments:
-#* addr = CIDR address as a String, or a packed IP address as an Integer
+#* addr = CIDR address as a String, or an IP address as an Integer
 #* options = Hash with the following keys:
-#     :PackedNetmask -- Integer representation of an IP Netmask
+#     :Mask -- Integer representing a binary IP Netmask
 #     :Version -- IP version - Integer
 #     :Tag -- Custom descriptor tag - Hash, tag => value.
 #     :WildcardMask -- 2 element Array. First element contains a special bit mask used for
@@ -154,10 +108,10 @@ private_class_method :new
 #                      bit mask is bit flipped.
 #
     def CIDR.create(addr, options=nil)
-        known_args = [:PackedNetmask, :Version, :Tag, :WildcardMask]
+        known_args = [:Mask, :Version, :Tag, :WildcardMask]
         ip, netmask, tag = nil, nil, {}
         version, wildcard_mask ,wildcard_mask_bit_flipped = nil, nil, false
-        packed_netmask, all_f = nil, nil
+        netmask_int, all_f = nil, nil
 
         # validate options
         if (options)
@@ -165,10 +119,10 @@ private_class_method :new
                                  "#{options.class} provided." if (!options.kind_of?(Hash) )
             NetAddr.validate_args(options.keys,known_args)
 
-            if (options.has_key?(:PackedNetmask))
-                packed_netmask = options[:PackedNetmask]
-                raise ArgumentError, "Expected Integer, but #{packed_netmask.class} " +
-                                     "provided for option :PackedNetmask." if (!packed_netmask.kind_of?(Integer))
+            if (options.has_key?(:Mask))
+                netmask_int = options[:Mask]
+                raise ArgumentError, "Expected Integer, but #{netmask_int.class} " +
+                                     "provided for option :Mask." if (!netmask_int.kind_of?(Integer))
             end
 
             if (options.has_key?(:Tag))
@@ -239,10 +193,10 @@ private_class_method :new
         all_f = 2**32-1
         all_f = 2**128-1 if (version == 6)
 
-        # set netmask. packed_netmask takes precedence. set to all_f if no netmask provided
-        if (packed_netmask)
-            NetAddr.validate_netmask_int(packed_netmask,version,true)
-            netmask = packed_netmask
+        # set netmask. netmask_int takes precedence. set to all_f if no netmask provided
+        if (netmask_int)
+            NetAddr.validate_netmask_int(netmask_int,version,true)
+            netmask = netmask_int
         elsif (netmask)
             NetAddr.validate_netmask_str(netmask,version)
             netmask = NetAddr.netmask_str_to_int(netmask, version)
@@ -268,22 +222,70 @@ private_class_method :new
     end
 
 #==============================================================================#
-# <=>()
+# initialize()
+#==============================================================================#
+
+# This method performs absolutely no error checking, and is meant to be used only by
+# other internal methods for the sake of the speedier creation of CIDR objects.
+# Please consider using #create unless you know what you are doing with 100% certainty.
+#
+#===Arguments:
+#* ip - Integer representing an ip address
+#* netmask - Integer representing a binary netmask
+#* tag - Hash used to append custom tags to CIDR
+#* wildcard_mask - Integer representing a binary mask
+#* wildcard_mask_bit_flipped - indicates whether or not the wildcard_mask is bit-flipped or not
+#
+    def initialize(ip, netmask=nil, tag={}, wildcard_mask=nil, wildcard_mask_bit_flipped=false)
+        @ip = ip
+
+        if ( self.kind_of?(NetAddr::CIDRv4) )
+            @version = 4
+            @address_len = 32
+        else
+            @version = 6
+            @address_len = 128
+        end
+        @all_f = 2**@address_len - 1
+
+        if (netmask)
+            @netmask = netmask
+        else
+            @netmask = 2**@address_len - 1
+        end
+
+        @network = (@ip & @netmask)
+        @hostmask = @netmask ^ @all_f
+        @tag = tag
+
+        if (!wildcard_mask)
+            @wildcard_mask = @netmask
+        else
+            @wildcard_mask = wildcard_mask
+            @wildcard_mask = ~@wildcard_mask if (wildcard_mask_bit_flipped)
+        end
+
+    end
+
+#==============================================================================#
+# <()
 #==============================================================================#
 
 #===Synopsis
-#Compare the sort order of the current CIDR with a provided CIDR and return:
-#* 1 if the current CIDR is greater than the provided CIDR
-#* 0 if the current CIDR and the provided CIDR are equal (base address and netmask are equal)
-#* -1 if the current CIDR is less than the provided CIDR
+#Compare the sort order of the current CIDR with a provided CIDR and return true
+#if current CIDR is less than provided CIDR.
+#
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr < '192.168.2.0/24' => true
 #
 #===Arguments:
 #* CIDR address or NetAddr::CIDR object
 #
 #===Returns:
-#* Integer
+#* true or false
 #
-    def <=>(cidr)
+    def <(cidr)
         if (!cidr.kind_of?(NetAddr::CIDR))
             begin
                 cidr = NetAddr::CIDR.create(cidr)
@@ -299,26 +301,35 @@ private_class_method :new
         end
 
         # compare
-        comparasin = NetAddr.cidr_gt_lt(self,cidr)
+        lt = false
+        lt = true if ( NetAddr.cidr_gt_lt(self,cidr) == -1)
 
-        return(comparasin)
+        return(lt)
     end
 
 #==============================================================================#
-# >()
+# <=>()
 #==============================================================================#
 
 #===Synopsis
-#Compare the sort order of the current CIDR with a provided CIDR and return true
-#if current CIDR is greater than provided CIDR.
+#Compare the sort order of the current CIDR with a provided CIDR and return:
+#* 1 if the current CIDR is greater than the provided CIDR
+#* 0 if the current CIDR and the provided CIDR are equal (base address and netmask are equal)
+#* -1 if the current CIDR is less than the provided CIDR
+#
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr <=> '192.168.2.0/24' => -1
+# cidr <=> '192.168.0.0/24' => 1
+# cidr <=> '192.168.1.0/24' => 0
 #
 #===Arguments:
 #* CIDR address or NetAddr::CIDR object
 #
 #===Returns:
-#* true or false
+#* Integer
 #
-    def >(cidr)
+    def <=>(cidr)
         if (!cidr.kind_of?(NetAddr::CIDR))
             begin
                 cidr = NetAddr::CIDR.create(cidr)
@@ -334,19 +345,22 @@ private_class_method :new
         end
 
         # compare
-        gt = false
-        gt = true if ( NetAddr.cidr_gt_lt(self,cidr) == 1)
+        comparasin = NetAddr.cidr_gt_lt(self,cidr)
 
-        return(gt)
+        return(comparasin)
     end
 
 #==============================================================================#
-# <()
+# ==()
 #==============================================================================#
 
 #===Synopsis
 #Compare the sort order of the current CIDR with a provided CIDR and return true
-#if current CIDR is less than provided CIDR.
+#if current CIDR is equal to the provided CIDR.
+#
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr == '192.168.1.0/24' => true
 #
 #===Arguments:
 #* CIDR address or NetAddr::CIDR object
@@ -354,7 +368,7 @@ private_class_method :new
 #===Returns:
 #* true or false
 #
-    def <(cidr)
+    def ==(cidr)
         if (!cidr.kind_of?(NetAddr::CIDR))
             begin
                 cidr = NetAddr::CIDR.create(cidr)
@@ -370,19 +384,24 @@ private_class_method :new
         end
 
         # compare
-        lt = false
-        lt = true if ( NetAddr.cidr_gt_lt(self,cidr) == -1)
+        eq = false
+        eq = true if ( NetAddr.cidr_gt_lt(self,cidr) == 0)
 
-        return(lt)
+        return(eq)
     end
+    alias :eql? :==
 
 #==============================================================================#
-# ==()
+# >()
 #==============================================================================#
 
 #===Synopsis
 #Compare the sort order of the current CIDR with a provided CIDR and return true
-#if current CIDR is equal to the provided CIDR.
+#if current CIDR is greater than provided CIDR.
+#
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr > '192.168.0.0/24' => true
 #
 #===Arguments:
 #* CIDR address or NetAddr::CIDR object
@@ -390,7 +409,7 @@ private_class_method :new
 #===Returns:
 #* true or false
 #
-    def ==(cidr)
+    def >(cidr)
         if (!cidr.kind_of?(NetAddr::CIDR))
             begin
                 cidr = NetAddr::CIDR.create(cidr)
@@ -406,21 +425,156 @@ private_class_method :new
         end
 
         # compare
-        eq = false
-        eq = true if ( NetAddr.cidr_gt_lt(self,cidr) == 0)
+        gt = false
+        gt = true if ( NetAddr.cidr_gt_lt(self,cidr) == 1)
 
-        return(eq)
+        return(gt)
+    end
+
+#==============================================================================#
+# []
+#==============================================================================#
+
+#===Synopsis
+#Provide the IP at the given index of the CIDR.
+#
+# Example:
+# cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr4[1] => 192.168.1.1/32
+#
+#===Arguments:
+#* index = Index number as an Integer
+#
+#===Returns:
+#* NetAddr::CIDR object.
+#
+    def [](index)
+        raise ArgumentError, "Integer expected for argument 'index' but " +
+                             "#{index.class} provided." if (!index.kind_of?(Integer) )
+
+        addr = @network + index
+        if ( (@hostmask | addr) == (@hostmask | @network) )
+            addr = NetAddr.cidr_build(@version, addr)
+        else
+            raise BoundaryError, "Index of #{index} returns IP that is out of " +
+                                 "bounds of CIDR network."
+        end
+
+        return(addr)
+    end
+
+#==============================================================================#
+# allocate_rfc3531()
+#==============================================================================#
+
+#===Synopsis
+#RFC 3531 describes a flexible method for IP subnet allocation from
+#a larger parent network. Given the new netmask for subnet allocations from this CIDR,
+#provide a list of those subnets arranged by the order in which they should be allocated.
+#
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.0.0/16')
+# cidr.allocate_rfc3531(21, :Strategy => :centermost) => ["192.168.0.0/21"... "192.168.248.0/21"]
+#
+#===Arguments:
+#* netmask (in bits) for all new subnet allocations
+#* options = Hash with the following keys:
+#    :Objectify -- if true, return NetAddr::CIDR objects
+#    :Short -- if true, return IPv6 addresses in short-hand notation
+#    :Strategy -- allocation strategy to use. must be either :centermost or :leftmost (default)
+#
+#===Returns:
+#* Array of Strings or CIDR objects
+#
+    def allocate_rfc3531(netmask, options=nil)
+        short = false
+        objectify = false
+        strategy = :leftmost
+
+        # validate args
+        raise ArgumentError, "Expected Integer for argument (netmask), but #{max.class} received." if ( !netmask.kind_of?(Integer) )
+        raise BoundaryError, "Netmask (#{netmask}) is invalid for a version #{self.version} address." if (netmask > @address_len)
+        raise BoundaryError, "Netmask (#{netmask}) cannot be less than #{self.bits}." if (netmask < self.bits)
+        known_args = [:Objectify, :Short, :Strategy]
+        if (options)
+            if (!options.kind_of? Hash)
+                raise ArgumentError, "Expected Hash, but #{options.class} provided."
+            end
+            NetAddr.validate_args(options.keys,known_args)
+
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+
+            if( options.has_key?(:Strategy))
+                strategy = options[:Strategy]
+                raise ArgumentError, "Argument :Strategy must be either :leftmost or :centermost." if (strategy != :leftmost && strategy != :centermost)
+            end
+        end
+
+        subnet_bits = netmask - self.bits
+        net_lshift = @address_len - netmask
+        new_mask = NetAddr.bits_to_mask(netmask,self.version)
+        cidr_list = []
+        if (strategy == :leftmost)
+            (0..(2**subnet_bits)-1).each do |num|
+                mirror = NetAddr.binary_mirror(num, subnet_bits)
+
+                if (!objectify)
+                    my_ip_s = NetAddr.ip_int_to_str(@network | (mirror << net_lshift), @version)
+                    my_ip_s = NetAddr.shorten(my_ip_s) if (short && @version == 6)
+                    cidr_list.push( my_ip_s << '/' << netmask.to_s )
+                else
+                    cidr_list.push( NetAddr.cidr_build(@version, @network | (mirror << net_lshift), new_mask ) )
+                end
+            end
+
+        else # :centermost
+            round = 1
+            bit_count = 1
+            lshift = subnet_bits/2
+            lshift -= 1 if (subnet_bits & 1 == 0) # if subnet_bits is even number
+
+            unique = {}
+            until (bit_count > subnet_bits)
+                (0..2**bit_count-1).each do |num|
+                    shifted = num << lshift
+                    if ( !unique.has_key?(shifted) )
+                        if (!objectify)
+                            my_ip_s = NetAddr.ip_int_to_str(@network | (shifted << net_lshift), @version)
+                            my_ip_s = NetAddr.shorten(my_ip_s) if (short && @version == 6)
+                            cidr_list.push( my_ip_s << '/' << netmask.to_s )
+                        else
+                            cidr_list.push( NetAddr.cidr_build(@version, @network | (shifted << net_lshift), new_mask ) )
+                        end
+                        unique[shifted] = true
+                    end
+                end
+
+                lshift -= 1 if (round & 1 == 0) # if even round
+                round += 1
+                bit_count += 1
+            end
+        end
+
+        return(cidr_list)
     end
-    alias :eql? :==
 
 #==============================================================================#
 # arpa()
 #==============================================================================#
 
 #===Synopsis
-#Depending on the IP version of the current CIDR, 
+#Depending on the IP version of the current CIDR,
 #return either an in-addr.arpa. or ip6.arpa. string. The netmask will be used
 #to determine the length of the returned string.
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr.arpa => "1.168.192.in-addr.arpa."
 #
 #===Arguments:
 #* none
@@ -476,6 +630,9 @@ private_class_method :new
 
 #===Synopsis
 #Provide number of bits in Netmask.
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr.bits => 24
 #
 #===Arguments:
 #* none
@@ -498,10 +655,12 @@ private_class_method :new
 #* -1 if the current CIDR is contained by (is subnet of) the provided CIDR
 #* nil if the two CIDR addresses are unrelated
 #
-# cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
-# cidr4_2 = NetAddr::CIDR.create('192.168.1.0/26')
-# cidr4.cmp(cidr4_2)
-# cidr4.cmp('192.168.1.0/26')
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr.cmp('192.168.1.0/25') => 1
+# cidr.cmp('192.168.1.0/24') => 0
+# cidr.cmp('192.168.0.0/23') => -1
+# cidr.cmp('10.0.0.0/24') => nil
 #
 #===Arguments:
 #* CIDR address or NetAddr::CIDR object
@@ -538,11 +697,12 @@ end
 #Determines if this CIDR contains (is supernet of)
 #the provided CIDR address or NetAddr::CIDR object.
 #
-# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# Example:
+# cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
 # cidr6 = NetAddr::CIDR.create('fec0::/64')
 # cidr6_2 = NetAddr::CIDR.create('fec0::/96')
-# cidr4.contains?('192.168.1.2')
-# cidr6.contains?(cidr6_2)
+# cidr4.contains?('192.168.1.2') => true
+# cidr6.contains?(cidr6_2) => true
 #
 #===Arguments:
 #* cidr = CIDR address or NetAddr::CIDR object
@@ -579,11 +739,12 @@ end
 #===Synopsis
 #Returns network/netmask in CIDR format.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # cidr6 = NetAddr::CIDR.create('fec0::/64')
-# cidr4.desc(:IP => true)
-# cidr4.desc()
-# cidr6.desc(:Short => true)
+# cidr4.desc(:IP => true) => "192.168.1.1/24"
+# cidr4.desc() => "192.168.1.0/24"
+# cidr6.desc(:Short => true) => "fec0::/64"
 #
 #===Arguments:
 #* options = Optional hash with the following keys:
@@ -631,10 +792,11 @@ end
 #===Synopsis
 #Provide all IP addresses contained within the IP space of this CIDR.
 #
-#   cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
-#   cidr6 = NetAddr::CIDR.create('fec0::/64')
-#   cidr4.enumerate(:Limit => 4, :Bitstep => 32)
-#   cidr6.enumerate(:Limit => 4, :Bitstep => 32, :Objectify => true)
+# Example:
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# cidr4.enumerate(:Limit => 4, :Bitstep => 32)
+# cidr6.enumerate(:Limit => 4, :Bitstep => 32, :Objectify => true)
 #
 #===Arguments:
 #* options = Hash with the following keys:
@@ -707,6 +869,7 @@ end
 #Given a list of subnets of the current CIDR, return a new list with any
 #holes (missing subnets) filled in.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
 # cidr4.fill_in(['192.168.1.0/27','192.168.1.64/26','192.168.1.128/25'])
 #
@@ -784,6 +947,10 @@ end
 #===Synopsis
 #Provide original IP address passed during initialization.
 #
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr.ip => "192.168.1.1"
+#
 #===Arguments:
 #* options = Hash with the following keys:
 #    :Objectify -- if true, return NetAddr::CIDR object
@@ -832,6 +999,7 @@ end
 #Determines if this CIDR is contained within (is subnet of)
 #the provided CIDR address or NetAddr::CIDR object.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # cidr4.is_contained?('192.168.0.0/23')
 #
@@ -858,9 +1026,9 @@ end
                                  "with a version #{@version} CIDR."
         end
 
-        network = cidr.packed_network 
-        netmask = cidr.packed_netmask
-        hostmask = cidr.packed_hostmask
+        network = cidr.to_i(:network)
+        netmask = cidr.to_i(:netmask)
+        hostmask = cidr.to_i(:hostmask)
 
         is_contained = true if ( NetAddr.cidr_compare(self,cidr) == -1 )
 
@@ -874,6 +1042,10 @@ end
 #===Synopsis
 #Provide last IP address in this CIDR object.
 #
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr.last => "192.168.1.255"
+#
 #===Arguments:
 #* options = Hash with the following keys:
 #    :Objectify -- if true, return NetAddr::CIDR object
@@ -904,16 +1076,16 @@ end
 
         end
 
-        packed_ip = @network | @hostmask
+        ip_int = @network | @hostmask
         if (!objectify)
-            ip = NetAddr.ip_int_to_str(packed_ip, @version)
+            ip = NetAddr.ip_int_to_str(ip_int, @version)
             ip = NetAddr.shorten(ip) if (short && !objectify && @version == 6)
         else
-            ip = NetAddr.cidr_build(@version,packed_ip)
+            ip = NetAddr.cidr_build(@version,ip_int)
         end
 
         return(ip)
-    end   
+    end
 
 #==============================================================================#
 # matches?()
@@ -924,6 +1096,7 @@ end
 #if it falls within the range of addresses resulting from the combination of the 
 #IP and Wildcard Mask of this CIDR.
 #
+# Example:
 # cidr4 = NetAddr.CIDRv4.create('10.0.0.0', :WildcardMask => ['0.7.0.255', true])
 # cidr4.matches?('10.0.0.22') -> true
 # cidr4.matches?('10.8.0.1') -> false
@@ -937,19 +1110,19 @@ end
 #* True or False
 #
     def matches?(ip)
-        packed = nil
+        ip_int = nil
         if (!ip.kind_of?(NetAddr::CIDR))
             begin
-                packed = NetAddr.pack_ip_addr(ip, :Version => @version)
+                ip_int = NetAddr.ip_to_i(ip, :Version => @version)
             rescue NetAddr::ValidationError
                 raise NetAddr::ValidationError, "Provided IP must be a valid IPv#{@version} address."
             end
         else
             raise NetAddr::ValidationError, "Provided CIDR must be of type #{self.class}" if (ip.class != self.class)
-            packed = ip.packed_ip
+            ip_int = ip.to_i(:ip)
         end
 
-        return(true) if (@ip & @wildcard_mask == packed & @wildcard_mask)
+        return(true) if (@ip & @wildcard_mask == ip_int & @wildcard_mask)
         return(false)
     end
 
@@ -962,6 +1135,7 @@ end
 #and ff00::/8 for IPv6), return its ethernet MAC address (EUI-48) mapping.
 #MAC address is based on original IP address passed during initialization.
 #
+# Example:
 # mcast = NetAddr::CIDR.create('224.0.0.6')
 # mcast.multicast_mac.address
 #
@@ -1018,6 +1192,10 @@ end
 #===Synopsis
 #Provide netmask in CIDR format (/yy).
 #
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr.netmask => "/24"
+#
 #===Arguments:
 #* none
 #
@@ -1036,6 +1214,10 @@ end
 #===Synopsis
 #Provide base network address.
 #
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr.network => "192.168.1.0"
+#
 #===Arguments:
 #* options = Hash with the following fields:
 #    :Objectify -- if true, return NetAddr::CIDR object
@@ -1086,6 +1268,7 @@ end
 #===Synopsis
 #Provide the next IP following the last available IP within this CIDR object.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # cidr6 = NetAddr::CIDR.create('fec0::/64')
 # cidr4.next_subnet()
@@ -1151,10 +1334,11 @@ end
 #Provide the next subnet following this CIDR object. The next subnet will
 #be of the same size as the current CIDR object.
 #
-#   cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
-#   cidr6 = NetAddr::CIDR.create('fec0::/64')
-#   cidr4.next_subnet()
-#   cidr6.next_subnet(:Short => true) 
+# Example:
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# cidr4.next_subnet()
+# cidr6.next_subnet(:Short => true) 
 #
 #===Arguments:
 #* options = Hash with the following keys:
@@ -1203,7 +1387,7 @@ end
             next_sub = NetAddr.shorten(next_sub) if (short && @version == 6)        
             next_sub = next_sub << "/" << self.bits.to_s
         else
-            next_sub = NetAddr.cidr_build(@version,next_sub,self.packed_netmask)
+            next_sub = NetAddr.cidr_build(@version,next_sub,self.to_i(:netmask))
         end
 
         return(next_sub)
@@ -1216,6 +1400,7 @@ end
 #===Synopsis
 #Provide the nth IP within this object.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # cidr4.nth(1)
 # cidr4.nth(1, :Objectify => true)
@@ -1270,100 +1455,16 @@ end
         return(my_ip)
     end
 
-#==============================================================================#
-# packed_hostmask()
-#==============================================================================#
-
-#===Synopsis
-#Provide an Integer representation of the Hostmask of this object.
-#
-#===Arguments:
-#* none
-#
-#===Returns:
-#* Integer
-#
-    def packed_hostmask()
-        return(@hostmask)
-    end
-
-#==============================================================================#
-# packed_ip()
-#==============================================================================#
-
-#===Synopsis
-#Provide an Integer representation of the IP address of this object.
-#
-#===Arguments:
-#* none
-#
-#===Returns:
-#* Integer
-#
-    def packed_ip()
-        return(@ip)
-    end
-
-#==============================================================================#
-# packed_netmask()
-#==============================================================================#
-
-#===Synopsis
-#Provide an Integer representation of the Netmask of this object.
-#
-#===Arguments:
-#* none
-#
-#===Returns:
-#* Integer
-#
-    def packed_netmask()
-        return(@netmask)
-    end
-
-#==============================================================================#
-# packed_network()
-#==============================================================================#
-
-#===Synopsis
-#Provide an Integer representation of the Network address of this object.
-#
-#===Arguments:
-#* none
-#
-#===Returns:
-#* Integer
-#
-    def packed_network()
-        return(@network)
-    end
-
-#==============================================================================#
-# packed_wildcard_mask()
-#==============================================================================#
-
-#===Synopsis
-#Provide an Integer representation of the IPv4 Wildcard Mask.
-#
-#===Arguments:
-#* none
-#
-#===Returns:
-#* Integer
-#
-    def packed_wildcard_mask()
-        return(@wildcard_mask)
-    end
-
 #==============================================================================#
 # range()
 #==============================================================================#
 
 #===Synopsis
-#Given a set of index numbers for this CIDR, return all IP addresses within the 
+#Given a set of index numbers for this CIDR, return all IP addresses within the
 #CIDR that are between them (inclusive). If an upper bound is not provided, then
-#all addresses from the lower bound up will be returned. 
+#all addresses from the lower bound up will be returned.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # cidr4.range(0, 1)
 # cidr4.range(0, 1, :Objectify => true)
@@ -1379,6 +1480,15 @@ end
 #
 #===Returns:
 #* Array of Strings, or Array of NetAddr::CIDR objects
+#
+#===Note:
+#If you do not need all of the fancy options in this method, then please consider
+#using the standard Ruby Range class as shown below.
+#
+# Example:
+# start = NetAddr::CIDR.create('192.168.1.0')
+# fin = NetAddr::CIDR.create('192.168.2.3')
+# (start..fin).each {|addr| puts addr.desc}
 #
     def range(lower, upper=nil, options=nil)
         known_args = [:Bitstep, :Objectify, :Short]
@@ -1511,12 +1621,12 @@ end
         # belongs in. take that half & repeat the process. every time
         # we repeat, store the non-matching half
         new_mask = self.bits + 1
-        lower_network = self.packed_network
-        upper_network = self.packed_network + 2**(@address_len - new_mask)
+        lower_network = self.to_i(:network)
+        upper_network = self.to_i(:network) + 2**(@address_len - new_mask)
 
         new_subnets = []
         until(new_mask > addr.bits)
-            if (addr.packed_network < upper_network)
+            if (addr.to_i(:network) < upper_network)
                 match = lower_network
                 non_match = upper_network
             else
@@ -1548,6 +1658,7 @@ end
 #Resize the CIDR by changing the size of the Netmask. 
 #Return the resulting CIDR as a new object.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # new_cidr = cidr4.resize(23)
 #
@@ -1577,6 +1688,7 @@ end
 #passed during initialization will be set to the base network address if
 #it no longer falls within the bounds of the CIDR.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # cidr4.resize!(23)
 #
@@ -1591,7 +1703,7 @@ end
                                  "#{bits.class} provided." if (!bits.kind_of?(Integer))
 
         NetAddr.validate_ip_netmask(bits, :Version => @version)
-        netmask = NetAddr.pack_ip_netmask(bits, :Version => @version)
+        netmask = NetAddr.netmask_to_i(bits, :Version => @version)
 
         @netmask = netmask
         @network = @network & netmask
@@ -1613,6 +1725,7 @@ end
 #Set the wildcard mask. Wildcard masks are typically used for matching
 #entries in an access-list.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
 # cidr4.set_wildcard_mask('0.0.0.255', true)
 # cidr4.set_wildcard_mask('255.255.255.0')
@@ -1625,20 +1738,20 @@ end
 #* nil
 #
     def set_wildcard_mask(mask, bit_flipped=false)
-        packed = nil
+        netmask_int = nil
         if (mask.kind_of?(Integer))
             NetAddr.validate_ip_int(mask,@version)
-            packed = mask
+            netmask_int = mask
         else
             begin
                 NetAddr.validate_ip_str(mask,@version)
-                packed = NetAddr.ip_str_to_int(mask, @version)
+                netmask_int = NetAddr.ip_str_to_int(mask, @version)
             rescue NetAddr::ValidationError
                 raise NetAddr::ValidationError, "Wildcard Mask must be a valid IPv#{@version} address."
             end
         end
-        packed = ~packed if (bit_flipped)
-        @wildcard_mask = packed
+        netmask_int = ~netmask_int if (bit_flipped)
+        @wildcard_mask = netmask_int
 
         return(nil)
     end
@@ -1650,6 +1763,10 @@ end
 #===Synopsis
 #Provide number of IP addresses within this CIDR.
 #
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr.size => 256
+#
 #===Arguments:
 #* none
 #
@@ -1683,6 +1800,7 @@ end
 #If neither :Bits nor :IPCount is provided, then the current CIDR will be split in half.
 #If both :Bits and :IPCount are provided, then :Bits takes precedence.
 #
+# Example:
 # cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
 # cidr6 = NetAddr::CIDR.create('fec0::/64')
 # cidr4.subnet(:Bits => 28, :NumSubnets => 3)
@@ -1703,7 +1821,7 @@ end
 #
     def subnet(options=nil)
         known_args = [:Bits, :IPCount, :NumSubnets, :Objectify, :Short]
-        my_network = self.packed_network
+        my_network = self.to_i(:network)
         my_mask = self.bits
         subnet_bits = my_mask + 1
         min_count = nil 
@@ -1785,7 +1903,7 @@ end
                     new_subnets.push("#{subnet.network}/#{subnet_bits}")
                 end
             else
-                new_subnets.push( NetAddr.cidr_build(@version, subnet.packed_network, NetAddr.bits_to_mask(subnet_bits,version) ) )
+                new_subnets.push( NetAddr.cidr_build(@version, subnet.to_i(:network), NetAddr.bits_to_mask(subnet_bits,version) ) )
             end
         end
 
@@ -1810,6 +1928,73 @@ end
         return(new_subnets)
     end
 
+#==============================================================================#
+# succ()
+#==============================================================================#
+
+#===Synopsis
+#Provide the next subnet following this CIDR object. The next subnet will
+#be of the same size as the current CIDR object.
+#
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr.succ => 192.168.2.0/24
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* NetAddr::CIDR object.
+#
+    def succ()
+        bitstep = 2**(@address_len - self.bits)
+        next_sub = @network + bitstep
+
+        if (next_sub > @all_f)
+            raise BoundaryError, "Returned subnet is out of bounds for IPv#{@version}."
+        end
+
+        next_sub = NetAddr.cidr_build(@version,next_sub,self.to_i(:netmask))
+
+        return(next_sub)
+    end
+
+#==============================================================================#
+# to_i()
+#==============================================================================#
+
+#===Synopsis
+#Convert the requested attribute of the CIDR to an Integer.
+# Example:
+# cidr = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr.to_i => 3232235776
+# cidr.to_i(:hostmask) => 255
+# cidr.to_i(:ip) => 3232235777
+# cidr.to_i(:netmask) => 4294967040
+# cidr.to_i(:wildcard_mask) => 4294967040
+#
+#===Arguments:
+#* attribute -- attribute of the CIDR to convert to an Integer (:hostmask, :ip, :netmask, :network, or :wildcard_mask).
+#
+#===Returns:
+#* Integer
+#
+    def to_i(attribute=:network)
+        if(attribute == :network)
+            return(@network)
+        elsif(attribute == :hostmask)
+            return(@hostmask)
+        elsif(attribute == :ip)
+            return(@ip)
+        elsif(attribute == :netmask)
+            return(@netmask)
+        elsif(attribute == :wildcard_mask)
+            return(@wildcard_mask)
+        else
+            raise ArgumentError, "Attribute is unrecognized. Must be :hostmask, :ip, :netmask, :network, or :wildcard_mask."
+        end
+    end
+
 #==============================================================================#
 # wildcard_mask()
 #==============================================================================#
@@ -1817,6 +2002,11 @@ end
 #===Synopsis
 #Return the wildcard mask.
 #
+# Example:
+# cidr = NetAddr::CIDR.create('10.1.0.0/24', :WildcardMask => ['0.7.0.255', true])
+# cidr.wildcard_mask => "255.248.255.0"
+# cidr.wildcard_mask(true) => "0.7.0.255"
+#
 #===Arguments:
 #* bit_flipped = if set True then returned the bit-flipped version of the wildcard mask.
 #
@@ -1860,6 +2050,10 @@ class CIDRv4 < CIDR
 #===Synopsis
 #Provide IPv4 Hostmask in extended format (y.y.y.y).
 #
+# Example:
+# cidr = NetAddr::CIDR.create('10.1.0.0/24')
+# cidr.hostmask_ext => "0.0.0.255"
+#
 #===Arguments:
 #* none
 #
@@ -1877,6 +2071,10 @@ class CIDRv4 < CIDR
 #===Synopsis
 #Provide IPv4 netmask in extended format (y.y.y.y).
 #
+# Example:
+# cidr = NetAddr::CIDR.create('10.1.0.0/24')
+# cidr.netmask_ext => "255.255.255.0"
+#
 #===Arguments:
 #* none
 #
@@ -1900,6 +2098,80 @@ end # end class CIDRv4
 # Addresses of this class are composed of a 128-bit address space.
 class CIDRv6 < CIDR
     public_class_method :new
+
+#==============================================================================#
+# unique_local()
+#==============================================================================#
+
+#===Synopsis
+#Generate an IPv6 Unique Local CIDR address based on the algorithm described
+#in RFC 4193.
+#
+#From the RFC:
+#
+# 1) Obtain the current time of day in 64-bit NTP format [NTP].
+#
+# 2) Obtain an EUI-64 identifier from the system running this
+#    algorithm.  If an EUI-64 does not exist, one can be created from
+#    a 48-bit MAC address as specified in [ADDARCH].  If an EUI-64
+#    cannot be obtained or created, a suitably unique identifier,
+#    local to the node, should be used (e.g., system serial number).
+#
+# 3) Concatenate the time of day with the system-specific identifier
+#    in order to create a key.
+#
+# 4) Compute an SHA-1 digest on the key as specified in [FIPS, SHA1];
+#    the resulting value is 160 bits.
+#
+# 5) Use the least significant 40 bits as the Global ID.
+#
+# 6) Concatenate FC00::/7, the L bit set to 1, and the 40-bit Global
+#    ID to create a Local IPv6 address prefix.
+#
+# Example:
+# eui = NetAddr::EUI.create('aabb.ccdd.eeff')
+# NetAddr::CIDRv6.unique_local(eui) => fdb4:3014:e277:0000:0000:0000:0000:0000/48
+#
+#===Arguments:
+#* NetAddr::EUI object
+#
+#===Returns:
+#* CIDRv6 object
+#
+    def CIDRv6.unique_local(eui)
+
+        if (eui.kind_of?(NetAddr::EUI48) )
+            eui = eui.to_eui64.to_s
+        elsif (eui.kind_of?(NetAddr::EUI64) )
+            eui = eui.to_s
+        else
+            raise ArgumentError, "Expected NetAddr::EUI object but #{eui.class} received."
+        end
+
+        ntp_time = ''
+
+        # get current time (32-bits), convert to 4-byte string, and append to ntp_time
+        time = Time.now.to_i
+        4.times do
+            ntp_time.insert(0, (time & 0xff).chr )
+            time = time >> 8
+        end
+
+        # create 32-bit fractional, convert to 4-byte string, and append to ntp_time
+        fract = rand(2**32-1)
+        4.times do
+            ntp_time.insert(0, (fract & 0xff).chr )
+            fract = fract >> 8
+        end
+
+        # create sha1 hash
+        pre_hash = ntp_time << eui
+        gid = Digest::SHA1.hexdigest(pre_hash).slice!(30..39)
+        addr = 'fd' << gid << '00000000000000000000'
+
+        return( NetAddr::CIDRv6.new(addr.to_i(16), 0xffffffffffff00000000000000000000 ) )
+    end
+
 end # end class CIDRv6
 
 end # module NetAddr