ipadmin 0.3.0 → 0.4.0

data/lib/tree.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 Tree
 
@@ -14,11 +8,19 @@ class Tree
 # @version
 
 #==============================================================================#
-# attr_reader / attr_writer
+# initialize()
 #==============================================================================#
 
-    # IP version for this tree (4 or 6)
-    attr_reader :version
+# - Arguments:
+#   * none
+#
+# Examples:
+#   tree = IPAdmin::Tree.new()
+#
+    def initialize(options=nil)
+        # root of our ordered IP tree
+        @root = NetStruct.new(nil, nil, [])
+    end
 
 #======================================#
 #
@@ -26,42 +28,68 @@ class Tree
 
 
 #==============================================================================#
-# initialize()
+# add!()
 #==============================================================================#
 
+# Add a CIDR address or IPAdmin::CIDR object to the tree.
+#
 # - Arguments:
-#   * Hash with the following fields:
-#       - :Version -- IP version - Integer
+#   * CIDR address or IPAdmin::CIDR object
 #
-# Example:
-#   table = IPAdmin::CIDRTable.new(:Version => 4)
+# - Returns:
+#   * nothing
 #
-    def initialize(options)
-        if (!options.kind_of? Hash)
-            raise ArgumentError, "Expected Hash, but #{options.class} provided."
-        end
-
-        if ( options.has_key?(:Version) )
-            @version =  options[:Version]
+# Examples:
+#   tree.add!('192.168.1.0/24')
+#
+    def add!(new)
+        duplicate = false
 
-            if ( @version != 4 && @version != 6 )
-                raise "IP version should be either 4 or 6."
+        # validate object
+        if ( !new.kind_of?(IPAdmin::CIDR) )
+            begin
+                cidr = IPAdmin::CIDR.new(:CIDR => new)
+            rescue Exception => error
+                raise ArgumentError, "Provided argument raised the following " +
+                                     "errors: #{error}"
             end
         else
-            raise ArgumentError, "Missing argument: Version."
+            cidr = IPAdmin::CIDR.new(:PackedIP => new.packed_ip,
+                                     :PackedNetmask => new.packed_netmask,
+                                     :Version => new.version,
+                                     :Tag => new.tag)
+        end
+
+        version = cidr.version
+        new_entry = NetStruct.new(cidr, nil, [])
+
+        # find cidr's parent
+        new_entry.parent = find_parent(cidr, @root)
+
+        # check parent for subnets of cidr
+        new_entry.parent.children.each do |old_entry|
+            if (old_entry.cidr.version == version)
+                comp = IPAdmin.compare(cidr,old_entry.cidr)
+                if (comp && comp[0] == cidr)
+                    old_entry.parent = new_entry
+                    new_entry.children.push(old_entry)
+                elsif (comp && comp == 1)
+                    duplicate = true
+                    break
+                end
+            end
         end
 
-        if (@version == 4)
-            @max_bits = 32
-            @all_f = 2**@max_bits - 1
-        else
-            @max_bits = 128
-            @all_f = 2**@max_bits - 1
-        end
+        if (!duplicate)
+            new_entry.children.each do |old_entry|
+                new_entry.parent.children.delete(old_entry)
+            end
 
-        # root of our ordered IP tree
-        @root = []
+            # add new object as an ordered entry to parent.children
+            add_to_parent(new_entry,new_entry.parent)
+        end
 
+        return()
     end
 
 #======================================#
@@ -70,68 +98,118 @@ class Tree
 
 
 #==============================================================================#
-# add()
+# ancestors()
 #==============================================================================#
 
-# Add an IPAdmin::CIDR object to the tree.
+# Returns all the ancestors of the provided CIDR addresses.
 #
 # - Arguments:
-#   * CIDR object
+#   * CIDR address or IPAdmin::CIDR object
 #
 # - Returns:
-#   * nothing
+#   * Array of IPAdmin::CIDR objects
 #
-# Example:
-#   tree.add(cidr)
+# Examples:
+#   puts tree.ancestors('192.168.1.0/27')
 #
