ipadmin 0.1.2 → 0.1.3

data/README

@@ -24,6 +24,7 @@
  # IPAdmin::IPAddr
  #============================================================================#
  puts "IPAdmin::IPAddr"
+ print "\n"
 
  # new
  ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1/24')
@@ -33,34 +34,50 @@
  ip6 = IPAdmin::IPAddr.new(:IPAddr => 'fec0::1/64')
 
  # reader/writer
- puts ip4.tag['test']
+ puts "TEST 1"
+ puts "ip4 tag '#{ip4.tag['test']}'"
  ip4.tag['test'] = 'modified ip4 tag'
- puts ip4.tag['test']
+ puts "updated ip4 tag '#{ip4.tag['test']}'"
+ puts "ip4 version #{ip4.version}"
+ print "\n"
 
  # base
+ puts "TEST 2"
  puts "ip4 base addr #{ip4.base()}"
  puts "ip6 base addr #{ip6.base()}"
+ print "\n"
 
  # broadcast
+ puts "TEST 3"
  puts "ip4 bcast addr #{ip4.broadcast()}"
+ print "\n"
 
  # desc
+ puts "TEST 4"
  puts "ip4 description #{ip4.desc()}"
  puts "ip6 description #{ip6.desc()}"
+ print "\n"
 
  # extended masks
+ puts "TEST 5"
  puts "ip4 extended hostmask #{ip4.hostmask_ext()}"
- puts "ip6 extended netmask #{ip4.netmask_ext()}"
+ puts "ip4 extended netmask #{ip4.netmask_ext()}"
+ print "\n"
 
  # ip
+ puts "TEST 6"
  puts "ip4 ip addr #{ip4.ip()}"
  puts "ip6 ip addr #{ip6.ip()}"
+ print "\n"
 
  # netmask
+ puts "TEST 7"
  puts "ip4 netmask in CIDR format #{ip4.netmask()}"
  puts "ip6 netmask in CIDR format #{ip6.netmask()}"
+ print "\n"
  
  # bits
+ puts "TEST 8"
  puts "ip4 netmask in bits #{ip4.bits()}"
  puts "ip6 netmask in bits #{ip6.bits()}"
 
@@ -73,6 +90,10 @@
  # IPAdmin::CIDR
  #============================================================================#
  puts "IPAdmin::CIDR"
+ print "\n"
+ 
+ ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1/24')
+ ip6 = IPAdmin::IPAddr.new(:IPAddr => 'fec0::1/64')
 
  # new
  cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
@@ -81,44 +102,64 @@
                            :Tag => {'test' => 'cidr4 tag'})
  cidr6 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
 
- # attr reader/writer
- puts cidr4.tag['test']
+ # reader/writer
+ puts "TEST 1"
+ puts "cidr4 tag '#{cidr4.tag['test']}'"
  cidr4.tag['test'] = 'modified cidr4 tag'
- puts cidr4.tag['test']
+ puts "updated cidr4 tag '#{cidr4.tag['test']}'"
+ puts "cidr4 version #{cidr4.version}"
+ print "\n"
 
  # contains
+ puts "TEST 2"
  puts "#{cidr4.desc} contains #{ip4.desc}" if ( cidr4.contains(ip4) )
  puts "#{cidr6.desc} contains #{ip6.desc}" if ( cidr6.contains(ip6) )
+ print "\n"
 
  # desc
+ puts "TEST 3"
  puts "cidr4 description #{cidr4.desc()}"
  puts "cidr6 description #{cidr6.desc()}"
+ print "\n"
 
  # extended masks
+ puts "TEST 4"
  puts "cidr4 extended hostmask #{cidr4.hostmask_ext()}"
  puts "cidr4 extended netmask #{cidr4.netmask_ext()}"
+ print "\n"
 
  # netmask
+ puts "TEST 5"
  puts "cidr4 netmask in CIDR format #{cidr4.netmask()}"
  puts "cidr6 netmask in CIDR format #{cidr6.netmask()}"
+ print "\n"
  
  # bits
+ puts "TEST 6"
  puts "cidr4 netmask in bits #{cidr4.bits()}"
  puts "cidr6 netmask in bits #{cidr6.bits()}"
+ print "\n"
 
  # network
+ puts "TEST 7"
  puts "cidr4 network address #{cidr4.network()}"
  puts "cidr6 network address #{cidr6.network()}"
+ print "\n"
 
  # nth
+ puts "TEST 8"
  puts "cidr4 1st ip is #{cidr4.nth(:Index => 1)}"
  puts "cidr6 1st ip is #{(cidr6.nth(:Index => 1, :Objectify => 1)).desc}"
+ print "\n"
 
  # size
+ puts "TEST 9"
  puts "cidr4 size is #{cidr4.size()}"
  puts "cidr6 size is #{cidr6.size()}"
+ print "\n"
 
  # enumerate
+ puts "TEST 10"
  puts "first 4 cidr4 addresses (bitstep 32)"
  list4 = cidr4.enumerate(:Limit => 4, :Bitstep => 32)
  list4.each do |addr|
@@ -130,8 +171,10 @@
  list6.each do |addr|
      puts "  #{addr.desc}"
  end
+ print "\n"
  
  # subnet
+ puts "TEST 11"
  puts "cidr4 subnetted into at least 3 /28 ranges"
  sn4 = cidr4.subnet(:Subnet => 28, :MinCount => 3)
  sn4.each do |cidr|
@@ -149,76 +192,131 @@
  #
  #=====================================#
 
+
  #============================================================================#
- # IPAdmin::CIDRTable
+ # IPAdmin::Tree
  #============================================================================#
- puts "IPAdmin::CIDRTable"
+ puts "IPAdmin::Tree"
+ print "\n"
 
  cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
- cidr4_2 = IPAdmin::CIDR.new(:CIDR => '10.1.0.0/24')
- cidr4_3 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/26')
- cidr4_4 =IPAdmin::CIDR.new(:CIDR => '192.168.1.0/30')
- cidr4_5 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
- cidr4_6 = IPAdmin::CIDR.new(:CIDR => '192.168.1.128/26')
- cidr4_7 = IPAdmin::CIDR.new(:CIDR => '192.168.1.192/26')
-
- cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::/10')
- cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fe80::/10')
- cidr6_3 = IPAdmin::CIDR.new(:CIDR => 'fec0::/64')
- cidr6_4 =IPAdmin::CIDR.new(:CIDR => 'fec0::/126')
+ cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/26')
+ cidr4_3 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
+ cidr4_4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.128/26')
+ cidr4_5 = IPAdmin::CIDR.new(:CIDR => '192.168.1.192/26')
+ cidr4_6 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/27')
+ cidr4_7 = IPAdmin::CIDR.new(:CIDR => '192.168.1.32/27')
+ 
+ cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::/64')
+ cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::/66')
+ cidr6_3 = IPAdmin::CIDR.new(:CIDR => 'fec0::4000:0:0:0/66')
+ cidr6_4 = IPAdmin::CIDR.new(:CIDR => 'fec0::8000:0:0:0/66')
+ cidr6_5 = IPAdmin::CIDR.new(:CIDR => 'fec0::c000:0:0:0/66')
+ cidr6_6 = IPAdmin::CIDR.new(:CIDR => 'fec0::/67')
+ cidr6_7 = IPAdmin::CIDR.new(:CIDR => 'fec0::2000:0:0:0/67')
 
  # new
