ipadmin 0.3.0 → 0.4.0

data/lib/cidr.rb

@@ -1,9 +1,3 @@
-=begin rdoc
- Copyright (c) 2006 Dustin Spinhirne -  
- Licensed under the same terms as Ruby, No Warranty is provided.
-=end
-
-
 module IPAdmin
 class CIDR
 
@@ -26,6 +20,9 @@ class CIDR
 
     # 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.
     #
@@ -50,7 +47,7 @@ class CIDR
 #==============================================================================#
 
 # - Arguments:
-#   * Hash with the following fields:
+#   * CIDR address as a string, or a Hash with the following fields:
 #       - :CIDR -- IP address in CIDR notation - String (optional)
 #       - :Netmask -- IP Netmask - String or Integer (optional)
 #       - :PackedIP -- Integer representation of an IP address (optional)
@@ -66,7 +63,8 @@ class CIDR
 #   * Netmask within :CIDR takes precedence over :Netmask.
 #   * Version will be auto-detected if not specified
 #
-# Example:
+# Examples:
+#   cidr4 = IPAdmin::CIDR.new('192.168.1.1/24')
 #   cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.1/24')
 #   cidr4_2 = IPAdmin::CIDR.new(:PackedIP => 0x0a010001,
 #                               :PackedNetmask => 0xffffff00
@@ -76,47 +74,51 @@ class CIDR
 #   cidr6_2 = IPAdmin::CIDR.new(:CIDR => '::ffff:192.168.1.1/96')
 #
     def initialize(options)
-        if (!options.kind_of? Hash)
-            raise ArgumentError, "Expected Hash, but #{options.class} provided."
+        @tag = {}
+        if (!options.kind_of?(Hash) && !options.kind_of?(String))
+            raise ArgumentError, "Expected Hash or String, but #{options.class} provided."
         end
 
-
-        if (options.has_key?(:PackedIP))
-            packed_ip = options[:PackedIP]
-            raise ArgumentError, "Expected Integer, but #{packed_ip.class} " +
-                                 "provided for option :PackedIP." if (!packed_ip.kind_of?(Integer))
-        elsif (options.has_key?(:CIDR))
-            cidr =  options[:CIDR]
-            raise ArgumentError, "Expected String, but #{cidr.class} " +
-                                 "provided for option :CIDR." if (!cidr.kind_of?(String))      
-        else
-            raise ArgumentError, "Missing argument: CIDR or PackedIP."
-        end        
-        
+        if (options.kind_of? String)
+            cidr = options
+        end
         
-        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))
-
-        elsif (options.has_key?(:Netmask))
-            netmask = options[:Netmask]
-            raise ArgumentError, "Expected String or Integer, but #{netmask.class} " +
-                                 "provided for option :Netmask." if (!netmask.kind_of?(String) && !netmask.kind_of?(Integer))
-        end      
+        if (options.kind_of? Hash) 
+            if (options.has_key?(:PackedIP))
+                packed_ip = options[:PackedIP]
+                raise ArgumentError, "Expected Integer, but #{packed_ip.class} " +
+                                     "provided for option :PackedIP." if (!packed_ip.kind_of?(Integer))
+            elsif (options.has_key?(:CIDR))
+                cidr =  options[:CIDR]
+                raise ArgumentError, "Expected String, but #{cidr.class} " +
+                                     "provided for option :CIDR." if (!cidr.kind_of?(String))      
+            else
+                raise ArgumentError, "Missing argument: CIDR or PackedIP."
+            end        
         
+            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))
+
+            elsif (options.has_key?(:Netmask))
+                netmask = options[:Netmask]
+                raise ArgumentError, "Expected String or Integer, but #{netmask.class} " +
+                                     "provided for option :Netmask." if (!netmask.kind_of?(String) && !netmask.kind_of?(Integer))
+            end    
         