-    def add(object)
-
+    def ancestors(cidr)
         # validate object
-        if ( !object.kind_of?(IPAdmin::CIDR) )
-            raise ArgumentError, "IPAdmin::CIDR object " +
-                                 "required 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
-
-        if ( object.version != @version )
-            raise "IP version #{object.version} is incompatible with " +
-                  "Tree IP version #{@version}."
+        
+        list = []
+        parent = find_parent(cidr,@root)
+        
+        until (parent == @root)
+            list.push(parent.cidr)
+            parent = parent.parent
         end
 
-        net_struct = IPAdmin.create_net_struct(object)
+        return(list)
+    end
 
-        # search tree for it's home branch
-        search_results = find_home(net_struct, @root)
-        home_struct = search_results[0] if (search_results)
-        home_branch = home_struct.subnets if (search_results)
-        home_branch = @root if (!home_branch)
+#======================================#
+#
+#======================================#
 
-        # make sure we dont have a duplicate
-        if (home_struct)
-            if ( (net_struct.network == home_struct.network) && 
-                 (net_struct.netmask == home_struct.netmask) )
-                raise "Attempted to add #{object.desc()} multiple times."
-            end
-        end
 
-        # now that we have our branch location, check that other entries
-        # of this branch are not subnets of our new object. if they are
-        # then make them a branch of our new object
-        home_branch.each do |entry|
-            is_contained = contains(net_struct, entry)
+#==============================================================================#
+# children()
+#==============================================================================#
 
-            if (is_contained)
-                net_struct.subnets.push(entry)
+# Returns all the immediate children of the provided CIDR addresses.
+#
+# - Arguments:
+#   * CIDR address or IPAdmin::CIDR object
+#
+# - Returns:
+#   * Array of IPAdmin::CIDR objects
+#
+# Examples:
+#   puts tree.children('192.168.1.0/24')
+#
+    def children(cidr)
+        # validate object
+        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
 
-        net_struct.subnets.each do |entry|
-            home_branch.delete(entry)
+        list = []
+        find_me(cidr).children.each do |child|
+            list.push(child.cidr)
+        end
+
+        return(list)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# descendants
+#==============================================================================#
+
+# Return all descendants of the provided CIDR address.
+#
+# - Arguments:
+#   * CIDR address or IPAdmin::CIDR object
+#
+# - Returns:
+#   * Array of IPAdmin::CIDR objects
+#
+# Examples:
+#   descendants = tree.descendants('192.168.1.0/24')
+#
+    def descendants(cidr)
+        list = []
+        
+        # validate object
+        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
 
-        # add new object as an ordered entry to home_branch
-        add_to_branch(net_struct,home_branch)
+        me = find_me(cidr)        
+        dump_children(me).each {|x| list.push(x[:NetStruct].cidr)} if (me)
 
-        return(nil)
+        return(list)
     end
 
 #======================================#
@@ -140,39 +218,46 @@ class Tree
 
 
 #==============================================================================#
-# collapse()
+# delete!()
 #==============================================================================#
 
-# Collapse (supernet) all subnets of the tree,
-# and return a new tree. The supernetting of subnets will only occur in
-# situations where the newly created supernet will not result in the
-# 'creation' of additional space. For example the following blocks
-# (192.168.0.0/24, 192.168.1.0/24, and 192.168.2.0/24) would merge into
-# 192.168.0.0/23 and 192.168.2.0/24 rather than into 192.168.0.0/22.
+# Remove the provided CIDR address from the tree.
 #
 # - Arguments:
-#   * none
+#   * CIDR address of IPAdmin::CIDR object
 #
 # - Returns:
-#   * Tree object
-#
-# Example:
-#   new_tree = tree.collapse()
-#
-    def collapse()
-            tree = IPAdmin::Tree.new(:Version => @version)
-            branch = IPAdmin.merge(:List => @root, :NetStruct => 1)
-            dumped = dump_branch(branch)
-            dumped.each do |entry|
-                net_struct = entry[:NetStruct]
-                network = IPAdmin.unpack_ip_addr(:Integer => net_struct.network,
-                                                 :Version => @version)
-                netmask = IPAdmin.unpack_ip_netmask(:Integer => net_struct.netmask,
-                                                    :Version => @version)
-                cidr = IPAdmin::CIDR.new(:CIDR => "#{network}/#{netmask}")
-                tree.add(cidr)
+#   * true on success or false on fail
+#
+# Examples:
+#   did_remove = tree.remove!('192.168.1.0/24')
+#
+    def delete!(cidr)
+        removed = false
+        
+        # validate object
+        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
-        return(tree)
+        end
+
+        # find matching
+        me = find_me(cidr)
+        
+        # remove
+        if (me)
+            parent = me.parent
+            children = me.children 
+            parent.children.delete(me)
+            children.each {|x| add_to_parent(x,parent)}
+            removed = true
+        end
+
+        return(removed)
     end
 
 #======================================#
@@ -191,20 +276,19 @@ class Tree
 #
 # - Returns:
 #   * ordered array of hashes with the following fields: 
-#       - :Object => CIDR object
+#       - :CIDR => IPAdmin::CIDR object
 #       - :Depth => (depth level in tree)
-# Example:
+# Examples:
 #   dumped = tree.dump()
 #
     def dump()
         list = []
-        dumped = dump_branch(@root)
+        dumped = dump_children(@root)
 
         dumped.each do |entry|
             depth = entry[:Depth]
             net_struct = entry[:NetStruct]
-            object = net_struct.object
-            list.push({:Depth => depth, :Object => object})
+            list.push({:Depth => depth, :CIDR => net_struct.cidr})
         end
 
         return(list)
@@ -219,43 +303,31 @@ class Tree
 # exists?()
 #==============================================================================#
 
-# Has an IPAdmin::CIDR object already been added to the tree?
+# Has a CIDR address already been added to the tree?
 #
 # - Arguments:
-#   * CIDR object
+#   * CIDR address or IPAdmin::CIDR object
 #
 # - Returns:
 #   * true or false
 #
-# Example:
-#   added = tree.exists?(cidr)
+# Examples:
+#   added = tree.exists?('192.168.1.0/24')
 #
-    def exists?(object)
+    def exists?(cidr)
+        found = false
 
         # validate object
-        if ( !object.kind_of?(IPAdmin::CIDR) )
-            raise ArgumentError, "IPAdmin::CIDR object " +
-                                 "required but #{object.class} provided."
-        end
-
-        if ( !object.version == @version )
-            raise "IP version #{object.version} is incompatible with " +
-                  "Tree IP version #{@version}."
-        end
-
-        net_struct = IPAdmin.create_net_struct(object)
-        home_struct,home_branch = find_home(net_struct, @root)
-
-        # check for match
-        found = false
-        if (home_struct)  
-            if ( (net_struct.network == home_struct.network) && 
-                 (net_struct.netmask == home_struct.netmask) )
-                found = true
+        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
 
-
+        found = true if (find_me(cidr))
         return(found)
     end
 
@@ -265,37 +337,76 @@ class Tree
 
 
 #==============================================================================#
-# find()
+# fill_in!()
 #==============================================================================#
 
-# Find the longest matching branch of our tree to which an 
-# IPAdmin::CIDR object belongs. Useful for performing 'routing table' lookups.
+# Fill in the missing subnets of a particular CIDR.
 #
 # - Arguments:
-#   * CIDR object
+#   * CIDR address or IPAdmin::CIDR object
 #
 # - Returns:
-#   * CIDR object, or nil
+#   * true or false
 #
-# Example:
-#   longest_match = tree.find(ip)
+# Examples:
+#   success = tree.fill_in!('192.168.1.0/24')
 #
-    def find(object)
-        if ( !object.kind_of?(IPAdmin::CIDR) )
-            raise ArgumentError, "IPAdmin::CIDR object " +
-                                 "required but #{object.class} provided."
+    def fill_in!(cidr)
+        filled = false
+
+        # validate object
+        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
 