- table4 = IPAdmin::CIDRTable.new(4)
- table6 = IPAdmin::CIDRTable.new(6)
-
- # add_cidr
- table4.add_cidr(cidr4_1)
- table4.add_cidr(cidr4_2)
- table4.add_cidr(cidr4_3)
- table4.add_cidr(cidr4_4)
- table4.add_cidr(cidr4_5)
- table4.add_cidr(cidr4_6)
- table4.add_cidr(cidr4_7)
-
- table6.add_cidr(cidr6_1)
- table6.add_cidr(cidr6_2)
- table6.add_cidr(cidr6_3)
- table6.add_cidr(cidr6_4)
-
- # find_ip
- puts "#{ip4.desc} belongs in #{table4.find_ip(ip4).desc}"
- puts "#{ip6.desc} belongs in #{table6.find_ip(ip6).desc}"
-
- # find_space
- puts "all blocks that can hold a /27"
- list4 = table4.find_space(:Size => 27)
- list4.each do |cidr|
-    puts "  #{cidr.desc()}"
+ tree4 = IPAdmin::Tree.new(:Version => 4)
+ tree6 = IPAdmin::Tree.new(:Version => 6)
+
+ # add
+ tree4.add(cidr4_1)
+ tree4.add(cidr4_2)
+ tree4.add(cidr4_3)
+ tree4.add(cidr4_4)
+ tree4.add(cidr4_5)
+ tree4.add(cidr4_6)
+ tree4.add(cidr4_7)
+ 
+ tree6.add(cidr6_1)
+ tree6.add(cidr6_2)
+ tree6.add(cidr6_3)
+ tree6.add(cidr6_4)
+ tree6.add(cidr6_5)
+ tree6.add(cidr6_6)
+ tree6.add(cidr6_7)
+ 
+ # show
+ puts "TEST 1"
+ puts "tree4 is..."
+ puts tree4.show()
+ print "\n"
+ puts "tree6 is..."
+ puts tree6.show()
+ print "\n"
+ 
+ # collapse
+ puts "TEST 2"
+ puts "collapsed tree4 is..."
+ new_tree4 = tree4.collapse()
+ puts new_tree4.show()
+ print "\n"
+ puts "collapsed tree6 is..."
+ new_tree6 = tree6.collapse()
+ puts new_tree6.show()
+ print "\n"
+ 
+ # find space
+ puts "TEST 3"
+ puts "available /27 space"
+ space = tree4.find_space(:Size => 27)
+ space.each do |obj|
+    puts "  #{obj.desc}"
  end
-
- puts "first block that can hold a /64"
- list6 = table6.find_space(:Size => 64, :Limit => 1)
- list6.each do |cidr|
-    puts "  #{cidr.desc()}"
+ print "\n"
+ puts "available /67 space"
+ space = tree6.find_space(:Size => 67)
+ space.each do |obj|
+    puts "  #{obj.desc}"
  end
-
+ print "\n"
+ 
+ # remove
+ puts "TEST 4"
+ puts "removing #{cidr4_4.desc}"
+ tree4.remove(cidr4_4)
+ puts tree4.show()
+ print "\n"
+ puts "removing #{cidr6_4.desc}"
+ tree6.remove(cidr6_4)
+ puts tree6.show()
+ print "\n"
+ 
+ # prune
+ puts "TEST 5"
+ puts "pruning #{cidr4_2.desc}"
+ tree4.prune(cidr4_2)
+
+ puts "pruning #{cidr6_2.desc}"
+ tree6.prune(cidr6_2)
+ print "\n"
+ 
  # dump
- puts 'dump table4...'
- dump4 = table4.dump
- dump4.each do |cidr|
-    puts "  #{cidr.desc}"
- end
- puts 'dump table6...'
- dump6 = table6.dump
- dump6.each do |cidr|
-     puts "  #{cidr.desc}"
+ puts "TEST 6"
+ puts "dumping & printing tree4"
+ dumped = tree4.dump()
+ dumped.each do |val|
+    obj = val[:Object]
+    depth = val[:Depth]
+    if (depth > 0)
+        indent = " " * (depth*3)
+        puts indent << obj.desc()
+    else
+        puts obj.desc()
+    end
  end
- 
- puts "remove 192.168.1.0/26 from table4"
- table4.rem_cidr(cidr4_3)
- dump4 = table4.dump
- dump4.each do |cidr|
-    puts "  #{cidr.desc}"
+ print "\n"
+ puts "dumping & printing tree6"
+ dumped = tree6.dump()
+ dumped.each do |val|
+    obj = val[:Object]
+    depth = val[:Depth]
+    if (depth > 0)
+        indent = " " * (depth*3)
+        puts indent << obj.desc()
+    else
+        puts obj.desc()
+    end
  end
 
  print "\n\n\n"
@@ -232,10 +330,13 @@
  puts "IPAdmin Methods"
 
  # validate ip
+ puts "TEST 1"
  puts "192.168.1.0 is valid" if ( IPAdmin.validate_ipv4_addr('192.168.1.0') )
  puts "192.168.1.0 is valid" if ( IPAdmin.validate_ipv6_addr('fec0::0') )
+ print "\n"
 
  # validate netmask
+ puts "TEST 2"
  puts "255.255.255.0 is valid" if (IPAdmin.validate_ipv4_netmask('255.255.255.0') )
  puts "/24 is valid" if ( IPAdmin.validate_ipv4_netmask(24) )
  puts "/64 is valid" if ( IPAdmin.validate_ipv6_netmask(64) )
@@ -244,10 +345,12 @@
  cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/25')
  cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/10')
  cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
+ print "\n"
 
- # compare_cidr
- comp1 = IPAdmin.compare_cidr(cidr4_1,cidr4_2)
- comp2 = IPAdmin.compare_cidr(cidr6_1,cidr6_2)
+ # compare
+ puts "TEST 3"
+ comp1 = IPAdmin.compare(cidr4_1,cidr4_2)
+ comp2 = IPAdmin.compare(cidr6_1,cidr6_2)
  puts "#{(comp1[0]).desc} is the supernet of #{(comp1[1]).desc}"
  puts "#{(comp2[0]).desc} is the supernet of #{(comp2[1]).desc}"
 
@@ -256,26 +359,28 @@
  cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/128')
  cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::1/128')
 
