netaddr 1.0.0

data/Errors

@@ -0,0 +1,13 @@
+=Error Classes
+
+ Exception -
+            |
+             --StandardError -
+                              |
+                               --BoundaryError => CIDR or EUI is out of bounds for a valid address
+                              |
+                               --ValidationError => CIDR or EUI is not a valid address
+                              |
+                               --VersionError => CIDR or EUI is of improper version for requested operation
+                              |
+            |

data/README

@@ -0,0 +1,202 @@
+=Introduction
+
+ NetAddr arose through my need as a network engineer for a 
+ back-end module that could easily handle such advanced tasks 
+ as automating the subnetting/supernetting
+ of IP space, performing calculations on IP CIDR blocks, and other
+ various items. At that time there were no modules that could
+ do any of the things that I needed, so I set out to create my own. 
+ Since it proved to be fairly useful to me, I decided to share the
+ code with the Ruby community. 
+ 
+ I have added things that I find immediately useful for me. I am
+ open to suggestions if there is something that I could add to make
+ your life easier. Comments are also welcome (positive ones in particular).  
+ 
+ Dustin Spinhirne
+
+
+=Example Script
+
+ #!/usr/bin/ruby
+
+ # A script to parse static routes from a Cisco router.
+ # Performs the following tasks:
+ #  - organizes statics by directly connected next-hop interface
+ #  - corrects recursive static routes
+ #  - reports statics with no directly connected next-hop
+ #  - reports duplicate static routes
+ #  - reports static routes that overlap directly connected interfaces
+ #
+ # Change the variable 'infile' to that of the name of the router configuration
+ # file that should be parsed.
+
+ require 'rubygems'
+ require_gem 'netaddr'
+
+ # change this variable to that of the router config file
+ infile = 'router_config.txt'
+
+
+ ip_interface_count = 0
+ static_route_count = 0
+ connected_routes = []
+ static_routes = []
+ statics = {}
+ grouped_routes = {}
+ duplicates = []
+ recursives = []
+ corrected_statics = []
+ overlapping_statics = []
+
+
+ # sort through router config. put connected ip interfaces into 'connected_routes'
+ # and static routes into 'statics'. Set aside duplicate static routes.
+ File.open(infile, 'r') do |file|
+     while line = file.gets
+         if (line =~/^interface .+/)
+             interface = line.chomp
+         elsif (line =~ /^\s*ip address/) # connected interface
+             ip_interface_count += 1
+             addr = line.split('ip address ').join # ['x.x.x.x y.y.y.y']
+             cidr = NetAddr::CIDR.create(addr, :Tag => {:interface => interface})
+             connected_routes.push(cidr)
+         elsif (line =~/^ip route/) # static route
+             static_route_count += 1
+             elements = line.split(' ') # ['ip','route','x.x.x.x','y.y.y.y','x.x.x.x',]
+                ip = elements[2]
+                netmask = elements[3]
+                nexthop = elements[4]
+
+             # keep all but loopbacks, nulls, or defaults
+             if ( (nexthop !~ /Loopback/) && (nexthop !~ /Null/) && (ip != '0.0.0.0') )
+                 nexthop_cidr = NetAddr::CIDR.create(nexthop)
+                 cidr = NetAddr::CIDR.create("#{ip} #{netmask}",
+                                             :Tag => {:route => line, :nexthop => nexthop_cidr})
+
+                 if (!statics.has_key?(cidr.desc))
+                     statics[cidr.desc] = cidr
+                 else
+                     msg = '! overlaps with - ' + statics[cidr.desc].tag[:route] + line + "!\n"
+                     duplicates.push(msg)
+                 end
+             end
+         end
+     end
+ end
+
+
+ # look for statics that overlap with a connected interface, and
+ # group static routes with their next-hop interface.
+ statics.each_key do  |desc|
+     cidr = statics[desc]
+     nexthop = cidr.tag[:nexthop]
+     route = cidr.tag[:route]
+
+     overlaps_with = nil
+     nexthop_int = nil
+     connected_routes.each do |interface|
+         if (interface.contains?(cidr)) # overlapping static
+             overlaps_with = interface
+             break
+         elsif (interface.contains?(nexthop)) # next-hop directly connected
+             nexthop_int = interface
+             break
+         end
+     end
+
+     if (nexthop_int)
+         key = "#{nexthop_int.tag[:interface]} -> #{nexthop_int.desc}"
+         if (grouped_routes.has_key?(key))
+             grouped_routes[key].push(route)
+         else
+             grouped_routes[key] = [route]
+         end
+         static_routes.push(cidr)
+     elsif (overlaps_with)
+         overlap = "! overlaps with: #{overlaps_with.tag[:interface]} -> #{overlaps_with.desc}"
+         overlap << "\n#{route}!\n"
+         overlapping_statics.push(overlap)
+     else
+         recursives.push(cidr)
+     end
+ end
+
+
+ # process recursive routes. update next-hop so that it points
+ # to next hop of a directly connected ip. remove any that do not point to a
+ # directly connected ip. We must continually cycle through the list, as the
+ # 'static_routes' tree is constantly updated. We do this until our list of
+ # recursive static routes stops getting any shorter
+ recursives_count = 0
+ until (recursives_count == recursives.length)
+     recursives_count = recursives.length
+     recursives.each do  |cidr|
+         nexthop = cidr.tag[:nexthop]
+         route = cidr.tag[:route]
+
+         found = nil
+         static_routes.each do |static|
+             if (static.contains?(nexthop))
+                 found = static
+                 break
+             end
+         end
+
+         if (found)
+             updated = 'no ' + route
+             updated << "ip route #{cidr.network} #{cidr.netmask_ext} #{found.tag[:nexthop].ip}\n"
+             updated << "!\n"
+             corrected_statics.push(updated)
+             static_routes.push(cidr)
+             recursives.delete(cidr)
+         end
+     end
+ end
+
+
+ # print results.
+ puts "--- STATISTICS ---"
+ puts "#{ip_interface_count} Connected IP Interfaces\n#{static_route_count} IP Static Routes\n"
+
+ print "\n\n"
+
+ puts "--- OVERLAPPING STATIC ROUTES ---"
+ overlapping_statics.each do |overlap|
+     puts overlap
+ end
+
+ print "\n\n"
+
+ puts "--- DUPLICATE STATIC ROUTES ---"
+ duplicates.each do |route|
+     puts route
+ end
+
+ print "\n\n"
+
+ puts "--- STATIC ROUTES WITH UPDATED NEXT-HOP ---"
+ corrected_statics.each do |route|
+     puts route
+ end
+
+ print "\n\n"
+
+ puts "--- STATIC ROUTES WITH UNKNOWN NEXT-HOP ---"
+ recursives.each do |cidr|
+     puts cidr.tag[:route]
+ end
+
+ print "\n\n"
+
+ puts "--- STATIC ROUTES GROUPED BY NEXT-HOP INTERFACE ---"
+ grouped_routes.each_key do |interface|
+     routes = grouped_routes[interface]
+     puts interface
+     routes.each do |route|
+         puts route
+     end
+     print "\n"
+ end
+
+ __END__

data/lib/cidr.rb