-        if ( object.version != @version )
-            raise "IP version #{object.version} is incompatible with " +
-                  "Tree IP version #{@version}."
+        me = find_me(cidr)        
+        if (me && me.children.length != 0)
+            list = []
+            me.children.each {|x| list.push(x.cidr)}
+            me.cidr.fill_in(:List => list, :Objectify => true).each do |cidr|
+                self.add!(cidr)
+            end
+            filled = true
         end
+        return(filled)
+    end
 
-        net_struct = IPAdmin.create_net_struct(object)
-        home_struct,home_branch = find_home(net_struct, @root)
-        found_obj = home_struct.object if (home_struct)
+#======================================#
+#
+#======================================#
 
-        return(found_obj)
+
+#==============================================================================#
+# find()
+#==============================================================================#
+
+# Find and return a CIDR from within the tree.
+#
+# - Arguments:
+#   * CIDR address or IPAdmin::CIDR object
+#
+# - Returns:
+#   * IPAdmin::CIDR object, or nil
+#
+# Examples:
+#   cidr = tree.find('192.168.1.0/24')
+#
+    def find(cidr)
+        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
+
+        return(find_me(cidr).cidr)
     end
 
 #======================================#
@@ -307,86 +418,110 @@ class Tree
 # find_space()
 #==============================================================================#
 
-# Find Tree entries that can hold a subnet of size X. Returns only the smallest
-# matching subnets of each supernet. If neither IPCount or Subnet or provided,
-# then method returns all entries that can fit a single IP.
+# Find subnets that are of at least size X. Only subnets that are not themselves 
+# subnetted will be returned.
 #
 # - Arguments:
-#   * Hash with the following fields:
-#       - :IPCount -- Minimum number of IP's that should fit within subnet - Integer (optional)
-#       - :Limit -- Maximum entries to return - Integer (optional)
-#       - :Subnet -- Netmask (in bits) of space to find - Integer (optional)
+#   * Minimum subnet size in bits, or a Hash with the following fields:
+#       - :Subnet - minimum subnet size in bits for returned subnets
+#       - :IPCount - minimum IP count per subnet required for returned subnets
+#       - :Version - restrict results to IPvX
 #
 # - Returns:
-#   * Array of CIDR objects
+#   * Array of IPAdmin::CIDR objects
 #
 # - Notes:
-#    * :Subnet always takes precedence over :IPCount.
+#   * :Subnet takes precedence over :IPCount
 #
-# Example:
-#   list = tree.find_space(:Subnet => 27)
-#   list = tree.find_space(:IPCount => 33, :Limit => 2)
+# Examples:
+#   subnets = tree.find_space(:IPCount => 16)
 #
     def find_space(options)
-        limit = nil
-        list = []
-
-        # validate options
-        if (!options.kind_of? Hash)
-            raise ArgumentError, "Expected Hash, but #{options.class} provided."
-        end
+        version = nil
+        if (options.kind_of? Integer)
+            bits4 = options
+            bits6 = options
+        elsif (options.kind_of? Hash) 
+            if (options.has_key?(:Version))
+                version = options[:Version]
+                raise "IP version should be 4 or 6, but was #{version}." if (version != 4 && version !=6)
+            end
 
-        if ( options.has_key?(:Limit) )
-            limit = options[:Limit]
-        end
-        
-        if ( options.has_key?(:IPCount) )
-            subnet_size = IPAdmin.minimum_size(:IPCount =>options[:IPCount],
-                                               :Version => @version)
-        end
-        
-        if ( options.has_key?(:Subnet) )
-            subnet_size = options[:Subnet]
+            if (options.has_key?(:Subnet))
+                bits4 = options[:Subnet]
+                bits6 = options[:Subnet]
+            elsif(options.has_key?(:IPCount))
+                bits4 = IPAdmin.minimum_size(:IPCount => options[:IPCount], :Version => 4)
+                bits6 = IPAdmin.minimum_size(:IPCount => options[:IPCount], :Version => 6)
+            else
+                raise "Missing arguments: :Subnet/:IPCount"
+            end
+        else
+            raise "Integer or Hash expected, but #{options.class} provided."
         end
 