- # merge_cidr
- puts "192.168.1.0/24 and 192.168.0.0/24 merge into #{IPAdmin.merge_cidr([cidr4_1,cidr4_2]).desc}"
- puts "fec0::0/128 and fec0::1/128 merge into #{IPAdmin.merge_cidr([cidr6_1,cidr6_2]).desc}"
-
  ip1 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.0')
  ip2 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.50')
+ print "\n"
 
  # range
+ puts "TEST 4"
  list = IPAdmin.range(:Boundaries => [ip1,ip2], :Bitstep => 20 )
  puts "ip's between #{ip1.desc} and #{ip2.desc} (bitstep of 20)"
  list.each do |x|
   puts "  #{x}"
  end
+ print "\n"
 
- # make_arpa
- puts "arpa for #{cidr4_1.desc()} is #{IPAdmin.make_arpa(cidr4_1)}"
- puts "arpa for #{cidr6_1.desc()} is #{IPAdmin.make_arpa(cidr6_1)}"
+ # arpa
+ puts "TEST 5"
+ puts "arpa for #{cidr4_1.desc()} is #{IPAdmin.arpa(cidr4_1)}"
+ puts "arpa for #{cidr6_1.desc()} is #{IPAdmin.arpa(cidr6_1)}"
+ print "\n"
  
- # v6_short
- puts "shorthand notation for  #{cidr6_1.network()} is #{IPAdmin.v6_short(cidr6_1.network)}"
+ # shorten
+ puts "TEST 6"
+ puts "shorthand notation for  #{cidr6_1.network()} is #{IPAdmin.shorten(cidr6_1.network)}"
 
  print "\n\n\n"
  #=====================================#

data/lib/ip_admin.rb

@@ -1,86 +1,12 @@
-module IPAdmin
-
-
-
-#============================================================================#
-# compare_cidr()
-#============================================================================#
-
-# Compare cidr addresses of two IPAdmin::CIDR objects.
-# - Arguments:
-#   * Two IPAdmin::CIDR objects
-#
-# - Returns:
-#   * if one object is a subnet of another, then return an array in order of
-#     [supernet,subnet]
-#   * if both are equal, return 1
-#   * if neither is a subnet of the other, return nil
-#
-# Example:
-#   supernet,subnet = IPAdmin.compare_cidr(cidr1,cidr2)
-#   puts "#{supernet.desc} is the supernet of #{subnet.desc}"
-#
-
-def compare_cidr(cidr1,cidr2)
-    
-    # we only accept CIDR objects
-    unless ( (cidr1.kind_of? IPAdmin::CIDR)&&(cidr2.kind_of? IPAdmin::CIDR) )
-        raise ArgumentError, "Arguments shouldbe of type IPAdmin::CIDR."
-    end
-    
-    # make sure both are same version
-    unless (cidr1.version == cidr2.version )
-        raise "Provider CIDR objects are incompatible: " +
-              "#{cidr1.desc}/ and #{cidr2.desc}."
-    end
-    
-    network1 = cidr1.packed_network
-    network2 = cidr2.packed_network
-    netmask1 = cidr1.packed_netmask
-    netmask2 = cidr2.packed_netmask
-    
-    
-    # make sure cidr's arent equal. return 1's if they are
-    if ( (network1 == network2) && (netmask1 == netmask2) )
-        return(1)
-    end
-    
-    
-    # whichever netmask is smaller will be the supernet
-    # if we '&' both networks by the supernet, and they are
-    # equal, then the supernet is the parent of the other network
-    if (netmask1 > netmask2)
-        if ( (netmask2 & network1) == (netmask2 & network2) )
-            supernet = cidr2
-            subnet = cidr1
-        end
-
-    else
-        if ( (netmask1 & network1) == (netmask1 & network2) )
-            supernet = cidr1
-            subnet = cidr2
-        end
+#Copyright (c) 2006 Dustin Spinhirne <dspinhir@yahoo.com>
+#Licensed under the same terms as Ruby, No Warranty is provided.
 
-    end
-    
-        
-    if (supernet)
-        return([supernet,subnet])
-    else
-        return(nil)
-    end
-    
-end
-module_function :compare_cidr 
- 
-#=====================================#
-#     
-#=====================================#
+module IPAdmin
 
 
 
 #============================================================================#
-# make_arpa()
+# arpa()
 #============================================================================#
 
 # Given the address in the provided IPAdmin::IPAddr or IPAdmin::CIDR object, 
@@ -95,9 +21,9 @@ module_function :compare_cidr
 #   * IP/CIDR address in in-addr.arpa or ip6.arpa format
 #
 # Example:
-#   arpa = IPAdmin.make_arpa(cidr)
+#   arpa = IPAdmin.arpa(cidr)
 #
-def make_arpa(object)
+def arpa(object)
 
     if (object.kind_of? IPAdmin::CIDR)
         base = object.network()
@@ -149,6 +75,10 @@ def make_arpa(object)
     return(arpa)
     
 end 
+module_function :arpa
+
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
+alias make_arpa arpa
 module_function :make_arpa
 
 #=====================================#
@@ -158,23 +88,183 @@ module_function :make_arpa
 
 
 #============================================================================#
-# merge_cidr()
+# compare()
 #============================================================================#
 
-# Merge (supernet) contiguous IPAdmin::CIDR blocks into a single block.
-# Blocks must be contiguous, and must be able to form a single supernet.
-# 
+# Compare IPAdmin::CIDR/IPAdmin::IPAddr objects, and determine if one
+# is the supernet of the other. IPAdmin::IPAddr objects will use a /32 or /128
+# netmask for the comparasin.
 # - Arguments:
-#   * array of IPAdmin::CIDR objects to merge
-# 
+#   * Two IPAdmin::CIDR/IPAdmin::IPAddr objects
+#
 # - Returns:
-#   * IPAdmin::CIDR object
+#   * if one object is a subnet of another, then return an array in order of
+#     [supernet,subnet]
+#   * if both are equal, return 1
+#   * if neither is a supernet of the other, return nil
 #
 # Example:
-#   merged = IPAdmin.merge_cidr([cidr1,cidr2])
+#   supernet,subnet = IPAdmin.compare_cidr(cidr1,cidr2)
+#   puts "#{supernet.desc} is the supernet of #{subnet.desc}"
+#
+
+def compare(obj1,obj2)
+    
+    # we only accept CIDR  or IPAddr objects
+    unless ( ( (obj1.kind_of?(IPAdmin::CIDR) ) ||
+               (obj1.kind_of?(IPAdmin::IPAddr) ) ) &&
+             ( (obj2.kind_of?(IPAdmin::CIDR) ) ||
+               (obj2.kind_of?(IPAdmin::IPAddr) ) ) )
+        raise ArgumentError, "One or more arguments is not of type " +
+                             "IPAdmin::CIDR or IPAdmin::IPAddr."
+    end
+    
+    # make sure both are same version
+    unless (obj1.version == obj2.version )
+        raise "Provided objects are of different IP versions."
+    end
+    
+    
+    # get network/netmask of each        
+    if ( obj1.kind_of?(IPAdmin::CIDR) )
+        network1 = obj1.packed_network
+        netmask1 = obj1.packed_netmask
+    else
+        network1 = obj1.packed_ip
+        if (obj1.version == 4)
+            netmask1 = (2**32 - 1)
+        else
+            netmask1 = (2**128 - 1)
+        end
+    end
+    
+    if ( obj2.kind_of?(IPAdmin::CIDR) )
+        network2 = obj2.packed_network
+        netmask2 = obj2.packed_netmask
+    else
+        network2 = obj2.packed_ip
+        if (obj2.version == 4)
+            netmask2 = (2**32 - 1)
+        else
+            netmask2 = (2**128 - 1)
+        end
+    end
+    
+    
+    # make sure object's arent equal. return 1's if they are
+    if ( (network1 == network2) && (netmask1 == netmask2) )
+        return(1)
+    end
+    
+    
+    # whichever netmask is smaller will be the supernet
+    # if we '&' both networks by the supernet, and they are
+    # equal, then the supernet is the parent of the other network
+    if (netmask1 > netmask2)
+        if ( (netmask2 & network1) == (netmask2 & network2) )
+            supernet = obj2
+            subnet = obj1
+        end
+
+    else
+        if ( (netmask1 & network1) == (netmask1 & network2) )
+            supernet = obj1
+            subnet = obj2
+        end
+
+    end
+    
+        
+    if (supernet)
+        return([supernet,subnet])
+    else
+        return(nil)
+    end
+    
+end
+module_function :compare 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# compare_cidr()
+#============================================================================#
+
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
+#
+def compare_cidr(cidr1,cidr2)
+    
+    puts "compare_cidr() DEPRICATED, DO NOT USE - this will be removed in future releases."
+    
+    # we only accept CIDR objects
+    unless ( (cidr1.kind_of? IPAdmin::CIDR)&&(cidr2.kind_of? IPAdmin::CIDR) )
+        raise ArgumentError, "Arguments shouldbe of type IPAdmin::CIDR."
+    end
+    
+    # make sure both are same version
+    unless (cidr1.version == cidr2.version )
+        raise "Provider CIDR objects are incompatible: " +
+              "#{cidr1.desc}/ and #{cidr2.desc}."
+    end
+    
+    network1 = cidr1.packed_network
+    network2 = cidr2.packed_network
+    netmask1 = cidr1.packed_netmask
+    netmask2 = cidr2.packed_netmask
+    
+    
+    # make sure cidr's arent equal. return 1's if they are
+    if ( (network1 == network2) && (netmask1 == netmask2) )
+        return(1)
+    end
+    
+    
+    # whichever netmask is smaller will be the supernet
+    # if we '&' both networks by the supernet, and they are
+    # equal, then the supernet is the parent of the other network
+    if (netmask1 > netmask2)
+        if ( (netmask2 & network1) == (netmask2 & network2) )
+            supernet = cidr2
+            subnet = cidr1
+        end
+
+    else
+        if ( (netmask1 & network1) == (netmask1 & network2) )
+            supernet = cidr1
+            subnet = cidr2
+        end
+
+    end
+    
+        
+    if (supernet)
+        return([supernet,subnet])
+    else
+        return(nil)
+    end
+    
+end
+module_function :compare_cidr 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# merge_cidr()
+#============================================================================#
+
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
 #
 def merge_cidr(cidr_list)
     
+    puts "merge_cidr() DEPRICATED, DO NOT USE - this will be removed in future releases."
     # make sure we have an array with at least 2 objects
     unless ( (cidr_list.kind_of? Array) && (cidr_list.length > 1) )
         raise ArgumentError, "Array of at least two IPAdmin::CIDR objects required."
@@ -641,52 +731,135 @@ module_function :range
 
 
 #============================================================================#
-# unpack_ipv4_addr()
+# shorten()
 #============================================================================#
 
-# Unack IPv4 address back into a printable string. No attempt at validation
-# is performed.
+# Take a standard IPv6 address, and format it in short-hand notation.
+# Address should not contain a netmask.
 # - Arguments:
-#   * Byte-packed IPv4 address
+#   * IPv6 address
 # 
 # - Returns:
-#   * IPv4 address.
-#
+#   * IPv6 short-hand address.
+# 
 # Example:
-#   unpacked = IPAdmin.unpack_ipv4_addr(packed)
+#   short = IPAdmin.shorten('fec0:0000:0000:0000:0000:0000:0000:0001')
 #
-def unpack_ipv4_addr(packed_ip)
+def shorten(addr)
+
+    # is this a string?
+    unless (addr.kind_of? String)
+        raise ArgumentError, "Expected String, but #{addr.class} provided."
+    end    
+
+    validate_ipv6_addr(addr)
     
-    octets = []
-    (0..3).each do |x|
-        octets[x] = packed_ip & 0xFF
-        octets[x] = (octets[x]).to_s
-        packed_ip = packed_ip >> 8
+    # make sure this isnt already shorthand
+    if (addr =~ /::/)
+        raise "#{addr} already appears to be in IPv6 shorthand notation."
     end
     
-    octets.reverse!
-    ip = octets.join('.')
     
-    return(ip)
-end
-module_function :unpack_ipv4_addr 
- 
-#=====================================#
-#     
-#=====================================#
-
-
-
-#============================================================================#
-# unpack_ipv4_netmask()
-#============================================================================#
-
-# Unack IPv4 netmask into a integer representing the number of
-# bits in the CIDR mask. No attempt at validation is performed.
-# - Arguments:
-#   * Byte-packed IPv4 netmask
-# 
-# - Returns:
+    # look for most 0 fields
+    found_zero = nil
+    pattern = ""
+    zero_fields = []
+    fields = addr.split(":")  
+    
+    (0..(fields.length-1)).each do |x|    
+        fields[x] = fields[x].to_i(16)
+        
+        if (fields[x] == 0)        
+            if (!found_zero)
+                found_zero = 1
+            end
+            pattern << ":0"            
+        else
+            if (found_zero)
+                found_zero = nil
+                pattern << ":"
+                zero_fields.push(pattern)
+                pattern = ""
+            end        
+        end
+                
+        fields[x] = fields[x].to_s(16)        
+    end    
+    
+
+    # pattern should be the longest set of 0's in a row
+    zero_fields.push(pattern) if (pattern != "")
+    pattern = ""
+    zero_fields.each do |x|
+        pattern = x if (x.length > pattern.length)          
+    end
+
+    
+
+    short = fields.join(":")
+    short.sub!(pattern,"::")
+    
+    return(short)
+end
+module_function :shorten
+
+#DEPRICATED, DO NOT USE - this will be removed in future releases.
+alias v6_short shorten
+module_function :v6_short
+    
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# unpack_ipv4_addr()
+#============================================================================#
+
+# Unack IPv4 address back into a printable string. No attempt at validation
+# is performed.
+# - Arguments:
+#   * Byte-packed IPv4 address
+# 
+# - Returns:
+#   * IPv4 address.
+#
+# Example:
+#   unpacked = IPAdmin.unpack_ipv4_addr(packed)
+#
+def unpack_ipv4_addr(packed_ip)
+    
+    octets = []
+    (0..3).each do |x|
+        octets[x] = packed_ip & 0xFF
+        octets[x] = (octets[x]).to_s
+        packed_ip = packed_ip >> 8
+    end
+    
+    octets.reverse!
+    ip = octets.join('.')
+    
+    return(ip)
+end
+module_function :unpack_ipv4_addr 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# unpack_ipv4_netmask()
+#============================================================================#
+
+# Unack IPv4 netmask into a integer representing the number of
+# bits in the CIDR mask. No attempt at validation is performed.
+# - Arguments:
+#   * Byte-packed IPv4 netmask
+# 
+# - Returns:
 #   * IPv4 netmask as number of bits (cidr format).
 #
 # Example:
@@ -790,85 +963,6 @@ module_function :unpack_ipv6_netmask
 
 
 
-#============================================================================#
-# v6_short()
-#============================================================================#
-
-# Take a standard IPv6 address, and format it in short-hand notation.
-# Address should not contain a netmask.
-# - Arguments:
-#   * IPv6 address
-# 
-# - Returns:
-#   * IPv6 short-hand address.
-# 
-# Example:
-#   short = IPAdmin.v6_short('fec0:0000:0000:0000:0000:0000:0000:0001')
-#
-def v6_short(addr)
-
-    # is this a string?
-    unless (addr.kind_of? String)
-        raise ArgumentError, "Expected String, but #{addr.class} provided."
-    end    
-
-    validate_ipv6_addr(addr)
-    
-    # make sure this isnt already shorthand
-    if (addr =~ /::/)
-        raise "#{addr} already appears to be in IPv6 shorthand notation."
-    end
-    
-    
-    # look for most 0 fields
-    found_zero = nil
-    pattern = ""
-    zero_fields = []
-    fields = addr.split(":")  
-    
-    (0..(fields.length-1)).each do |x|    
-        fields[x] = fields[x].to_i(16)
-        
-        if (fields[x] == 0)        
-            if (!found_zero)
-                found_zero = 1
-            end
-            pattern << ":0"            
-        else
-            if (found_zero)
-                found_zero = nil
-                pattern << ":"
-                zero_fields.push(pattern)
-                pattern = ""
-            end        
-        end
-                
-        fields[x] = fields[x].to_s(16)        
-    end    
-    
-
-    # pattern should be the longest set of 0's in a row
-    zero_fields.push(pattern) if (pattern != "")
-    pattern = ""
-    zero_fields.each do |x|
-        pattern = x if (x.length > pattern.length)          
-    end
-
-    
-
-    short = fields.join(":")
-    short.sub!(pattern,"::")
-    
-    return(short)
-end
-module_function :v6_short
-    
-#=====================================#
-#     
-#=====================================#
-
-
-
 #============================================================================#
 # validate_ipv4_addr()
 #============================================================================#
@@ -1184,7 +1278,11 @@ class CIDR
     # hash of custom tags. should be in the format tag => value
     attr_reader :tag
     
-    # attr_writer - hash of custom tags. should be in the format tag => value
+    # Hash of custom tags. should be in the format tag => value
+    #
+    # Example:
+    #   cidr4.tag['test'] = 'modified cidr4 tag'
+    #
     def tag=(new_tag)
         unless (new_tag.kind_of? Hash)
             raise ArgumentError, "Expected Hash, but #{new_tag.class} provided."
@@ -1347,8 +1445,8 @@ class CIDR
 # contains()
 #============================================================================#
 
-# Determines if cidr block of IPAdmin::CIDR contains IP address
-# of provided IPAdmin:IPAddr object.
+# Determines if IPAdmin::CIDR object contains (is supernet of)
+# provided IPAdmin::CIDR or IPAdmin:IPAddr object.
 # - Arguments:
 #   * IPAdmin:IPAddr object
 # 
@@ -1358,32 +1456,46 @@ class CIDR
 # Example:
 #   contains = cidr.contains(ip)
 #
-    def contains(ip_obj)
+    def contains(object)
+        is_contained = nil
                 
-        unless (ip_obj.kind_of? IPAdmin::IPAddr)
-            raise ArgumentError, "Expected IPAdmin::IPAddr object, but #{ip_obj.class} provided."
+        if (object.kind_of?(IPAdmin::CIDR))
+            network = object.packed_network 
+            netmask = object.packed_netmask
+                       
+        elsif (object.kind_of?(IPAdmin::IPAddr))
+            network = object.packed_ip   
+                     
+        else 
+            raise ArgumentError, "Expected IPAdmin::CIDR or IPAdmin::IPAddr " +
+                                 " object but #{object.class} provided."
         end
         
-        if ( (ip_obj.version == 4) && (@version == 4) )
-            v4_all_f = (2**32)-1        
-            hostmask = @netmask ^ v4_all_f
-            if ( (ip_obj.packed_ip | hostmask) == (@network | hostmask) )
-                return(1)
+        
+        unless (object.version == @version)
+            raise "Attempted to compare a version #{object.version} IP " +
+                      "with a version #{@version} network."
+        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)
+            if (object.kind_of?(IPAdmin::IPAddr) )
+                is_contained = 1
+            else
+                is_contained = 1 if (netmask > @netmask)
             end
             
-        elsif ( (ip_obj.version == 6) && (@version == 6) )
-            v6_all_f = (2**128)-1
-            hostmask = @netmask ^ v6_all_f
-            if ( (ip_obj.packed_ip | hostmask) == (@network | hostmask) )
-                return(1)
-            end
-        
         else
-            raise "Attempted to compare a version #{ip_obj.version} IP " +
-                  "with a version #{@version} network."
+            if ( (network | @hostmask) == (@network | @hostmask) )
+                is_contained = 1
+            end
         end
         
-        return(nil)
+                
+        return(is_contained)
     end
 
 #=====================================#
@@ -1990,8 +2102,7 @@ end
 #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
 
 =begin rdoc
-A class & series of methods for creating and manipulating CIDR-based
-heirarchical tables. Both IPv4 and IPv6 are supported.
+DEPRICATED, DO NOT USE - this will be removed in future releases.
 =end
 
 class CIDRTable
@@ -2002,11 +2113,8 @@ class CIDRTable
 # attr_reader / attr_writer
 #============================================================================#
 
-    
-    # ip table version (4 or 6)
-    attr_reader :version
-    
-    # contains IPAdmin::CIDR entries. hash (IPAdmin::CIDR => IPAdmin::CIDRTable)
+    # attr_reader/attr_writer
+    attr_reader :version    
     attr_reader :cidr_table
     
 #=====================================#
@@ -2019,14 +2127,11 @@ class CIDRTable
 # initialize()
 #============================================================================#
 
-# - Arguments:
-#   * IP version (4 or 6)
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
 #