-        if (options.has_key?(:Version))
-            @version = options[:Version]
-            if (@version != 4 && @version != 6)
-                raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+            if (options.has_key?(:Version))
+                @version = options[:Version]
+                if (@version != 4 && @version != 6)
+                    raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+                end
             end
-        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."
+            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
         
@@ -156,8 +158,7 @@ class CIDR
                 @netmask = 2**128-1 if (!netmask && !packed_netmask)
             end
 
-            # validate & pack ip
-            IPAdmin.validate_ip_addr(:IP => ip, :Version => @version)                
+            # pack ip                
             @ip = IPAdmin.pack_ip_addr(:IP => ip, :Version => @version)            
             
         end
@@ -208,8 +209,8 @@ class CIDR
 # - Returns:
 #   * String
 #
-# Example:
-#   arpa = cidr4.arpa() --> '1.168.192.in-addr.arpa.'
+# Examples:
+#   arpa = cidr4.arpa()
 #
     def arpa()
 
@@ -270,8 +271,8 @@ class CIDR
 # - Returns:
 #   * Integer.
 #
-# Example:
-#   puts cidr4.bits()   --> 24
+# Examples:
+#   puts cidr4.bits()
 #
     def bits()
         return(IPAdmin.unpack_ip_netmask(:Integer => @netmask))
@@ -287,33 +288,35 @@ class CIDR
 #==============================================================================#
 
 # Determines if this CIDR contains (is supernet of)
-# the provided CIDR object.
+# the provided CIDR addresss or IPAdmin::CIDR object.
 #
 # - Arguments:
-#   * CIDR object
+#   * CIDR addresss or IPAdmin::CIDR object
 #
 # - Returns:
 #   * true or false
 #
-# Example:
-#   cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/26')
-#   contains? = cidr4.contains(cidr4_2)   --> true
+# Examples:
+#   contains? = cidr4.contains('192.168.1.32/27')
 #
-    def contains?(object)
+    def contains?(cidr)
         is_contained = false
 
-        if (object.kind_of?(IPAdmin::CIDR))
-            network = object.packed_network 
-            netmask = object.packed_netmask
-
-        else 
-            raise ArgumentError, "Expected IPAdmin::CIDR " +
-                                 " object but #{object.class} provided."
+        if (!cidr.kind_of?(IPAdmin::CIDR))
+            begin
+                cidr = IPAdmin::CIDR.new(:CIDR => cidr)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
+            end
         end
+        
+        network = cidr.packed_network 
+        netmask = cidr.packed_netmask
 
 
-        if (object.version != @version)
-            raise ArgumentError, "Attempted to compare a version #{object.version} CIDR " +
+        if (cidr.version != @version)
+            raise ArgumentError, "Attempted to compare a version #{cidr.version} CIDR " +
                                  "with a version #{@version} CIDR."
         end
 
@@ -349,11 +352,11 @@ class CIDR
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * String
+#   * CIDR address as a String
 #
-# Example:
-#   puts cidr4.desc()   --> 192.168.1.0/24
-#   puts cidr4.desc(:IP => true)   --> 192.168.1.1/24
+# Examples:
+#   puts cidr4.desc()
+#   puts cidr4.desc(:IP => true)
 #
     def desc(options=nil)
         short = false
@@ -404,10 +407,10 @@ class CIDR
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * Array of Strings or CIDR objects
+#   * Array of IP address Strings or IPAdmin::CIDR objects
 #
-# Example:
-#   ip_list = cidr4.enumerate(:Bitstep => 2, :Limit => 2)   --> ['192.168.1.0','192.168.1.1']
+# Examples:
+#   ip_list = cidr4.enumerate(:Bitstep => 2, :Limit => 2)
 #
     def enumerate(options=nil)
         bitstep = 1
@@ -465,6 +468,127 @@ class CIDR
 #======================================#
 
 