-        # set subnet_size if not already
-        if (!subnet_size)
-            if (@version == 4)
-                subnet_size = 32
+        list4 = []
+        list6 = []
+        dump_children(@root).each do |entry|
+            netstruct = entry[:NetStruct]
+            if (netstruct.cidr.version == 4)
+                if ( (netstruct.children.length == 0) && (netstruct.cidr.bits <= bits4) )
+                    list4.push(netstruct.cidr)
+                end
             else
-                subnet_size = 128
+                if ( (netstruct.children.length == 0) && (netstruct.cidr.bits <= bits6) )
+                    list6.push(netstruct.cidr)
+                end
             end
         end
         
-        # check that subnet_size is a valid size
-        if ( (subnet_size < 1) || (subnet_size > @max_bits) )
-                raise "#{subnet_size} is out of range for an " +
-                      "IP version #{@version} Tree."
+        list = []
+        if (!version)
+            list.concat(list4)
+            list.concat(list6)
+        else
+            list.concat(list4) if (version == 4)
+            list.concat(list6) if (version == 6)
         end
 
-        # search
-        search_list = dump_branch(@root)
-        search_list.each do |entry|
-            depth = entry[:Depth]
-            net_struct = entry[:NetStruct]
+        return(list)
+    end
 
-            # we only want leaf nodes of type IPAdmin::CIDR
-            if ( (net_struct.subnets.length == 0) &&
-                 (net_struct.object.kind_of?(IPAdmin::CIDR)) )
+#======================================#
+#
+#======================================#
 
-                 if (subnet_size >= net_struct.object.bits)
-                    list.push(net_struct.object)
-                 end
-            end
 
-            if (limit && (list.length >= limit) )
-                break
-            end
+#==============================================================================#
+# longest_match()
+#==============================================================================#
 
+# Find the longest matching branch of our tree to which a 
+# CIDR address belongs. Useful for performing 'routing table' style lookups.
+#
+# - Arguments:
+#   * CIDR address or IPAdmin::CIDR object
+#
+# - Returns:
+#   * IPAdmin::CIDR object, or nil
+#
+# Examples:
+#   longest_match = tree.longest_match('192.168.1.1')
+#
+    def longest_match(cidr)
+        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
+        
+        found = find_me(cidr)
+        found = find_parent(cidr, @root) if !found
 
-        return(list)
-
+        return(found.cidr)
     end
 
 #======================================#
@@ -395,43 +530,84 @@ class Tree
 
 
 #==============================================================================#
-# prune()
+# merge_subnets!()
 #==============================================================================#
 
-# Remove an IPAdmin::CIDR object, and all child
-# objects from the tree.
+# Merge (summarize) all subnets of the provided CIDR address.
 #
 # - Arguments:
-#   * CIDR object
+#   * CIDR address or IPAdmin::CIDR object
 #
 # - Returns:
-#   * true or false
+#   * true on success or false on fail
 #
-# Example:
-#   did_prune = tree.prune(ip)
+# Examples:
+#   tree.merge_subnets!('192.168.1.0/24')
 #
-    def prune(object)
-        if ( !object.kind_of?(IPAdmin::CIDR) )
-            raise ArgumentError, "IPAdmin::CIDR object " +
-                                 "required but #{object.class} provided."
+    def merge_subnets!(cidr)
+        merged = false
+        
+        # validate object
+        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
 
-        if (object.version != @version )
-            raise "IP version #{object.version} is incompatible with " +
-                  "Tree IP version #{@version}."
+        me = find_me(cidr)
+        
+        if (me)
+            to_merge = []
+            me.children.each {|x| to_merge.push(x.cidr)}
+            to_merge.each {|x| delete!(x)}
+
+            IPAdmin.merge(to_merge).each {|x| add!(x)}            
+            merged = true
         end
 
-        net_struct = IPAdmin.create_net_struct(object)
-        home_struct,home_branch = find_home(net_struct, @root)
+        return(merged)
+    end
 