-# Example:
-#   table = IPAdmin::CIDRTable.new(4)
-# 
     def initialize(version)
         
+        puts "DEPRICATED, DO NOT USE - this will be removed in future releases."
         unless ( version.kind_of? Fixnum )
             raise ArgumentError, "Expected Fixnum, but #{version.class} provided."
         end
@@ -2049,16 +2154,7 @@ class CIDRTable
 # add_cidr()
 #============================================================================#
 
-# Add an IPAdmin::CIDR object to this table
-# 
-# - Arguments:
-#   * IPAdmin::CIDR object
-# 
-# - Returns:
-#   * nothing
-#
-# Example:
-#   table.add_cidr(cidr)
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
 #
     def add_cidr(new_cidr)
         
@@ -2134,16 +2230,7 @@ class CIDRTable
 # dump()
 #============================================================================#
 
-# Dump contents of this table
-# 
-# - Arguments:
-#   * none
-# 
-# - Returns:
-#   * ordered array of IPAdmin::CIDR objects within this table
-#
-# Example:
-#   cidr_list = table.dump()
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
 #
     def dump()
     
@@ -2182,17 +2269,7 @@ class CIDRTable
 # find_ip()
 #============================================================================#
 
-# Find longest matching IPAdmin::CIDR object whose cidr block contains the IP  
-# address within the provided IPAdmin::IPAddr object
-# 
-# - Arguments:
-#   * IPAdmin::IPAddr object
-# 
-# - Returns:
-#   * IPAdmin::CIDR object, or nil on no match
-#
-# Example:
-#   cidr = table.find_ip(ip)
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
 #
     def find_ip(ip_obj)
         
@@ -2232,19 +2309,7 @@ class CIDRTable
 # find_space()
 #============================================================================#
 
-# Find CIDR blocks of at least X size. Returns only the smallest matching
-# subnets of each supernet. 
-# 
-# - Arguments:
-#   * Hash with the following fields:
-#       - :Size -- subnet size (number of bits)
-#       - :Limit -- max entries to return
-# 
-# - Returns:
-#   * ordered array of IPAdmin::CIDR objects, or nil on no match
-#
-# Example:
-#   cidr_list = table.find_space(:Size => 27)
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
 #
     def find_space(options)
         limit = nil
@@ -2338,16 +2403,7 @@ class CIDRTable
 # rem_cidr()
 #============================================================================#
 
-# Remove an IPAdmin::CIDR object from this table
-# 
-# - Arguments:
-#   * IPAdmin::CIDR object
-# 
-# - Returns:
-#   * nothing
-#
-# Example:
-#   table.rem_cidr(cidr)
+# DEPRICATED, DO NOT USE - this will be removed in future releases.
 #
     def rem_cidr(cidr)
         
@@ -2434,7 +2490,11 @@ class IPAddr
     # hash of custom tags. should be in the format tag => value
     attr_reader :tag
     
-    # attr_writer - hash of custom tags. should be in the format tag => value
+    # Hash of custom tags. should be in the format tag => value
+    #
+    # Example:
+    #   ip4.tag['test'] = 'modified ip4 tag'
+    #
     def tag=(new_tag)
         unless (new_tag.kind_of? Hash)
             raise ArgumentError, "Expected Hash, but #{new_tag.class} provided."
@@ -2911,6 +2971,883 @@ end
 #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
 
 