+#==============================================================================#
+# fill_in()
+#==============================================================================#
+
+# Given a list of subnets of the current CIDR, return a new list with any
+# holes (missing subnets) filled in.
+#
+# - Arguments:
+#   * Array of CIDR addresses or IPAdmin::CIDR objects,
+#     or a Hash with the following fields:
+#       - :List -- Array of CIDR addresses or IPAdmin::CIDR objects
+#       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * Array of CIDR address Strings or IPAdmin::CIDR objects
+#
+# Examples:
+#   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)
+#
+
+    def fill_in(options)
+        short = false
+        objectify = false
+
+        # validate options
+        if ( options.kind_of?(Hash) )
+            if (!options.has_key?(:List))
+                raise ArgumentError, "Missing argument: List."
+            end
+    
+            if (options.has_key?(:Short) && options[:Short] == true)
+                short = true
+            end
+    
+            if (options.has_key?(:Objectify) && options[:Objectify] == true)
+                objectify = true
+            end
+
+            # make sure :List is an array
+            if ( !options[:List].kind_of?(Array) )
+                raise ArgumentError, "Expected Array for option :List, " +
+                                     "but #{list.class} provided."
+            end
+            list = options[:List]
+        
+        elsif ( options.kind_of?(Array) )
+            list = options
+        else
+            raise ArgumentError, "Array or Hash expected but #{options.class} provided."
+        end
+
+        # validate each cidr and store in cidr_list
+        cidr_list = []
+        list.each do |obj|
+            if (!obj.kind_of?(IPAdmin::CIDR))
+                begin
+                    obj = IPAdmin::CIDR.new(:CIDR => obj)
+                rescue Exception => error
+                    aise ArgumentError, "A provided CIDR raised the following " +
+                                        "errors: #{error}"
+                end
+            end
+
+            if (!obj.version == self.version)
+                raise "#{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
+        IPAdmin.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(IPAdmin::CIDR.new(:PackedIP => 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()
 #==============================================================================#
@@ -477,8 +601,8 @@ class CIDR
 # - Returns:
 #   * String
 #
-# Example:
-#   puts cidr4.hostmask_ext()   --> 0.0.0.255
+# Examples:
+#   puts cidr4.hostmask_ext()
 #
     def hostmask_ext()
         if (@version == 4)
@@ -507,10 +631,10 @@ class CIDR
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * String or CIDR object.
+#   * IP address String or IPAdmin::CIDR object.
 #
-# Example:
-#   puts cidr4.ip()   --> 192.168.1.1
+# Examples:
+#   puts cidr4.ip()
 #
     def ip(options=nil)
         objectify = false
@@ -560,15 +684,15 @@ class CIDR
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * String or CIDR object.
+#   * IP address String or IPAdmin::CIDR object.
 #
 # - Notes:
 #   * 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.
 #
-# Example:
-#   puts cidr4.last()   --> 192.168.1.255
+# Examples:
+#   puts cidr4.last()
 #
     def last(options=nil)
         objectify = false
@@ -620,14 +744,14 @@ class CIDR
 #       - :Objectify -- if true, return EUI objects (optional)
 #
 # - Returns:
-#   * EUI object
+#   * IPAdmin::EUI48 object
 #
 # - Note:
 #   * MAC address is based on original IP address passed during initialization.
 #
-# Example:
+# Examples:
 #   mcast = IPAdmin::CIDR.new(:CIDR => '224.0.0.6')
-#   puts mcast.multicast_mac.address --> 01-00-5e-00-00-06
+#   puts mcast.multicast_mac.address
 #
     def multicast_mac(options=nil)
         objectify = false
@@ -660,7 +784,7 @@ class CIDR
             end             
         end
         
-        eui = IPAdmin::EUI.new(:PackedEUI => mac)
+        eui = IPAdmin::EUI48.new(:PackedEUI => mac)
         eui = eui.address if (!objectify)
 
         return(eui)
@@ -683,8 +807,8 @@ class CIDR
 # - Returns:
 #   * String
 #
-# Example:
-#   puts cidr4.netmask()   --> /24
+# Examples:
+#   puts cidr4.netmask()
 #
     def netmask()
         bits = IPAdmin.unpack_ip_netmask(:Integer => @netmask)
@@ -708,8 +832,8 @@ class CIDR
 # - Returns:
 #   * String
 #
-# Example:
-#   puts cidr4.netmask_ext()   --> 255.255.255.0
+# Examples:
+#   puts cidr4.netmask_ext()
 #
     def netmask_ext()    
         if (@version == 4)
@@ -739,10 +863,10 @@ class CIDR
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * String or CIDR object.
+#   * CIDR address String or IPAdmin::CIDR object.
 #
-# Example:
-#   puts cidr4.network()   --> 192.168.1.0
+# Examples:
+#   puts cidr4.network()
 #
     def network(options=nil)
         objectify = false
@@ -796,10 +920,10 @@ class CIDR
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * String or CIDR object.
+#   * IP address String or IPAdmin::CIDR object.
 #
-# Example:
-#   puts cidr4.next_ip()   --> 192.168.2.0
+# Examples:
+#   puts cidr4.next_ip()
 #
     def next_ip(options=nil)
         bitstep = 1
@@ -861,10 +985,10 @@ class CIDR
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * String or CIDR object.
+#   * CIDR address String or IPAdmin::CIDR object.
 #
-# Example:
-#   puts cidr4.next_subnet()   --> 192.168.2.0/24
+# Examples:
+#   puts cidr4.next_subnet()
 #
     def next_subnet(options=nil)
         bitstep = 1
@@ -921,39 +1045,42 @@ class CIDR
 # Provide the nth IP within this object.
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * Integer or a Hash with the following fields:
 #       - :Index -- index number of the IP address to return - Integer
 #       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * String or CIDR object.
+#   * IP address String or IPAdmin::CIDR object.
 #
-# Example:
-#   puts cidr4.nth(:Index => 1)   --> 192.168.1.1
+# Examples:
+#   puts cidr4.nth(1)
+#   puts cidr4.nth(:Index => 1, :Objectify => true)
 #
     def nth(options)
         objectify = false
         short = false
 
-        if (!options.kind_of?(Hash))
-            raise ArgumentError, "Expected Hash, but " +
-                                 "#{options.class} provided."
-        end
-        
-        if ( !options.has_key?(:Index) )
-            raise ArgumentError, "Missing argument: Index."
-        end
-        index = options[:Index]
+        if (options.kind_of?(Hash))
+            if ( !options.has_key?(:Index) )
+                raise ArgumentError, "Missing argument: Index."
+            end
+            index = options[:Index]
 
-        if( options.has_key?(:Short) && options[:Short] == true )
-            short = true
-        end
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
         
-        if( options.has_key?(:Objectify) && options[:Objectify] == true )
-                objectify = true
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                    objectify = true
+            end
+        elsif (options.kind_of?(Integer))
+            index = options
+        else
+            raise ArgumentError, "Integer or Hash expected, but " +
+                                 "#{options.class} provided."
         end
-
+        
         my_ip = @network + index
         if ( (@hostmask | my_ip) == (@hostmask | @network) )
             
@@ -989,8 +1116,8 @@ class CIDR
 # - Returns:
 #   * Integer
 #
-# Example:
-#   puts cidr4.packed_hostmask().to_s(16)   --> 0xff
+# Examples:
+#   puts cidr4.packed_hostmask().to_s(16)
 #
     def packed_hostmask()
         return(@hostmask)
@@ -1013,8 +1140,8 @@ class CIDR
 # - Returns:
 #   * Integer
 #
-# Example:
-#   puts cidr4.packed_ip().to_s(16)   --> 0xc0c80101
+# Examples:
+#   puts cidr4.packed_ip().to_s(16)
 #
     def packed_ip()
         return(@ip)
@@ -1037,8 +1164,8 @@ class CIDR
 # - Returns:
 #   * Integer
 #
-# Example:
-#   puts cidr4.packed_netmask().to_s(16)   --> 0xffffff00
+# Examples:
+#   puts cidr4.packed_netmask().to_s(16)
 #
     def packed_netmask()
         return(@netmask)
@@ -1061,8 +1188,8 @@ class CIDR
 # - Returns:
 #   * Integer
 #
-# Example:
-#   packed = cidr4.packed_network().to_s(16)   --> 0xc0c80100
+# Examples:
+#   packed = cidr4.packed_network().to_s(16)
 #
     def packed_network()
         return(@network)
@@ -1081,37 +1208,53 @@ class CIDR
 # between them (inclusive).
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * Array of (2) Integers, or a Hash with the following fields:
 #       - :Bitstep -- enumerate in X sized steps - Integer (optional)
 #       - :Indexes -- index numbers of the addresses to use as boundaries - Array of (2) Integers
 #       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * Array Strings or CIDR objects
+#   * Array IP address Strings or IPAdmin::CIDR objects
 #
-# Example:
-#   list = cidr4.range(:Indexes => [0,1]) --> ['192.168.1.0','192.168.1.1']
+# Examples:
+#   list = cidr4.range([0,1])
+#   list = cidr4.range(:Indexes => [0,1], :Objectify => true)
 #
     def range(options)
         objectify = false
         short = false
         bitstep = 1
 
-        if (!options.kind_of?(Hash))
-            raise Argumenterror, "Expected Hash, but #{options.class} provided."
-        end
+        if (options.kind_of?(Hash))
+            if ( !options.has_key?(:Indexes) )
+                raise ArgumentError, "Missing argument: Indexes."
+            end
+            indexes = options[:Indexes]
+            raise "Array expected but #{indexes.class} provided for argument: Indexes" if (!indexes.kind_of?(Array))
+            
+            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?(:Indexes) )
-            raise ArgumentError, "Missing argument: Indexes."
+            if( options.has_key?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+        elsif (options.kind_of?(Array))
+            indexes = options
+        else
+            raise Argumenterror, "Array or Hash expected, but #{options.class} provided."
         end
-        indexes = options[:Indexes]
-        indexes.sort!
         
-        if( (!indexes.kind_of?(Array)) || (indexes.length != 2))
-            raise ArgumentError, "Argument :Index should be an array of (2) index numbers."
+        # validate & sort indexes
+        indexes.sort!
+        if (indexes.length != 2)
+            raise "(2) index numbers are required."
         end
-
         if ( (indexes[0] < 0) || (indexes[0] > self.size) )
             raise ArgumentError, "Index #{indexes[0]} is out of bounds for this CIDR."
         end
@@ -1120,18 +1263,7 @@ class CIDR
             raise ArgumentError, "Index #{indexes[1]} is out of bounds for this CIDR."
         end
         
-        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
-
+        # make range
         start_ip = @network + indexes[0]
         end_ip = @network + indexes[1]
         my_ip = start_ip
@@ -1160,51 +1292,59 @@ class CIDR
 # remainder()
 #==============================================================================#
 
-# Given a portion of the current CIDR, provide the remainder of
-# the CIDR. For example if the original CIDR is 192.168.0.0/24 and you
+# 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 remainder.
+# and 192.168.0.128/25 will be returned as the remainders.
 #
 # - Arguments:
-#   * Optional hash with the following fields:
-#       - :Exclude -- CIDR object to use in calculating the remainder.
+#   * CIDR address or IPAdmin::CIDR object, or a Hash with the following fields:
+#       - :Exclude -- CIDR address or IPAdmin::CIDR object.
 #       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * Array of Strings or CIDR objects
+#   * Array of CIDR address Strings or IPAdmin::CIDR objects
 #
 #
-# Example:
-#   cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
-#   cidr4.remainder(:Exclude => cidr4_2).each {|x| puts}
+# Examples:
+#   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}
 #
     def remainder(options)
         short = nil
         objectify = nil
         
-        if (!options.kind_of? Hash)
-            raise ArgumentError, "Expected Hash, but #{options.class} provided."
-        end
-            
-        if ( !options.has_key?(:Exclude) )
-            raise ArgumentError, "Missing argument: Exclude."
-        end
-        to_exclude = options[:Exclude]
+        if (options.kind_of? Hash)
+            if ( !options.has_key?(:Exclude) )
+                raise ArgumentError, "Missing argument: Exclude."
+            end
+            to_exclude = options[:Exclude]
             
-        if ( !to_exclude.kind_of?(IPAdmin::CIDR) )
-            raise ArgumentError, "Expeced IPAdmin::CIDR, but #{exclude.class} " +
-                                 "for option: Exclude."
-        end
+            if( options.has_key?(:Short) && options[:Short] == true )
+                short = true
+            end
         
-        if( options.has_key?(:Short) && options[:Short] == true )
-            short = true
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
+                objectify = true
+            end
+        
+        elsif
+            to_exclude = options
+        else
+            raise ArgumentError, "CIDR address or Hash expected, but #{options.class} provided."
         end
         
-        if( options.has_key?(:Objectify) && options[:Objectify] == true )
-            objectify = true
+        if ( !to_exclude.kind_of?(IPAdmin::CIDR) )
+            begin
+                to_exclude = IPAdmin::CIDR.new(:CIDR => to_exclude)
+            rescue Exception => error
+                raise ArgumentError, "Argument :Exclude raised the following " +
+                                     "errors: #{error}"
+            end
         end
         
+        
         # make sure 'to_exclude' is the same ip version
         if ( to_exclude.version != @version )
             raise "#{to_exclude.desc(:Short => true)} is of a different " +
@@ -1266,26 +1406,29 @@ class CIDR
 # Return the resulting CIDR as a new object.
 #
 # - Arguments:
-#   * Hash with the following fields:
-#       - :Subnet -- Number of bits of new Netmask - Integer
+#   * Integer, or a Hash with the following fields:
+#       - :Netmask -- Number of bits of new Netmask - Integer
 #
 # - Returns:
-#   * CIDR object
+#   * IPAdmin::CIDR object
 #
-# Example:
-#   new_cidr = cidr4.resize(:Subnet => 23)
-#   puts new_cidr.desc   --> 192.168.1.0/23
+# Examples:
+#   new_cidr = cidr4.resize(23)
+#   new_cidr = cidr4.resize(:Netmask => 23)
+#   puts new_cidr.desc
 #
     def resize(options)
-        if (!options.kind_of?(Hash))
-                raise Argumenterror, "Expected Hash, but " +
+        if (options.kind_of?(Hash))
+            if ( !options.has_key?(:Netmask) )
+                raise Argumenterror, "Missing argument: Netmask."
+            end
+            bits = options[:Netmask]
+        elsif (options.kind_of?(Integer))
+            bits = options
+        else
+            raise Argumenterror, "Integer or Hash expected, but " +
                                      "#{options.class} provided."
         end
-            
-        if ( !options.has_key?(:Subnet) )
-                raise Argumenterror, "Missing argument: Subnet."
-        end
-        bits = options[:Subnet]
         
         IPAdmin.validate_ip_netmask(:Netmask => bits, :Version => @version)
         netmask = IPAdmin.pack_ip_netmask(:Netmask => bits, :Version => @version)
@@ -1307,30 +1450,32 @@ class CIDR
 # Resize this object by changing the size of the Netmask. 
 #
 # - Arguments:
-#   * Hash with the following fields:
-#       - :Subnet -- Number of bits of new Netmask - Integer
+#   * Integer, or a Hash with the following fields:
+#       - :Netmask -- Number of bits of new Netmask - Integer
 #
 # - Returns:
-#   * nil
+#   * True
 #
 # - Notes:
 #   * If CIDR is resized such that the original IP is no longer contained within,
 #     then that IP will be reset to the base network address.
 #
-# Example:
-#   cidr4.resize!(:Subnet => 23)
-#   puts cidr4.desc   --> 192.168.1.0/23
+# Examples:
+#   cidr4.resize!(23)
+#   puts cidr4.desc
 #
     def resize!(options)
-        if (!options.kind_of?(Hash))
-                raise Argumenterror, "Expected Hash, but " +
+        if (options.kind_of?(Hash))
+            if ( !options.has_key?(:Netmask) )
+                raise Argumenterror, "Missing argument: Netmask."
+            end
+            bits = options[:Netmask]
+        elsif (options.kind_of?(Integer))
+            bits = options
+        else
+            raise Argumenterror, "Integer or Hash expected, but " +
                                      "#{options.class} provided."
         end
-            
-        if ( !options.has_key?(:Subnet) )
-                raise Argumenterror, "Missing argument: Subnet."
-        end
-        bits = options[:Subnet]
         
         IPAdmin.validate_ip_netmask(:Netmask => bits, :Version => @version)
         netmask = IPAdmin.pack_ip_netmask(:Netmask => bits, :Version => @version)
@@ -1344,7 +1489,7 @@ class CIDR
             @ip = @network
         end
         
-        return(nil)
+        return(true)
     end
 
 #======================================#
@@ -1364,8 +1509,8 @@ class CIDR
 # - Returns:
 #   * Integer
 #
-# Example:
-#   puts cidr4.size()   --> 256
+# Examples:
+#   puts cidr4.size()
 #
     def size()
         return(@hostmask + 1)
@@ -1380,11 +1525,14 @@ class CIDR
 # subnet()
 #==============================================================================#
 
-# Subnet this object. Object will be fully subnetted into X number of subnets
-# of specified size. If :MinCount is provided, then method will return at least 
-# that number of subnets (of size X) and the remainder of the new subnets
-# will be merged together as tightly as possible. If a size is not provided,
-# then the current CIDR will be split in half.
+# Subnet this object. There are 2 ways to subnet:
+#   * By providing the netmask of the new subnets in :Subnet.
+#   * By providing the number of IP addresses needed in the new subnets in :IPCount
+#
+# If :Mincount is not provided, then the CIDR will be fully subnetted. Otherwise,
+# if provided then :Mincount number of subnets of requested size will be returned and
+# the remainder of the subnets will be summarized as much as possible. If neither :Subnet
+# or :IPCount is provided, then the current CIDR will be split in half.
 #
 # - Arguments:
 #   * Optional hash with the following fields:
@@ -1395,15 +1543,14 @@ class CIDR
 #       - :Subnet --  Netmask (in bits) of new subnets - Integer (optional)
 #
 # - Returns:
-#   * Array of CIDR addresses or IPAdmin::CIDR objects
+#   * Array of CIDR address Strings or IPAdmin::CIDR objects
 #
 # - Notes:
 #   * :Subnet always takes precedence over :IPCount.
 #
-# Example:
+# Examples:
 #   cidr_list = cidr4.subnet(:Subnet => 28, :MinCount => 3)
 #   cidr_list = cidr4.subnet(:IPCount => 19)
-#   puts cidr_list[0]   --> 192.168.1.0/27
 #
     def subnet(options=nil)
         my_network = self.packed_network
@@ -1516,6 +1663,61 @@ class CIDR
 #
 #======================================#
 
+
+# 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 IPAdmin::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(IPAdmin::CIDR.new(:PackedIP => base_addr,
+                                        :PackedNetmask => mask,
+                                        :Version => self.version))
+            ip_count -= bitstep
+            base_addr += bitstep
+        end
+        
+        return(list)
+    end
+
+#======================================#
+#
+#======================================#
+
+
 end
 
 end # module IPAdmin