-        if(!home_struct)
-            raise "#{object.desc} could not be found."
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# prune!()
+#==============================================================================#
+
+# Remove all subnets of the provided CIDR address.
+#
+# - Arguments:
+#   * CIDR address or IPAdmin::CIDR object
+#
+# - Returns:
+#   * true on success or false on fail
+#
+# Examples:
+#   did_prune = tree.prune!('192.168.1.0/24')
+#
+    def prune!(cidr)
+        pruned = false
+        
+        # validate object
+        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
+
+        me = find_me(cidr)
         
-        # remove if home_struct.object = object
-        pruned = false
-        if (home_struct.object = object)
-            home_branch.delete(home_struct)
+        if (me)
+            me.children.clear
             pruned = true
         end
 
@@ -444,57 +620,131 @@ class Tree
 
 
 #==============================================================================#
-# remove()
+# remove!()
 #==============================================================================#
 
-# Remove a single CIDR object from the tree.
+# Remove the provided CIDR address, and all of its subnets from the tree.
 #
 # - Arguments:
-#   * CIDR object
+#   * CIDR address of IPAdmin::CIDR object
 #
 # - Returns:
-#   * true or false
+#   * true on success or false on fail
 #
-# Example:
-#   did_remove = tree.remove(ip)
+# Examples:
+#   did_remove = tree.remove!('192.168.1.0/24')
 #
-    def remove(object)
-        if ( !object.kind_of?(IPAdmin::CIDR) )
-            raise ArgumentError, "IPAdmin::CIDR object " +
-                                 "required but #{object.class} provided."
+    def remove!(cidr)
+        removed = false
+        found = nil
+        
+        # validate object
+        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
 
-        if (object.version != @version )
-            raise "IP version #{object.version} is incompatible with " +
-                  "Tree IP version #{@version}."
+        me = find_me(cidr)
+        
+        if (me)
+            parent = me.parent
+            parent.children.delete(me)
+            removed = true
         end
+        
+        return(removed)
+    end
 
-        net_struct = IPAdmin.create_net_struct(object)
-        home_struct,home_branch = find_home(net_struct, @root)
+#======================================#
+#
+#======================================#
 
-        # remove if home_struct.object = object
-        removed = false
-        if (home_struct.object = object)
-
-            # if we have children subnets, move them up one level
-            if (home_struct.subnets.length > 0)
-                home_struct.subnets.each do |entry|
-                    index = 0
-                    home_branch.each do
-                        if(entry.network < (home_branch[index]).network)
-                            break
-                        end
-                        index += 1
-                    end
-                    home_branch.insert(index, entry)
-                end
+
+#==============================================================================#
+# resize!()
+#==============================================================================#
+
+# Resize the provided CIDR address.
+#
+# - Arguments:
+#   * CIDR address or IPAdmin::CIDR object
+#   * Integer representing the bits of the new netmask
+#
+# - Returns:
+#   * true on success or false on fail
+#
+# Examples:
+#   resized = tree.resize!('192.168.1.0/24', 23)
+#
+    def resize!(cidr,bits)
+        resized = false
+        
+        # validate cidr
+        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
 
-            home_branch.delete(home_struct)
-            removed = true
+        me = find_me(cidr)
+        
+        if (me)
+            new = me.cidr.resize(bits)
+            delete!(me.cidr)
+            add!(new)
+            resized = true
         end
+        
+        return(resized)
+    end
 
-        return(removed)
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# root()
+#==============================================================================#
+
+# Returns the root of the provided CIDR address.
+#
+# - Arguments:
+#   * CIDR address or IPAdmin::CIDR object
+#
+# - Returns:
+#   * IPAdmin::CIDR object
+#
+# Examples:
+#   puts tree.root('192.168.1.32/27')
+#
+    def root(cidr)
+        # validate object
+        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
+        
+        parent = find_parent(cidr,@root)
+        
+        if (parent && parent != @root)
+            until (parent.parent == @root)
+                parent = parent.parent
+            end
+        end
+
+        return(parent.cidr)
     end
 
 #======================================#