+
+
+
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  BEGIN class Tree
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+=begin rdoc
+A class & series of methods for creating and manipulating IP-based
+heirarchical trees. Both IPv4 and IPv6 are supported.
+=end
+
+class Tree
+
+    # define structure for our tree leaves
+    NetStruct = Struct.new(:network, :netmask, :object, :subnets)
+
+#============================================================================#
+# attr_reader / attr_writer
+#============================================================================#
+
+    
+    # IP version for this tree (4 or 6)
+    attr_reader :version
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# initialize()
+#============================================================================#
+
+# - Arguments:
+#   * Hash with the following fields
+#       - :Version -- IP version for this tree (4 or 6)
+#
+# Example:
+#   table = IPAdmin::CIDRTable.new(:Version => 4)
+# 
+    def initialize(options)
+        unless (options.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{options.class} provided."
+        end
+        
+        if ( options.has_key?(:Version) )
+            @version =  options[:Version]
+            
+            unless ( @version == 4 || @version == 6 )
+                raise "IP version should be either 4 or 6."
+            end
+        else
+            raise ArgumentError, "Missing arguments: Version."
+        end
+
+        if (@version == 4)
+            @all_f = 2**32 - 1
+        else
+            @all_f = 2**128 - 1
+        end
+        
+        # root of our ordered IP tree
+        @root = []
+
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# add()
+#============================================================================#
+
+# Add an IPAdmin::CIDR/IPAdmin::IPAddr object to the tree. IPAdmin::IPAddr 
+# objects will be treated as either /32 or /128 addresses when added to the
+# tree.
+#
+# - Arguments:
+#   * IPAdmin::CIDR/IPAdmin::IPAddr object
+#
+# - Returns:
+#   * nothing
+#
+# Example:
+#   tree.add(cidr)
+#
+    def add(object)
+
+        # make sure we have an array with at least 2 objects
+        unless ( object.kind_of?(IPAdmin::CIDR) || 
+                 object.kind_of?(IPAdmin::IPAddr) )
+            raise ArgumentError, "IPAdmin::CIDR/IPAdmin::IPAddr object " +
+                                 "required but #{object.class} provided."
+        end
+
+        unless (object.version == @version )
+            raise "IP version #{object.version} is incompatible with " +
+                  "Tree IP version #{@version}."
+        end
+
+
+        net_struct = create_struct(object)
+
+
+        # 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)
+
+            if (is_contained)
+                net_struct.subnets.push(entry)                
+            end
+        end
+        
+        net_struct.subnets.each do |entry|
+            home_branch.delete(entry)
+        end
+        
+
+        # add new object as an ordered entry to home_branch
+        add_to_branch(net_struct,home_branch)
+
+        return(nil)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# add_to_branch() private
+#============================================================================#
+
+# Add Netstruct object to an array of NetStruct's
+#
+# - Arguments:
+#   * NetStruct, and array of NetStruct's in which to add it
+#
+# - Returns:
+#   * none
+#
+# Example:
+#   add_to_branch(net_struct,branch)
+#
+    def add_to_branch(net_struct,branch)
+        index = 0
+        branch.each do            
+            if(net_struct.network < (branch[index]).network)
+                break
+            end
+            index += 1
+        end
+
+        branch.insert(index, net_struct)
+
+        return()
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# collapse()
+#============================================================================#
+
+# 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.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * IPAdmin::Tree object
+#
+# Example:
+#   new_tree = tree.collapse()
+#
+    def collapse()
+            tree = IPAdmin::Tree.new(:Version => @version)
+            branch = collapse_branch(@root)
+            dumped = dump_branch(branch)
+            dumped.each do |entry|
+                net_struct = entry[:NetStruct]
+
+                if (@version == 4)
+                    network = IPAdmin.unpack_ipv4_addr(net_struct.network)
+                    netmask = IPAdmin.unpack_ipv4_netmask(net_struct.netmask)
+                else
+                    network = IPAdmin.unpack_ipv6_addr(net_struct.network)                    
+                    netmask = IPAdmin.unpack_ipv6_netmask(net_struct.netmask)
+                end
+                cidr = IPAdmin::CIDR.new(:CIDR => "#{network}/#{netmask}")
+                tree.add(cidr)
+            end
+        return(tree)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# collapse_branch() private
+#============================================================================#
+
+# Collapse this branch, and any child branches that it may have.
+#
+# - Arguments:
+#   * Array of NetStruct objects
+#
+# - Returns:
+#   * Array of NetStruct objects. The 'object' filed will be null.
+#
+# Example:
+#   new_branch = collapse_branch(old_branch)
+#
+    def collapse_branch(old_branch)
+        new_branch = []
+
+        # create new_branch from old one
+        old_branch.each do |entry|
+            net_struct = NetStruct.new(entry.network,entry.netmask,nil,[])
+
+            if (entry.subnets.length > 0)
+                # get all child subnets of this branch entry
+                children = collapse_branch(entry.subnets)
+                grandchildren = nil
+
+                # if any child subnets are equal to this branch entry
+                # then copy the grandchild subnets and delete it
+                children.each do |child|
+                    if ( (entry.network == child.network) &&
+                        (entry.netmask == child.netmask) )
+                        if (child.subnets.length > 0)
+                            grandchildren = child.subnets
+                        end                        
+                        children.delete(child)
+                        break
+                    end
+                end
+                
+                net_struct.subnets.concat(children)
+                if (grandchildren)
+                    grandchildren.each do |grandchild|
+                        add_to_branch(grandchild,net_struct.subnets)
+                    end
+                end
+            end
+
+            new_branch.push(net_struct)
+        end
+
+        # merge subnets of this new branch by removing them from 'new_branch',
+        # and categorizing them into hash of arrays (key=netmask) 
+        # within each categorization we merge contiguous subnets
+        # and then remove them from that category & put them back into 
+        # 'new_branch'. we do this until our list stops getting any shorter
+        categories = {}
+        branch_length = 0
+        until (branch_length == new_branch.length)
+            branch_length = new_branch.length
+            
+            # bust in to categories
+            new_branch.each do |entry|
+                netmask = entry.netmask
+                if (categories.has_key?(netmask) )
+                    (categories[netmask]).push(entry)
+                else
+                    categories[netmask] = [entry]
+                end
+            end
+            new_branch.clear
+            
+            categories.each_key do |netmask|
+                entries = categories[netmask]
+                
+                until (entries.length == 0)
+                    supernet = nil
+                    supermask = nil
+                    multiplier = 0                
+                    first = entries[0]
+                    to_merge = []
+                    
+                    # take first entry and use it to form a base
+                    # supernet address. this supernet should have
+                    # x number of subnets in it, so we look for
+                    # those subnets & if found store them
+                    entries.each do |entry|
+                        num_required = 2**multiplier
+                        supermask = (netmask << multiplier) & @all_f
+                        supernet = supermask & first.network if (!supernet)
+
+                        if ( (entry.network & supermask) == supernet)
+                            to_merge.push(entry)
+                            if ( (to_merge.length == num_required) &&
+                                 (entries.length > (2**multiplier) ) )
+                                multiplier += 1                            
+                            end
+                        else
+                            multiplier -= 1
+                            supermask = (netmask << multiplier) & @all_f
+                            break 
+                        end
+                    end
+                
+                    # now that we have the child members of our new supernet
+                    # take any grandchild subnets that they may have and 
+                    # add them to the new supernet. then kill the children
+                    net_struct = NetStruct.new(supernet,supermask,nil,[])
+                    (2**multiplier).times do
+                        to_kill = to_merge.shift
+                        net_struct.subnets.concat(to_kill.subnets)
+                        entries.delete(to_kill)
+                    end 
+                    new_branch.push(net_struct)
+
+                end
+            end
+            categories.clear
+        end
+
+        return(new_branch)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# contains() private
+#============================================================================#
+
+# Is the first NetStruct object the supernet of the second?
+#
+# - Arguments:
+#   * Two NetStruct objects
+#
+# - Returns:
+#   * 1 if struct1 contains or is equal to struct2, or nil if not.
+#
+# Example:
+#   is_contained = contains(struct1,struct2)
+#
+    def contains(struct1,struct2)
+
+        # make sure we have appropriate types 
+        unless (struct1.kind_of?(IPAdmin::Tree::NetStruct) && 
+                struct2.kind_of?(IPAdmin::Tree::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 = nil
+        if (network1 == network2)
+            if (netmask2 >= netmask1)
+                is_contained = 1
+            end
+        else
+            if ( (network1 | hostmask1) == (network2 | hostmask1) )
+                is_contained = 1
+            end
+        end
+
+        return(is_contained)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# create_struct() private
+#============================================================================#
+
+# Create a NetStruct object from a CIDR or IPAddr object
+#
+# - Arguments:
+#   * IPAdmin::CIDR or IPAdmin::IPAddr object
+#
+# - Returns:
+#   * IPAdmin::Tree::NetStruct object
+#
+# Example:
+#   net_struct = create_struct(object)
+#
+    def create_struct(object)
+
+        if ( object.kind_of?(IPAdmin::CIDR) )
+            network = object.packed_network
+            netmask = object.packed_netmask
+
+        elsif ( object.kind_of?(IPAdmin::IPAddr) )
+            network = object.packed_ip
+            netmask = @all_f
+        end
+
+        net_struct = NetStruct.new(network, netmask, object, [])
+
+        return(net_struct)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# dump
+#============================================================================#
+
+# Dump the contents of this tree.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * ordered array of hashes in the form: :Object => CIDR or IPAddr object
+#                                          :Depth => (depth level in tree)
+# Example:
+#   dumped = tree.dump()
+#
+    def dump()
+        list = []
+        dumped = dump_branch(@root)
+        
+        dumped.each do |entry|
+            depth = entry[:Depth]
+            net_struct = entry[:NetStruct]
+            object = net_struct.object
+            list.push({:Depth => depth, :Object => object})
+        end
+        
+        return(list)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# dump_branch() 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::Tree::NetStruct object
+#                              :Depth => (depth level in tree)
+# Example: 
+#   dumped = dump_branch(branch)
+#  
+    def dump_branch(branch,depth=nil)
+        list = []
+        depth = 0 if (!depth)
+        
+        branch.each do |entry|
+            subnets = entry.subnets            
+            list.push({:NetStruct => entry, :Depth => depth})
+            
+            if (subnets.length > 0)
+                list.concat( dump_branch(subnets, (depth+1) ) )
+            end
+            
+        end
+        
+        return(list)
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# find()
+#============================================================================#
+
+# Find the branch of this tree to which an IPAdmin::CIDR or IPAdmin::IPAddr 
+# would belong if added. This is useful for finding the longest match for
+# an IP address.
+#
+# - Arguments:
+#   * IPAdmin::CIDR or IPAdmin::IPAddr object
+#
+# - Returns:
+#   * IPAdmin::CIDR object, or nil if not found
+#
+# Example:
+#   longest_match = tree.find(ip)
+#
+    def find(object)
+        unless ( object.kind_of?(IPAdmin::CIDR) || 
+                 object.kind_of?(IPAdmin::IPAddr) )
+            raise ArgumentError, "IPAdmin::CIDR/IPAdmin::IPAddr object " +
+                                 "required but #{object.class} provided."
+        end
+
+        unless (object.version == @version )
+            raise "IP version #{object.version} is incompatible with " +
+                  "Tree IP version #{@version}."
+        end
+
+        net_struct = create_struct(object)
+        home_struct,home_branch = find_home(net_struct, @root)
+        found_obj = home_struct.object if (home_struct)
+
+        return(found_obj)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# find_home() private
+#============================================================================#
+
+# Find the branch to which a NetStruct object belongs.
+#
+# - Arguments:
+#   * IPAdmin::Tree::NetStruct to find, and Array of
+#     IPAdmin::Tree::NetStruct's to search
+#
+# - Returns:
+#   * array of: container IPAdmin::Tree::NetStruct object,
+#               and container branch, or nil
+#
+# Example:
+#   branch = find_home(net_struct,branch)
+#
+    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
+                
+                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
+
+                ret_val = [home_struct,home_branch]
+                break
+            end
+        end
+
+        return(ret_val)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# find_space()
+#============================================================================#
+
+# Find Tree entries of at least X size. Returns only the smallest matching
+# subnets of each supernet. 
+# 
+# - Arguments:
+#   * Hash with the following fields:
+#       - :Size -- subnet size (number of bits)
+#       - :Limit -- max entries to return
+# 
+# - Returns:
+#   * ordered array of IPAdmin::CIDR/IPAdmin::IPAddr objects
+#
+# Example:
+#   list = tree.find_space(:Size => 27)
+#
+    def find_space(options)
+        limit = nil
+        list = []
+             
+        # validate options
+        unless (options.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{options.class} provided."
+        end
+        
+        unless ( options.has_key?(:Size) )
+            raise ArgumentError, "Missing argument :Size."
+        end
+        subnet_size = options[:Size]        
+        
+        if ( options.has_key?(:Limit) )
+            limit = options[:Limit]
+        end        
+        
+        
+        # check that subnet_size is a valid size
+        if (@version == 4)
+            unless ( (subnet_size > 0) && (subnet_size < 33) )
+                raise "#{subnet_size} is out of range for an " +
+                      "IP version #{@version} Tree."
+            end
+            
+        else
+            unless ( (subnet_size > 0) && (subnet_size < 129) )
+                raise "#{subnet_size} is out of range for an " +
+                      "IP version #{@version} Tree."
+            end
+        end
+        
+        search_list = dump_branch(@root) 
+                       
+        search_list.each do |entry|
+            depth = entry[:Depth]
+            net_struct = entry[:NetStruct]
+            
+            # 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
+            
+        end
+        
+        return(list)
+        
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# prune()
+#============================================================================#
+
+# Remove an IPAdmin::CIDR/IPAdmin::IPAddr object, and all child
+# objects from the tree.
+#
+# - Arguments:
+#   * IPAdmin::CIDR or IPAdmin::IPAddr object
+#
+# - Returns:
+#   * 1 on success, or nil
+#
+# Example:
+#   did_prune = tree.prune(ip)
+#
+    def prune(object)
+        unless ( object.kind_of?(IPAdmin::CIDR) || 
+                 object.kind_of?(IPAdmin::IPAddr) )
+            raise ArgumentError, "IPAdmin::CIDR/IPAdmin::IPAddr object " +
+                                 "required but #{object.class} provided."
+        end
+
+        unless (object.version == @version )
+            raise "IP version #{object.version} is incompatible with " +
+                  "Tree IP version #{@version}."
+        end
+
+        net_struct = create_struct(object)
+        home_struct,home_branch = find_home(net_struct, @root)
+
+        # remove if home_struct.object = object
+        if (home_struct.object = object)           
+            home_branch.delete(home_struct)
+            pruned = 1
+        end
+
+        return(pruned)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# remove()
+#============================================================================#
+
+# Remove a single IPAdmin::CIDR/IPAdmin::IPAddr object from the tree. 
+#
+# - Arguments:
+#   * IPAdmin::CIDR or IPAdmin::IPAddr object
+#
+# - Returns:
+#   * 1 on success, or nil
+#
+# Example:
+#   did_remove = tree.remove(ip)
+#
+    def remove(object)
+        unless ( object.kind_of?(IPAdmin::CIDR) || 
+                 object.kind_of?(IPAdmin::IPAddr) )
+            raise ArgumentError, "IPAdmin::CIDR/IPAdmin::IPAddr object " +
+                                 "required but #{object.class} provided."
+        end
+
+        unless (object.version == @version )
+            raise "IP version #{object.version} is incompatible with " +
+                  "Tree IP version #{@version}."
+        end
+
+        net_struct = create_struct(object)
+        home_struct,home_branch = find_home(net_struct, @root)
+
+        # remove if home_struct.object = object
+        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
+            end
+            
+            home_branch.delete(home_struct)
+            removed = 1
+        end
+
+        return(removed)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+#============================================================================#
+# show()
+#============================================================================#
+
+# Print the tree in a nicely formatted string.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * string representing the contents of the tree
+#
+# Example:
+#   puts tree.show()
+#
+    def show()
+        printed = ""
+        list = dump_branch(@root)
+
+        list.each do |entry|
+            net_struct = entry[:NetStruct]
+            depth = entry[:Depth]
+
+            if (@version == 4)
+                network = IPAdmin.unpack_ipv4_addr(net_struct.network)
+                netmask = IPAdmin.unpack_ipv4_netmask(net_struct.netmask)
+                
+            else 
+                network = IPAdmin.unpack_ipv6_addr(net_struct.network)
+                netmask = IPAdmin.unpack_ipv6_netmask(net_struct.netmask)
+                network = IPAdmin.shorten(network)
+            end
+
+            if (depth == 0)
+                indent = ""
+            else
+                indent = " " * (depth*3)
+            end
+
+            printed << "#{indent}#{network}/#{netmask}\n"
+        end
+
+        return(printed)
+    end
+
+#=====================================#
+#
+#=====================================#
+
+
+
+private :add_to_branch, :contains,  :collapse_branch,   :create_struct,
+        :dump_branch,   :find_home
+
+end
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  END class Tree
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+
+
+
 end # module IPAdmin