@@ -0,0 +1,1925 @@
+=begin rdoc
+ Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com) 
+ 
+ Licensed under the same terms as Ruby, No Warranty is provided.
+=end
+
+module NetAddr
+
+#=CIDR - Classless Inter-Domain Routing
+#
+#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 to the object.
+# 
+#Upon initialization, the IP version is auto-detected and assigned to the 
+#object. 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
+#    ip address = 192.168.1.20
+#    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.
+#
+class CIDR
+
+private_class_method :new
+
+#==============================================================================#
+# attr_reader/attr_writer
+#==============================================================================#
+
+    # IP version 4 or 6.
+    attr_reader :version
+
+    # Hash of custom tags. Should be in the format tag => value.
+    attr_reader :tag
+    
+    # Integer of either 32 or 128 bits in length, with all bits set to 1
+    attr_reader :all_f
+
+    # Hash of custom tags. Should be in the format tag => value.
+    #
+    # Example:
+    #   cidr4.tag[:name] = 'IPv4 CIDR'
+    #   puts cidr4.tag[:name]
+    #
+    def tag=(new_tag)
+        if (!new_tag.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{new_tag.class} provided."
+        end
+        @tag = new_tag
+    end
+
+#==============================================================================#
+# create()
+#==============================================================================#
+
+#===Synopsis
+#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.
+#Version will be auto-detected if not specified.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr4 = NetAddr::CIDR.create('192.168.1.1 255.255.255.0')
+# cidr4_2 = NetAddr::CIDR.create(0x0a010001,
+#                                :PackedNetmask => 0xffffff00
+#                                :Version => 4)
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# cidr6 = NetAddr::CIDR.create('fec0::/64',
+#                              :Tag => {'interface' => 'g0/1'})
+# cidr6_2 = NetAddr::CIDR.create('::ffff:192.168.1.1/96')
+#
+#===Arguments:
+#* CIDR address as a String, or a packed IP address as an Integer
+#* Optional Hash with the following keys:
+#     :PackedNetmask -- Integer representation of an IP Netmask (optional)
+#     :Version -- IP version - Integer (optional)
+#     :Tag -- Custom descriptor tag - Hash, tag => value. (optional)
+#
+    def CIDR.create(addr, options=nil)
+        known_args = [:PackedNetmask, :Version, :Tag]
+        cidr = nil
+        packed_ip = nil
+        version = nil
+        
+        # validate addr arg
+        if (addr.kind_of?(String))
+            cidr = addr
+        elsif (addr.kind_of?(Integer))
+            packed_ip = addr
+        else
+            raise ArgumentError, "String or Integer expected for argument 'addr' but #{addr.class} provided."
+        end
+        
+        # validate options
+        if (options)     
+            raise ArgumentError, "Hash expected for argument 'options' but " +
+                                 "#{options.class} provided." if (!options.kind_of?(Hash) )
+            NetAddr.validate_args(options.keys,known_args)
+            if (options.has_key?(:Version))
+                version = options[:Version]
+                options.delete(:Version)
+                if (version != 4 && version != 6)
+                    raise VersionError, ":Version should be 4 or 6, but was '#{version}'."
+                end
+            end
+        end
+        
+        # attempt to determine version if not provided
+        if (!version)
+            if (packed_ip) 
+                if (packed_ip < 2**32)
+                    version = 4
+                else
+                    version = 6
+                end
+            else           
+                if (cidr =~ /\./ && cidr !~ /:/)
+                    version = 4
+                elsif (cidr =~ /:/)
+                    version = 6
+                end
+            end          
+        end
+      
+        # create CIDRvX object
+        if (version == 4)
+            return(NetAddr::CIDRv4.new(addr, options))
+        elsif (version == 6)
+            return(NetAddr::CIDRv6.new(addr, options))
+        else
+            raise ArgumentError, "IP version omitted or could not be detected."
+        end
+        
+    end
+
+#==============================================================================#
+# arpa()
+#==============================================================================#
+
+#===Synopsis
+#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.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# puts "arpa for #{cidr4.desc()} is #{cidr4.arpa}"
+# puts "arpa for #{cidr6.desc(:Short => true)} is #{cidr6.arpa}"
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* String
+#
+    def arpa()
+
+        base = self.ip()
+        netmask = self.bits()
+
+        if (@version == 4)
+            net = base.split('.')
+
+            if (netmask)
+                while (netmask < 32)
+                    net.pop
+                    netmask = netmask + 8
+                end
+            end
+
+            arpa = net.reverse.join('.')
+            arpa << ".in-addr.arpa."
+
+        elsif (@version == 6)
+            fields = base.split(':')
+            net = []
+            fields.each do |field|
+                (field.split("")).each do |x|
+                    net.push(x)
+                end
+            end
+
+            if (netmask)
+                while (netmask < 128)
+                    net.pop
+                    netmask = netmask + 4
+                end
+            end
+
+            arpa = net.reverse.join('.')
+            arpa << ".ip6.arpa."
+
+        end
+
+        return(arpa)
+    end
+
+#==============================================================================#
+# bits()
+#==============================================================================#
+
+#===Synopsis
+#Provide number of bits in Netmask.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# puts "cidr4 netmask in bits #{cidr4.bits()}"
+# puts "cidr6 netmask in bits #{cidr6.bits()}"
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* Integer.
+#
+    def bits()
+        return(NetAddr.unpack_ip_netmask(@netmask))
+    end
+
+#==============================================================================#
+# cmp()
+#==============================================================================#
+
+#===Synopsis
+#Compare the current CIDR with a provided CIDR and return:
+#* 1 if the current CIDR contains (is supernet of) 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 contained by (is subnet of) the provided CIDR
+#* nil if the two CIDR addresses are unrelated
+#
+# comp1 = cidr4.cmp(cidr4_2)
+# comp2 = cidr4.cmp('192.168.1.0/26')
+#
+#===Arguments:
+#* CIDR address or NetAddr::CIDR object
+#
+#===Returns:
+#* Integer or nil
+#
+    def cmp(cidr)
+        if (!cidr.kind_of?(NetAddr::CIDR))
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+                end
+            end
+
+        if (cidr.version != @version)
+            raise VersionError, "Attempted to compare a version #{cidr.version} CIDR " +
+                                 "with a version #{@version} CIDR."
+        end
+        
+        # compare
+        comparasin = nil
+        if ( (@network == cidr.packed_network))
+            if (@netmask == cidr.packed_netmask)
+                comparasin = 0
+            elsif(@netmask < cidr.packed_netmask)
+                comparasin = 1
+            elsif(@netmask > cidr.packed_netmask)
+                comparasin = -1            
+            end
+        
+        elsif( (cidr.packed_network | @hostmask) == (@network | @hostmask) )
+            comparasin = 1
+        elsif( (cidr.packed_network | cidr.packed_hostmask) == (@network | cidr.packed_hostmask) )
+            comparasin = -1
+        end
+
+    return(comparasin)
+end
+
+#==============================================================================#
+# contains?()
+#==============================================================================#
+
+#===Synopsis
+#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')
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# cidr6_2 = NetAddr::CIDR.create('fec0::/96')
+# puts "#{cidr4.desc} contains 192.168.1.2" if ( cidr4.contains?('192.168.1.2') )
+# puts "#{cidr6.desc} contains #{cidr6_2.desc(:Short => true)}" if ( cidr6.contains?(cidr6_2) )
+#
+#===Arguments:
+#* CIDR address or NetAddr::CIDR object
+#
+#===Returns:
+#* true or false
+#
+    def contains?(cidr)
+        contains = false
+
+        if (!cidr.kind_of?(NetAddr::CIDR))
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        network = cidr.packed_network 
+        netmask = cidr.packed_netmask
+
+
+        if (cidr.version != @version)
+            raise VersionError, "Attempted to compare a version #{cidr.version} CIDR " +
+                                 "with a version #{@version} CIDR."
+        end
+
+        # if network == @network, then we have to go by netmask length
+        # else we can tell by or'ing network and @network by @hostmask
+        # and comparing the results
+        if (network == @network)
+            contains = true if (netmask > @netmask)
+
+        else
+            if ( (network | @hostmask) == (@network | @hostmask) )
+                contains = true
+            end
+        end
+
+        return(contains)
+    end
+
+#==============================================================================#
+# desc()
+#==============================================================================#
+
+#===Synopsis
+#Returns network/netmask in CIDR format.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# puts cidr4.desc(:IP => true)
+# puts "cidr4 description #{cidr4.desc()}"
+# puts "cidr6 description #{cidr6.desc()}"
+# puts "cidr6 short-hand description #{cidr6.desc(:Short => true)}"
+#
+#===Arguments:
+#* Optional hash with the following keys:
+#    :IP -- if true, return the original ip/netmask passed during initialization (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* String
+#
+    def desc(options=nil)
+        known_args = [:IP, :Short]
+        short = false
+        orig_ip = false
+
+        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?(:Short) && options[:Short] == true)
+                short = true
+            end
+            
+            if (options.has_key?(:IP) && options[:IP] == true)
+                orig_ip = true
+            end
+        end
+        
+        if (!orig_ip)
+            ip = NetAddr.unpack_ip_addr(@network, :Version => @version)
+        else
+            ip = NetAddr.unpack_ip_addr(@ip, :Version => @version)
+        end
+        ip = NetAddr.shorten(ip) if (short && @version == 6)
+        mask = NetAddr.unpack_ip_netmask(@netmask)
+
+        return("#{ip}/#{mask}")
+    end
+
+#==============================================================================#
+# enumerate()
+#==============================================================================#
+
+#===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')
+#   puts "first 4 cidr4 addresses (bitstep 32)"
+#   cidr4.enumerate(:Limit => 4, :Bitstep => 32).each {|x| puts "  #{x}"} 
+#   puts "first 4 cidr6 addresses (bitstep 32)"
+#   cidr6.enumerate(:Limit => 4, :Bitstep => 32, :Objectify => true).each {|x| puts "  #{x.desc}"}
+#
+#===Arguments:
+#* Optional Hash with the following keys:
+#    :Bitstep -- enumerate in X sized steps - Integer (optional)
+#    :Limit -- limit returned list to X number of items - Integer (optional)
+#    :Objectify -- if true, return NetAddr::CIDR objects (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* Array of Strings, or Array of NetAddr::CIDR objects
+#
+    def enumerate(options=nil)
+        known_args = [:Bitstep, :Limit, :Objectify, :Short]
+        bitstep = 1
+        objectify = false
+        limit = nil
+        short = false
+
+        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?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+
+            if( options.has_key?(:Limit) )
+                limit = options[:Limit]
+            end
+            
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+        end
+
+        list = []
+        my_ip = @network
+        change_mask = @hostmask | my_ip
+
+        until ( change_mask != (@hostmask | @network) ) 
+            if (!objectify)
+                my_ip_s = NetAddr.unpack_ip_addr(my_ip, :Version => @version)
+                my_ip_s = NetAddr.shorten(my_ip_s) if (short && @version == 6)
+                list.push( my_ip_s )
+            else
+                list.push( NetAddr::CIDR.create(my_ip, :Version => @version) )
+            end
+            my_ip = my_ip + bitstep
+            change_mask = @hostmask | my_ip
+            if (limit)
+                limit = limit -1
+                break if (limit == 0)
+            end
+        end       
+        
+        return(list)
+    end
+
+#==============================================================================#
+# eql?
+#==============================================================================#
+
+#===Synopsis
+#Return true if the current CIDR and the provided CIDR are equal 
+#(base address and netmask are equal).
+#
+# cidr4.eql?('192.168.1.1/24')
+#
+#===Arguments:
+#* CIDR address or NetAddr::CIDR object
+#
+#===Returns:
+#* true or false
+#
+    def eql?(cidr)
+        is_eql = false
+
+        if (!cidr.kind_of?(NetAddr::CIDR))
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        if (cidr.version != @version)
+            raise VersionError, "Attempted to compare a version #{cidr.version} CIDR " +
+                                 "with a version #{@version} CIDR."
+        end
+        
+        is_eql = true if (self.packed_network == cidr.packed_network && self.packed_netmask == cidr.packed_netmask)
+        
+        return(is_eql)
+    end
+
+#==============================================================================#
+# fill_in()
+#==============================================================================#
+
+#===Synopsis
+#Given a list of subnets of the current CIDR, return a new list with any
+#holes (missing subnets) filled in.
+#
+# subnets = cidr4.fill_in(['192.168.1.0/27','192.168.1.64/26','192.168.1.128/25'])
+# subnets = cidr4.fill_in(:List => ['192.168.1.0/27','192.168.1.64/26'], :Objectify => true)
+#
+#===Arguments:
+#* Array of CIDR addresses, or Array of NetAddr::CIDR objects
+#* Optional Hash with the following keys:
+#    :Objectify -- if true, return NetAddr::CIDR objects (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* Array of CIDR Strings, or an Array of NetAddr::CIDR objects
+#
+
+    def fill_in(list, options=nil)
+        known_args = [:Objectify, :Short]
+        short = false
+        objectify = false
+
+        # validate list
+        raise ArgumentError, "Array expected for argument 'list' but #{list.class} provided." if (!list.kind_of?(Array) )
+    
+        # validate options
+        if (options)     
+            raise ArgumentError, "Hash expected for argument 'options' but " +
+                                 "#{options.class} provided." if (!options.kind_of?(Hash) )
+            NetAddr.validate_args(options.keys,known_args)
+    
+            if (options.has_key?(:Short) && options[:Short] == true)
+                short = true
+            end
+    
+            if (options.has_key?(:Objectify) && options[:Objectify] == true)
+                objectify = true
+            end
+        end
+
+        # validate each cidr and store in cidr_list
+        cidr_list = []
+        list.each do |obj|
+            if (!obj.kind_of?(NetAddr::CIDR))
+                begin
+                    obj = NetAddr::CIDR.create(obj)
+                rescue Exception => error
+                    aise ArgumentError, "A provided CIDR raised the following " +
+                                        "errors: #{error}"
+                end
+            end
+
+            if (!obj.version == self.version)
+                raise VersionError, "#{obj.desc(:Short => true)} is not a version #{self.version} address."
+            end
+            
+            # make sure we contain the cidr
+            if ( self.contains?(obj) == false )
+                raise "#{obj.desc(:Short => true)} does not fit " +
+                      "within the bounds of #{self.desc(:Short => true)}."
+            end
+            cidr_list.push(obj)
+        end
+        
+        # sort our cidr's and see what is missing
+        complete_list = []
+        expected = self.packed_network
+        NetAddr.sort(cidr_list).each do |cidr|
+            network = cidr.packed_network
+            bitstep = (@all_f + 1) - cidr.packed_netmask
+            
+            if (network > expected)
+                num_ips_missing = network - expected
+                sub_list = make_subnets_from_base_and_ip_count(expected,num_ips_missing)
+                complete_list.concat(sub_list)                               
+            elsif (network < expected)
+                next
+            end
+            complete_list.push(NetAddr::CIDR.create(network,
+                                                    :PackedNetmask => cidr.packed_netmask,
+                                                    :Version => self.version))
+            expected = network + bitstep
+        end
+        
+        # if expected is not the next subnet, then we're missing subnets 
+        # at the end of the cidr
+        next_sub = self.next_subnet(:Objectify => true).packed_network
+        if (expected != next_sub)
+            num_ips_missing = next_sub - expected
+            sub_list = make_subnets_from_base_and_ip_count(expected,num_ips_missing)
+            complete_list.concat(sub_list)
+        end
+        
+        # decide what to return
+        if (!objectify)
+            subnets = []
+            complete_list.each {|entry| subnets.push(entry.desc(:Short => short))}
+            return(subnets)
+        else
+            return(complete_list)
+        end
+    end
+
+#==============================================================================#
+# hostmask_ext()
+#==============================================================================#
+
+#===Synopsis
+#Provide IPv4 Hostmask in extended format (y.y.y.y).
+#
+# puts cidr4.hostmask_ext(
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* String
+#
+    def hostmask_ext()
+        if (@version == 4)
+            return(NetAddr.unpack_ip_addr(@hostmask, :Version => @version))
+        else
+            return(nil) 
+        end
+    end
+
+#==============================================================================#
+# ip()
+#==============================================================================#
+
+#===Synopsis
+#Provide original IP address passed during initialization.
+#
+# puts cidr4.ip()
+# puts cidr4.ip(:Objectify => true).desc
+#
+#===Arguments:
+#* Optional Hash with the following keys:
+#    :Objectify -- if true, return NetAddr::CIDR object (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* String or NetAddr::CIDR object.
+#
+    def ip(options=nil)
+        known_args = [:Objectify, :Short]
+        objectify = false
+        short = false
+        
+        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?(:Short) && options[:Short] == true )
+                short = true
+            end
+            
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+        end
+
+        
+        
+        if (!objectify)
+            ip = NetAddr.unpack_ip_addr(@ip, :Version => @version)
+            ip = NetAddr.shorten(ip) if (short && @version == 6)
+        else
+            ip = NetAddr::CIDR.create(@ip, :Version => @version)
+        end
+
+        return(ip)
+    end
+
+#==============================================================================#
+# is_contained?()
+#==============================================================================#
+
+#===Synopsis
+#Determines if this CIDR is contained within (is subnet of)
+#the provided CIDR address or NetAddr::CIDR object.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# puts "#{cidr4.desc} is contained within 192.168.0.0/23" if ( cidr4.is_contained?('192.168.0.0/23') )
+#
+#===Arguments:
+#* CIDR address or NetAddr::CIDR object
+#
+#===Returns:
+#* true or false
+#
+    def is_contained?(cidr)
+        is_contained = false
+
+        if (!cidr.kind_of?(NetAddr::CIDR))
+            begin
+                cidr = NetAddr::CIDR.create(cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        if (cidr.version != @version)
+            raise VersionError, "Attempted to compare a version #{cidr.version} CIDR " +
+                                 "with a version #{@version} CIDR."
+        end
+        
+        network = cidr.packed_network 
+        netmask = cidr.packed_netmask
+        hostmask = cidr.packed_hostmask
+
+        # if network == @network, then we have to go by netmask length
+        # else we can tell by or'ing network and @network by hostmask
+        # and comparing the results
+        if (network == @network)
+            is_contained = true if (@netmask > netmask)
+
+        else
+            if ( (network | hostmask) == (@network | hostmask) )
+                is_contained = true
+            end
+        end
+
+        return(is_contained)
+    end
+
+#==============================================================================#
+# last()
+#==============================================================================#
+
+#===Synopsis
+#Provide last IP address in this CIDR object. The broadcast() method is 
+#aliased to this method, and thus works for IPv6 despite the fact that the 
+#IPv6 protocol does not support IP broadcasting
+#
+# puts cidr4.last() 
+#
+#===Arguments:
+#* Optional Hash with the following keys:
+#    :Objectify -- if true, return NetAddr::CIDR object (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* String or NetAddr::CIDR object.
+#
+    def last(options=nil)
+        known_args = [:Objectify, :Short]
+        objectify = false
+        short = false
+        
+        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?(:Short) && options[:Short] == true )
+                short = true
+            end
+            
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+
+        end
+        
+        packed_ip = @network | @hostmask
+        if (!objectify)
+            ip = NetAddr.unpack_ip_addr(packed_ip, :Version => @version)
+            ip = NetAddr.shorten(ip) if (short && !objectify && @version == 6)
+        else
+            ip = NetAddr::CIDR.create(packed_ip, :Version => @version)
+        end
+
+        return(ip)
+    end
+    
+    alias :broadcast :last
+
+#==============================================================================#
+# multicast_mac()
+#==============================================================================#
+
+#===Synopsis
+#Assuming this CIDR is a valid multicast address (224.0.0.0/4 for IPv4 
+#and ff00::/8 for IPv6), return its ethernet MAC address (EUI-48) mapping.
+#MAC address is based on original IP address passed during initialization.
+#
+# mcast = NetAddr::CIDR.create('224.0.0.6')
+# puts mcast.multicast_mac.address
+#
+#===Arguments:
+#* Optional Hash with the following keys:
+#    :Objectify -- if true, return EUI objects (optional)
+#
+#===Returns:
+#* String or NetAddr::EUI48 object
+#
+    def multicast_mac(options=nil)
+        known_args = [:Objectify]
+        objectify = false
+        
+        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
+        end
+        
+        if (@version == 4)
+            if (@ip & 0xf0000000 == 0xe0000000)
+                # map low order 23-bits of ip to 01:00:5e:00:00:00
+                mac = @ip & 0x007fffff | 0x01005e000000
+            else
+                raise ValidationError, "#{self.ip} is not a valid multicast address. IPv4 multicast " +
+                      "addresses should be in the range 224.0.0.0/4."
+            end
+        else
+            if (@ip & (0xff << 120) == 0xff << 120)
+                # map low order 32-bits of ip to 33:33:00:00:00:00
+                mac = @ip & (2**32-1) | 0x333300000000
+            else
+                raise ValidationError, "#{self.ip} is not a valid multicast address. IPv6 multicast " +
+                      "addresses should be in the range ff00::/8."
+            end             
+        end
+        
+        eui = NetAddr::EUI48.new(mac)
+        eui = eui.address if (!objectify)
+
+        return(eui)
+    end
+
+#==============================================================================#
+# netmask()
+#==============================================================================#
+
+#===Synopsis
+#Provide netmask in CIDR format (/yy).
+#
+# puts cidr4.netmask()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* String
+#
+    def netmask()
+        bits = NetAddr.unpack_ip_netmask(@netmask)
+        return("/#{bits}")
+    end
+
+#==============================================================================#
+# netmask_ext()
+#==============================================================================#
+
+#===Synopsis
+#Provide IPv4 netmask in extended format (y.y.y.y).
+#
+# puts cidr4.netmask_ext()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* String
+#
+    def netmask_ext()    
+        if (@version == 4)
+            return(NetAddr.unpack_ip_addr(@netmask))
+        else
+            return(nil)
+        end
+    end
+
+#==============================================================================#
+# network()
+#==============================================================================#
+
+#===Synopsis
+#Provide base network address.
+#
+# puts cidr4.network()
+#
+#===Arguments:
+#* Optional Hash with the following fields:
+#    :Objectify -- if true, return NetAddr::CIDR object (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* String or NetAddr::CIDR object.
+#
+    def network(options=nil)
+        known_args = [:Objectify, :Short]
+        objectify = false
+        short = false
+        
+        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?(:Short) && options[:Short] == true )
+                short = true
+            end
+            
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+        end
+
+            
+        if (!objectify)
+            ip = NetAddr.unpack_ip_addr(@network, :Version => @version)
+            ip = NetAddr.shorten(ip) if (short && @version == 6)
+        else
+            ip = NetAddr::CIDR.create(@network, :Version => @version)
+        end
+
+        return(ip)
+    end
+
+    alias :base :network
+    alias :first :network
+
+#==============================================================================#
+# next_ip()
+#==============================================================================#
+
+#===Synopsis
+#Provide the next IP following the last available IP within this CIDR object.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# cidr6 = NetAddr::CIDR.create('fec0::/64')
+# puts "cidr4 next subnet #{cidr4.next_subnet()}"
+# puts "cidr6 next subnet #{cidr6.next_subnet(:Short => true)}" 
+#
+#===Arguments:
+#* Optional Hash with the following keys:
+#     :Bitstep -- step in X sized steps - Integer (optional)
+#     :Objectify -- if true, return NetAddr::CIDR object (optional)
+#     :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* String or NetAddr::CIDR object.
+#
+    def next_ip(options=nil)
+        known_args = [:Bitstep, :Objectify, :Short]
+        bitstep = 1
+        objectify = false
+        short = false
+        
+        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?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+            
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+        end
+        
+        next_ip = @network + @hostmask + bitstep
+        
+        if (next_ip > @all_f)
+            raise BoundaryError, "Returned IP is out of bounds for IPv#{@version}."
+        end
+
+                
+        if (!objectify)
+            next_ip = NetAddr.unpack_ip_addr(next_ip, :Version => @version)
+            next_ip = NetAddr.shorten(next_ip) if (short && @version == 6)
+        else
+            next_ip = NetAddr::CIDR.create(next_ip, :Version => @version)
+        end
+        
+        return(next_ip)
+    end
+
+#==============================================================================#
+# next_subnet()
+#==============================================================================#
+
+#===Synopsis
+#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')
+#   puts "cidr4 next subnet #{cidr4.next_subnet()}"
+#   puts "cidr6 next subnet #{cidr6.next_subnet(:Short => true)}" 
+#
+#===Arguments:
+#* Optional Hash with the following keys:
+#    :Bitstep -- step in X sized steps. - Integer (optional)
+#    :Objectify -- if true, return NetAddr::CIDR object (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* String or NetAddr::CIDR object.
+#
+    def next_subnet(options=nil)
+        known_args = [:Bitstep, :Objectify, :Short]
+        bitstep = 1
+        objectify = false
+        short = false
+        
+        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?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+            
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+        end
+        
+        bitstep = bitstep * (2**(@max_bits - self.bits) )
+        next_sub = @network + bitstep
+        
+        if (next_sub > @all_f)
+            raise BoundaryError, "Returned subnet is out of bounds for IPv#{@version}."
+        end
+      
+        if (!objectify)
+            next_sub = NetAddr.unpack_ip_addr(next_sub, :Version => @version)
+            next_sub = NetAddr.shorten(next_sub) if (short && @version == 6)        
+            next_sub = next_sub << "/" << self.bits.to_s
+        else
+            next_sub = NetAddr::CIDR.create(next_sub, 
+                                            :PackedNetmask => self.packed_netmask, 
+                                            :Version => @version)
+        end
+        
+        return(next_sub)
+    end
+
+#==============================================================================#
+# nth()
+#==============================================================================#
+
+#===Synopsis
+#Provide the nth IP within this object.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# puts cidr4.nth(1)
+# puts cidr4.nth(:Index => 1, :Objectify => true
+#
+#===Arguments:
+#* Index number as an Integer
+#* Optional Hash with the following keys:
+#    :Objectify -- if true, return NetAddr::CIDR objects (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* String or NetAddr::CIDR object.
+#
+    def nth(index, options=nil)
+        known_args = [:Objectify, :Short]
+        objectify = false
+        short = false
+
+        # validate list
+        raise ArgumentError, "Integer expected for argument 'index' but " +
+                             "#{index.class} provided." if (!index.kind_of?(Integer) )
+    
+        # validate options
+        if (options)     
+            raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash) )
+            NetAddr.validate_args(options.keys,known_args)
+
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                    objectify = true
+            end
+        end
+        
+        my_ip = @network + index
+        if ( (@hostmask | my_ip) == (@hostmask | @network) )
+            
+            if (!objectify)
+                my_ip = NetAddr.unpack_ip_addr(my_ip, :Version => @version)
+                my_ip = NetAddr.shorten(my_ip) if (short && @version == 6)
+            else
+                my_ip = NetAddr::CIDR.create(my_ip, :Version => @version)
+            end
+
+        else
+            raise BoundaryError, "Index of #{index} returns IP that is out of " +
+                                 "bounds of CIDR network."
+        end
+
+        return(my_ip)
+    end
+
+#==============================================================================#
+# packed_hostmask()
+#==============================================================================#
+
+#===Synopsis
+#Provide an Integer representation of the Hostmask of this object.
+#
+# puts cidr4.packed_hostmask().to_s(16)
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* Integer
+#
+    def packed_hostmask()
+        return(@hostmask)
+    end
+
+#==============================================================================#
+# packed_ip()
+#==============================================================================#
+
+#===Synopsis
+#Provide an Integer representation of the IP address of this object.
+#
+# puts cidr4.packed_ip().to_s(16)
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* Integer
+#
+    def packed_ip()
+        return(@ip)
+    end
+
+#==============================================================================#
+# packed_netmask()
+#==============================================================================#
+
+#===Synopsis
+#Provide an Integer representation of the Netmask of this object.
+#
+# puts cidr4.packed_netmask().to_s(16)
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* Integer
+#
+    def packed_netmask()
+        return(@netmask)
+    end
+
+#==============================================================================#
+# packed_network()
+#==============================================================================#
+
+#===Synopsis
+#Provide an Integer representation of the Network address of this object.
+#
+# packed = cidr4.packed_network().to_s(16)
+#
+#===Arguments:
+#* none
+# 
+#===Returns:
+#* Integer
+#
+    def packed_network()
+        return(@network)
+    end
+
+#==============================================================================#
+# range()
+#==============================================================================#
+
+#===Synopsis
+#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. 
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# list = cidr4.range(0, 1)
+# list = cidr4.range(0, 1, :Objectify => true)
+# list = cidr4.range(0, nil, :Objectify => true)
+#
+#===Arguments:
+#* Lower range boundary index as an Integer
+#* Upper range boundary index as an Integer
+#* Optional Hash with the following keys:
+#    :Bitstep -- enumerate in X sized steps - Integer (optional)
+#    :Objectify -- if true, return NetAddr::CIDR objects (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* Array of Strings, or Array of NetAddr::CIDR objects
+#
+    def range(lower, upper=nil, options=nil)
+        known_args = [:Bitstep, :Objectify, :Short]
+        objectify = false
+        short = false
+        bitstep = 1
+
+        # validate indexes
+        raise ArgumentError, "Integer expected for argument 'lower' " +
+                             "but #{lower.class} provided." if (!lower.kind_of?(Integer))
+        
+        raise ArgumentError, "Integer expected for argument 'upper' " +
+                             "but #{upper.class} provided." if (upper && !upper.kind_of?(Integer))
+            
+        upper = @hostmask if (upper.nil?)
+        indexes = [lower,upper]
+        indexes.sort!
+        if ( (indexes[0] < 0) || (indexes[0] > self.size) )
+            raise BoundaryError, "Index #{indexes[0]} is out of bounds for this CIDR."
+        end
+        
+        if (indexes[1] >= self.size)
+            raise BoundaryError, "Index #{indexes[1]} is out of bounds for this CIDR."
+        end
+        
+        # validate options
+        if (options)     
+            raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash) )
+            NetAddr.validate_args(options.keys,known_args)
+            
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+        
+            if( options.has_key?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+        end
+        
+        # make range
+        start_ip = @network + indexes[0]
+        end_ip = @network + indexes[1]
+        my_ip = start_ip
+        list = []
+        until (my_ip > end_ip)            
+            if (!objectify)
+                ip = NetAddr.unpack_ip_addr(my_ip, :Version => @version)
+                ip = NetAddr.shorten(ip) if (short && @version == 6)
+            else
+                ip = NetAddr::CIDR.create(:PackedIP => my_ip, :Version => @version)
+            end
+            
+            list.push(ip)
+            my_ip += bitstep
+        end
+
+        return(list)
+    end
+
+#==============================================================================#
+# remainder()
+#==============================================================================#
+
+#===Synopsis
+#Given a single subnet of the current CIDR, provide the remainder of
+#the subnets. For example if the original CIDR is 192.168.0.0/24 and you
+#provide 192.168.0.64/26 as the portion to exclude, then 192.168.0.0/26,
+#and 192.168.0.128/25 will be returned as the remainders.
+#
+# cidr4.remainder('192.168.1.32/27').each {|x| puts x}
+# cidr4.remainder(:Exclude => '192.168.1.32/27', :Objectify => true).each {|x| puts x.desc}
+#
+#===Arguments:
+#* CIDR address or NetAddr::CIDR object
+#* Optional Hash with the following keys:
+#    :Objectify -- if true, return NetAddr::CIDR objects (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* Array of Strings, or Array of NetAddr::CIDR objects
+#
+    def remainder(addr, options=nil)
+        known_args = [:Objectify, :Short]
+        short = nil
+        objectify = nil
+        
+        # validate options
+        if (options)     
+            raise ArgumentError, "Hash expected for argument 'options' but " +
+                                 "#{options.class} provided." if (!options.kind_of?(Hash) )
+            NetAddr.validate_args(options.keys,known_args)
+            
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end        
+        end
+        
+        if ( !addr.kind_of?(NetAddr::CIDR) )
+            begin
+                addr = NetAddr::CIDR.create(addr)
+            rescue Exception => error
+                raise ArgumentError, "Argument 'addr' raised the following " +
+                                     "errors: #{error}"
+            end
+        end
+        
+        
+        # make sure 'addr' is the same ip version
+        if ( addr.version != @version )
+            raise VersionError, "#{addr.desc(:Short => true)} is of a different " +
+                                "IP version than #{self.desc(:Short => true)}."
+        end    
+
+        # make sure we contain 'to_exclude'
+        if ( self.contains?(addr) != true )
+            raise BoundaryError, "#{addr.desc(:Short => true)} does not fit " +
+                                 "within the bounds of #{self.desc(:Short => true)}."
+        end
+
+        # split this cidr in half & see which half 'to_exclude'
+        # 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**(@max_bits - new_mask)
+        
+        new_subnets = []
+        until(new_mask > addr.bits)
+            if (addr.packed_network < upper_network)
+                match = lower_network
+                non_match = upper_network
+            else
+                match = upper_network
+                non_match = lower_network
+            end
+
+            
+            if (!objectify)
+                non_match = NetAddr.unpack_ip_addr(non_match, :Version => @version)
+                non_match = NetAddr.shorten(non_match) if (short && @version == 6)
+                new_subnets.unshift("#{non_match}/#{new_mask}")
+            else
+                new_subnets.unshift(NetAddr::CIDR.create(non_match, 
+                                                         :PackedNetmask => NetAddr.pack_ip_netmask(new_mask), 
+                                                         :Version => @version))
+            end
+            
+            new_mask = new_mask + 1
+            lower_network = match
+            upper_network = match + 2**(@max_bits - new_mask)
+        end
+        
+        return(new_subnets)
+    end
+
+#==============================================================================#
+# resize()
+#==============================================================================#
+
+#===Synopsis
+#Resize the CIDR by changing the size of the Netmask. 
+#Return the resulting CIDR as a new object.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# new_cidr = cidr4.resize(23)
+# puts new_cidr.desc
+#
+#===Arguments:
+#* Netmask as an Integer
+#
+#===Returns:
+#* NetAddr::CIDR object
+#
+    def resize(bits)
+        raise Argumenterror, "Integer or Hash expected, but " +
+                                 "#{bits.class} provided." if (!bits.kind_of?(Integer))
+        
+        NetAddr.validate_ip_netmask(bits, :Version => @version)
+        netmask = NetAddr.pack_ip_netmask(bits, :Version => @version)
+        network = @network & netmask
+        
+        cidr = NetAddr::CIDR.create(network, :PackedNetmask => netmask, :Version => @version)
+        return(cidr)
+    end
+
+#==============================================================================#
+# resize!()
+#==============================================================================#
+
+#===Synopsis
+#Resize the current CIDR by changing the size of the Netmask. The original IP
+#passed during initialization will be set to the base network address if
+#it no longer falls within the bounds of the CIDR.
+#
+# cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
+# new_cidr = cidr4.resize(23)
+# puts new_cidr.desc 
+#
+#===Arguments:
+#* Netmask as an Integer
+#
+#===Returns:
+#* True
+#
+    def resize!(bits)
+        raise Argumenterror, "Integer or Hash expected, but " +
+                                 "#{bits.class} provided." if (!bits.kind_of?(Integer))
+        
+        NetAddr.validate_ip_netmask(bits, :Version => @version)
+        netmask = NetAddr.pack_ip_netmask(bits, :Version => @version)
+        
+        @netmask = netmask
+        @network = @network & netmask
+        @hostmask = @netmask ^ @all_f
+        
+        # check @ip
+        if ((@ip & @netmask) != (@network))
+            @ip = @network
+        end
+        
+        return(true)
+    end
+
+#==============================================================================#
+# size()
+#==============================================================================#
+
+#===Synopsis
+#Provide number of IP addresses within this object.
+#
+# puts cidr4.size()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* Integer
+#
+    def size()
+        return(@hostmask + 1)
+    end
+
+#==============================================================================#
+# subnet()
+#==============================================================================#
+
+#===Synopsis
+#Subnet this object. There are 2 ways to subnet:
+#   * By providing the netmask (in bits) of the new subnets in :Bits.
+#   * By providing the number of IP addresses needed in the new subnets in :IPCount
+#
+#:NumSubnets is used to determine how the CIDR is subnetted. For example, if I request
+#the following operation:
+#
+# NetAddr::CIDR.create('192.168.1.0/24').subnet(:Bits => 26, :NumSubnets => 1)
+#
+#then I would get back the first /26 subnet of 192.168.1.0/24 and the remainder of the IP
+#space as summary CIDR addresses (e.g. 192.168.1.0/26, 192.168.1.64/26, and 192.168.1.128/25).
+#If I were to perform the same operation without the :NumSubnets directive, then 192.168.1.0/24
+#will be fully subnetted into X number of /26 subnets (e.g. 192.168.1.0/26, 192.168.1.64/26, 
+#192.168.1.128/26, and 192.168.1.192/26). 
+#
+#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.
+#
+# cidr_list = cidr4.subnet(:Bits => 28, :NumSubnets => 3).each {|x| puts "  #{x}"}
+# cidr_list = cidr4.subnet(:IPCount => 19).each {|x| puts "  #{x}"}
+# cidr4.subnet(:Bits => 28).each {|x| puts "  #{x}"}  "
+# cidr6.subnet(:Bits => 67, :NumSubnets => 4, :Short => true).each {|x| puts "  #{x}"}
+#
+#===Arguments:
+#* Optional Hash with the following keys:
+#    :Bits --  Netmask (in bits) of new subnets - Integer (optional)
+#    :IPCount -- Minimum number of IP's that new subnets should contain - Integer (optional)
+#    :NumSubnets -- Number of X sized subnets to return - Integer (optional)
+#    :Objectify -- if true, return NetAddr::CIDR objects (optional)
+#    :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+#===Returns:
+#* Array of Strings, or Array of NetAddr::CIDR objects
+#
+    def subnet(options=nil)
+        known_args = [:Bits, :IPCount, :NumSubnets, :Objectify, :Short]
+        my_network = self.packed_network
+        my_mask = self.bits
+        subnet_bits = my_mask + 1
+        min_count = nil 
+        objectify = false
+        short = false       
+        
+        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?(:IPCount) )
+                subnet_bits = NetAddr.minimum_size(options[:IPCount], :Version => @version)
+            end
+            
+            if ( options.has_key?(:Bits) )
+                subnet_bits = options[:Bits]
+            end
+            
+            if ( options.has_key?(:NumSubnets) )
+                num_subnets = options[:NumSubnets]
+            end
+            
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+            
+        end
+
+        # get number of subnets possible with the requested subnet_bits
+        num_avail = 2**(subnet_bits - my_mask)        
+
+        # get the number of bits in the next supernet and
+        # make sure num_subnets is a power of 2
+        bits_needed = 1
+        num_subnets = num_avail if (!num_subnets)
+        until (2**bits_needed >= num_subnets)
+            bits_needed += 1
+        end
+        num_subnets = 2**bits_needed
+        next_supernet_bits = subnet_bits - bits_needed
+        
+
+        # make sure subnet isnt bigger than available bits
+        if (subnet_bits > @max_bits)
+            raise BoundaryError, "Requested subnet (#{subnet_bits}) does not fit " +
+                  "within the bounds of IPv#{@version}."
+        end
+
+        # make sure subnet is larger than mymask
+        if (subnet_bits < my_mask)
+            raise BoundaryError, "Requested subnet (#{subnet_bits}) is too large for " +
+                  "current CIDR space."
+        end
+
+        # make sure MinCount is smaller than available subnets
+        if (num_subnets > num_avail)
+            raise "Requested subnet count (#{num_subnets}) exceeds subnets " +
+                  "available for allocation (#{num_avail})."
+        end
+
+        # list all 'subnet_bits' sized subnets of this cidr block
+        # with a limit of num_subnets
+        bitstep = 2**(@max_bits - subnet_bits)
+        subnets = self.enumerate(:Bitstep => bitstep, :Limit => num_subnets)
+
+        # save our subnets
+        new_subnets = []
+        subnets.each do |subnet|
+            if (!objectify)
+                subnet = NetAddr.shorten(subnet) if (short && @version == 6)
+                new_subnets.push("#{subnet}/#{subnet_bits}")
+            else            
+                new_subnets.push(NetAddr::CIDR.create("#{subnet}/#{subnet_bits}", :Version => @version))
+            end
+        end
+
+        # now go through the rest of the cidr space and make the rest
+        # of the subnets. we want these to be as tightly merged as possible
+        next_supernet_bitstep = (bitstep * num_subnets)
+        next_supernet_ip = my_network + next_supernet_bitstep
+        until (next_supernet_bits == my_mask)
+            if (!objectify)
+                next_network = NetAddr.unpack_ip_addr(next_supernet_ip, :Version => @version)
+                next_network = NetAddr.shorten(next_network) if (short && @version == 6)
+                new_subnets.push("#{next_network}/#{next_supernet_bits}")
+            else
+                new_subnets.push(NetAddr::CIDR.create(next_supernet_ip,
+                                                      :PackedNetmask => NetAddr.pack_ip_netmask(next_supernet_bits),
+                                                      :Version => @version))
+            end
+            
+            next_supernet_bits -= 1
+            next_supernet_ip = next_supernet_ip + next_supernet_bitstep
+            next_supernet_bitstep = next_supernet_bitstep << 1
+        end
+
+        return(new_subnets)
+    end
+
+
+# PRIVATE INSTANCE METHODS
+private
+
+
+#==============================================================================#
+# make_subnets_from_base_and_ip_count()
+#==============================================================================#
+
+# Make CIDR addresses from a base addr and an number of ip's to encapsulate.
+#
+#===Arguments:
+#   * base ip as packed integer
+#   * number of ip's required
+#
+#===Returns:
+#   * array of NetAddr::CIDR objects
+#
+    def make_subnets_from_base_and_ip_count(base_addr,ip_count)
+        list = []        
+        until (ip_count == 0)
+            mask = @all_f
+            multiplier = 0
+            bitstep = 0
+            last_addr = base_addr
+            done = false
+            until (done == true)
+                if (bitstep < ip_count && (base_addr & mask == last_addr & mask) )
+                    multiplier += 1
+                elsif (bitstep > ip_count || (base_addr & mask != last_addr & mask) )
+                    multiplier -= 1
+                    done = true
+                else
+                    done = true
+                end                
+                bitstep = 2**multiplier
+                mask = @all_f << multiplier & @all_f
+                last_addr = base_addr + bitstep - 1
+            end          
+            
+            list.push(NetAddr::CIDR.create(base_addr,
+                                           :PackedNetmask => mask,
+                                           :Version => self.version))
+            ip_count -= bitstep
+            base_addr += bitstep
+        end
+        
+        return(list)
+    end
+
+end # end class CIDR
+
+
+
+# IPv4 CIDR address - Inherits all methods from NetAddr::CIDR. 
+# Addresses of this class are composed of a 32-bit address space.
+class CIDRv4 < CIDR
+
+public_class_method :new
+
+#==============================================================================#
+# initialize()
+#==============================================================================#
+
+#===Synopsis
+#Return a CIDRv4 object.
+#CIDR formatted netmasks take precedence over extended formatted ones.
+#CIDR address defaults to a host network (/32) if netmask not provided.
+#:PackedNetmask takes precedence over netmask given within CIDR address.
+#
+# cidr4 = NetAddr::CIDRv4.new('192.168.1.1/24')
+# cidr4 = NetAddr::CIDRv4.new('192.168.1.1 255.255.255.0')
+# cidr4_2 = NetAddr::CIDRv4.new(0x0a010001,
+#                               :PackedNetmask => 0xffffff00)
+#
+#===Arguments:
+#* CIDR address as a String, or a packed IP address as an Integer
+#* Optional Hash with the following keys:
+#     :PackedNetmask -- Integer representation of an IP Netmask (optional)
+#     :Tag -- Custom descriptor tag - Hash, tag => value. (optional)
+#
+    def initialize(addr, options=nil)
+        known_args = [:PackedNetmask, :Tag]
+        @tag = {}
+        @version = 4
+        @max_bits = 32
+        @all_f = 2**@max_bits - 1
+        
+        # validate addr arg
+        if (addr.kind_of?(String))
+            cidr = addr
+        elsif (addr.kind_of?(Integer))
+            packed_ip = addr
+        else
+            raise ArgumentError, "String or Integer expected for argument 'addr' but #{addr.class} provided."
+        end
+        
+        # validate options
+        if (options)     
+            raise ArgumentError, "Hash expected for argument 'options' but " +
+                                 "#{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))
+            end    
+        
+            if (options.has_key?(:Tag))
+                @tag = options[:Tag]
+                if (!@tag.kind_of? Hash)
+                    raise ArgumentError, "Expected Hash, but #{@tag.class} provided for option :Tag."
+                end
+            end
+        end
+        
+        
+        if (packed_ip)
+            # validate & store packed_ip
+            NetAddr.validate_ip_addr(packed_ip, :Version => @version)
+            @ip = packed_ip
+        
+        else           
+            # if extended netmask provided. should only apply to ipv4            
+            if (cidr =~ /.+\s+.+/ )
+                cidr,netmask = cidr.split(' ')
+            end           
+   
+            # if netmask part of cidr, then over-ride any provided extended netmask.
+            if (cidr =~ /\//) 
+                ip,netmask = cidr.split(/\//)
+                if (!ip || !netmask)
+                    raise ArgumentError, "CIDR address is improperly formatted. Missing netmask after '/' character." 
+                end
+            else
+                ip = cidr
+            end
+            
+            # pack ip                
+            @ip = NetAddr.pack_ip_addr(ip, :Version => @version)           
+        end
+        
+        # if no netmask or packed_netmask, then set
+        # else validate. packed_netmask takes precedence over netmask
+        if (!netmask && !packed_netmask)
+            @netmask = @all_f
+        else            
+            if (packed_netmask)
+                NetAddr.validate_ip_netmask(packed_netmask, :Packed => true, :Version => @version)
+                @netmask = packed_netmask
+            else
+                NetAddr.validate_ip_netmask(netmask, :Version => @version)
+                @netmask = NetAddr.pack_ip_netmask(netmask, :Version => @version)
+            end
+        end
+        
+        # set @network & @hostmask
+        @network = (@ip & @netmask)
+        @hostmask = @netmask ^ @all_f
+
+    end
+
+end
+
+
+# IPv6 CIDR address - Inherits all methods from NetAddr::CIDR. 
+# Addresses of this class are composed of a 128-bit address space.
+class CIDRv6 < CIDR
+
+public_class_method :new
+
+#==============================================================================#
+# initialize()
+#==============================================================================#
+
+#===Synopsis
+#Return a CIDRv6 object.
+#CIDR formatted netmasks take precedence over extended formatted ones.
+#CIDR address defaults to a host network (/128) if netmask not provided.
+#:PackedNetmask takes precedence over netmask given within CIDR address.
+#
+# cidr6 = NetAddr::CIDRv6.new('fec0::/64')
+# cidr6 = NetAddr::CIDRv6.new('fec0::/64',
+#                             :Tag => {'interface' => 'g0/1'})
+# cidr6_2 = NetAddr::CIDRv6.new('::ffff:192.168.1.1/96')
+#
+#===Arguments:
+#* CIDR address as a String, or a packed IP address as an Integer
+#* Optional Hash with the following keys:
+#     :PackedNetmask -- Integer representation of an IP Netmask (optional)
+#     :Tag -- Custom descriptor tag - Hash, tag => value. (optional)
+#
+    def initialize(addr, options=nil)
+        known_args = [:PackedNetmask, :Tag]
+        @tag = {}
+        @version = 6
+        @max_bits = 128
+        @all_f = 2**@max_bits - 1
+        
+        # validate addr arg
+        if (addr.kind_of?(String))
+            cidr = addr
+        elsif (addr.kind_of?(Integer))
+            packed_ip = addr
+        else
+            raise ArgumentError, "String or Integer expected for argument 'addr' but #{addr.class} provided."
+        end
+        
+        # validate options
+        if (options)     
+            raise ArgumentError, "Hash expected for argument 'options' but " +
+                                 "#{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))
+            end    
+        
+            if (options.has_key?(:Tag))
+                @tag = options[:Tag]
+                if (!@tag.kind_of? Hash)
+                    raise ArgumentError, "Expected Hash, but #{@tag.class} provided for option :Tag."
+                end
+            end
+        end
+        
+        
+        if (packed_ip) 
+            # validate & store packed_ip
+            NetAddr.validate_ip_addr(packed_ip, :Version => @version)
+            @ip = packed_ip
+        
+        else           
+            # if ipv6 and extended netmask was provided, then raise exception
+            raise ArgumentError, "Garbage provided at end of IPv6 address." if (cidr =~ /.+\s+.+/ )    
+            
+            # get ip and netmask
+            if (cidr =~ /\//) 
+                ip,netmask = cidr.split(/\//)
+                if (!ip || !netmask)
+                    raise ArgumentError, "CIDR address is improperly formatted. Missing netmask after '/' character." 
+                end
+            else
+                ip = cidr
+            end
+            
+            # pack ip                
+            @ip = NetAddr.pack_ip_addr(ip, :Version => @version)           
+        end
+
+        # if no netmask or packed_netmask, then set
+        # else validate. packed_netmask takes precedence over netmask
+        if (!netmask && !packed_netmask)
+            @netmask = @all_f
+        else            
+            if (packed_netmask)
+                NetAddr.validate_ip_netmask(packed_netmask, :Packed => true, :Version => @version)
+                @netmask = packed_netmask
+            else
+                NetAddr.validate_ip_netmask(netmask, :Version => @version)
+                @netmask = NetAddr.pack_ip_netmask(netmask, :Version => @version)
+            end
+        end
+        
+        # set @network & @hostmask
+        @network = (@ip & @netmask)
+        @hostmask = @netmask ^ @all_f
+
+    end
+
+end
+
+end # module NetAddr
+__END__