@@ -514,21 +764,16 @@ class Tree
 # - Returns:
 #   * String representing the contents of the tree
 #
-# Example:
+# Examples:
 #   puts tree.show()
 #
     def show()
         printed = ""
-        list = dump_branch(@root)
+        list = dump_children(@root)
 
         list.each do |entry|
-            net_struct = entry[:NetStruct]
+            cidr = entry[:NetStruct].cidr
             depth = entry[:Depth]
-            network = IPAdmin.unpack_ip_addr(:Integer => net_struct.network,
-                                             :Version => @version)
-            netmask = IPAdmin.unpack_ip_netmask(:Integer => net_struct.netmask,
-                                                :Version => @version)
-            network = IPAdmin.shorten(network) if (@version == 6)
 
             if (depth == 0)
                 indent = ""
@@ -536,7 +781,7 @@ class Tree
                 indent = " " * (depth*3)
             end
 
-            printed << "#{indent}#{network}/#{netmask}\n"
+            printed << "#{indent}#{cidr.desc(:Short => true)}\n"
         end
 
         return(printed)
@@ -547,45 +792,40 @@ class Tree
 #======================================#
 
 
-
-
-# PRIVATE METHODS
-private
-
 #==============================================================================#
-# add_to_branch() private
+# siblings()
 #==============================================================================#
 
-# Add Netstruct object to an array of NetStruct's
+# Return list of the sibling CIDRs of the provided CIDR address.
 #
 # - Arguments:
-#   * NetStruct, and array of NetStruct's in which to add it
+#   * CIDR address or IPAdmin::CIDR object
 #
 # - Returns:
-#   * none
+#   * Array of IPAdmin::CIDR objects
 #
-# Example:
-#   add_to_branch(net_struct,branch)
+# Examples:
+#   puts tree.siblings('192.168.1.0/27')
 #
-    def add_to_branch(net_struct,branch)
-        # make sure we have appropriate types 
-        if (!net_struct.kind_of?(IPAdmin::NetStruct) || 
-            !branch.kind_of?(Array) )
-            raise ArgumentError, "Incorrect argument types " +
-                                 "#{net_struct.class} and #{branch}."
+    def siblings(cidr)
+        # validate object
+        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
         
-        index = 0
-        branch.each do
-            if(net_struct.network < (branch[index]).network)
-                break
+        list = []
+        find_parent(cidr,@root).children.each do |entry|
+            if (!IPAdmin.compare(cidr,entry.cidr))
+                list.push(entry.cidr)
             end
-            index += 1
         end
 
-        branch.insert(index, net_struct)
-
-        return()
+        return(list)
     end
 
 #======================================#
@@ -594,50 +834,54 @@ private
 
 
 #==============================================================================#
-# contains() private
+# supernets()
 #==============================================================================#
 
-# Is the first NetStruct object the supernet of the second?
+# Return list of the top-level supernets of this tree.
 #
 # - Arguments:
-#   * Two NetStruct objects
+#   * none
 #
 # - Returns:
-#   * true if struct1 contains or is equal to struct2, or false if not.
+#   * Array of IPAdmin::CIDR objects
 #
-# Example:
-#   is_contained = contains(struct1,struct2)
+# Examples:
+#   supernets = tree.supernets()
 #
-    def contains(struct1,struct2)
+    def supernets()
+       supernets = []
+       @root.children.each {|x| supernets.push(x.cidr)}
+       return (supernets)
+    end
 
-        # make sure we have appropriate types 
-        if (!struct1.kind_of?(IPAdmin::NetStruct) || 
-            !struct2.kind_of?(IPAdmin::NetStruct) )
-            raise ArgumentError, "Incorrect argument types " +
-                                 "#{struct1.class} and #{struct2.class}."
-        end
+#======================================#
+#
+#======================================#
 
-        network1 = struct1.network
-        netmask1 = struct1.netmask
-        network2 = struct2.network
-        netmask2 = struct2.netmask
-        hostmask1 = netmask1 ^ @all_f
 
-        # if network1 == network2, then we have to go by netmask length
-        # else we can tell by or'ing network1 and network2 by hostmask1
-        # and comparing the results
-        is_contained = false
-        if (network1 == network2)
-            if (netmask2 >= netmask1)
-                is_contained = true
-            end
-        else
-            if ( (network1 | hostmask1) == (network2 | hostmask1) )
-                is_contained = true
+
+
+# PRIVATE INSTANCE METHODS
+private
+
+#==============================================================================#
+# add_to_parent() private
+#==============================================================================#
+
+# Add NetStruct object to an array of NetStruct's
+#
+    def add_to_parent(new_entry, parent)       
+        index = 0
+        parent.children.each do
+            if(new_entry.cidr.packed_network < parent.children[index].cidr.packed_network)
+                break
             end
+            index += 1
         end
 
-        return(is_contained)
+        parent.children.insert(index, new_entry)
+
+        return()
     end
 
 #======================================#
@@ -646,32 +890,21 @@ private
 
 
 #==============================================================================#
-# dump_branch() private
+# dump_children() private
 #==============================================================================#
 
 #  Dump contents of an Array of NetStruct objects
 #
-# - Arguments:
-#   * array of NetStruct objects, and an optional depth within the tree
-#
-# - Returns:
-#   * array of hashes in form: :NetStruct => IPAdmin::NetStruct object
-#                              :Depth => (depth level in tree)
-# Example: 
-#   dumped = dump_branch(branch)
-#
-    def dump_branch(branch,depth=nil)
+    def dump_children(parent,depth=nil)
         list = []
         depth = 0 if (!depth)
 
-        branch.each do |entry|
-            subnets = entry.subnets
+        parent.children.each do |entry|
             list.push({:NetStruct => entry, :Depth => depth})
 
-            if (subnets.length > 0)
-                list.concat( dump_branch(subnets, (depth+1) ) )
+            if (entry.children.length > 0)
+                list.concat( dump_children(entry, (depth+1) ) )
             end
-
         end
 
         return(list)
@@ -683,46 +916,55 @@ private
 
 
 #==============================================================================#
-# find_home() private
+# find_me() private
 #==============================================================================#
 
-# Find the branch to which a NetStruct object belongs.
-#
-# - Arguments:
-#   * IPAdmin::NetStruct to find, and Array of
-#     IPAdmin::NetStruct's to search
-#
-# - Returns:
-#   * array of: container IPAdmin::NetStruct object,
-#               and container branch, or nil
+# Find the NetStruct to which a cidr belongs.
 #
-# Example:
-#   branch = find_home(net_struct,branch)
+    def find_me(cidr)
+        me = nil
+        
+        # find matching
+        parent = find_parent(cidr,@root)
+        parent.children.each do |entry|
+            if (entry.cidr.version == cidr.version)
+                if (IPAdmin.compare(entry.cidr,cidr) == 1)
+                    me = entry
+                    break
+                end
+            end
+        end
+
+        return(me)
+    end
+
+#======================================#
 #
-    def find_home(net_struct,branch)
-        ret_val = nil
+#======================================#
 
-        branch.each do |entry|
-            is_contained = contains(entry,net_struct)
 
-            if (is_contained)
-                home_struct = entry
-                home_branch = branch
+#==============================================================================#
+# find_parent() private
+#==============================================================================#
 
-                if (home_struct.subnets.length > 0)
-                    search_results = find_home(net_struct,home_struct.subnets)
-                    if (search_results)
-                        home_struct = search_results[0] 
-                        home_branch = search_results[1]
-                    end
-                end
+# Find the parent NetStruct to which a child NetStruct belongs.
+#
+    def find_parent(cidr,parent)
+        version = cidr.version
 
-                ret_val = [home_struct,home_branch]
+        parent.children.each do |entry|
+            if (entry.cidr.version == version && entry.cidr.contains?(cidr))
+                parent = entry
+
+                if (parent.children.length > 0)
+                    search_results = find_parent(cidr,parent)
+                    parent = search_results if (search_results)
+                end
                 break
             end
         end
 
-        return(ret_val)
+        return(parent)
     end
 
 #======================================#