Completed ::summarize documentation

1 files changed, 59 insertions, 2 deletions

diff --git a/lib/ipaddress/ipv4.rb b/lib/ipaddress/ipv4.rb
index 4124685..558aa84 100644
--- a/lib/ipaddress/ipv4.rb
+++ b/lib/ipaddress/ipv4.rb
@@ -1,6 +1,5 @@
 require 'ipaddress/ipbase'
 require 'ipaddress/prefix'
-require 'pp'
 
 # 
 # =Name
@@ -601,7 +600,65 @@ module IPAddress; class IPv4 < IPBase
   end
 
   #
-  
+  # Summarization (or aggregation) is the process when two or more
+  # networks are taken together to check if a supernet, including all
+  # and only these networks, exists. If it exists then this supernet
+  # is called the summarized (or aggregated) network.
+  #
+  # It is very important to understand that summarization can only
+  # occur if there are no holes in the aggregated network, or, in other
+  # words, if the given networks fill completely the address space
+  # of the supernet. So the two rules are:
+  #
+  # 1) The aggregate network must contain +all+ the IP addresses of the
+  #    original networks;
+  # 2) The aggregate network must contain +only+ the IP addresses of the
+  #    original networks;
+  #
+  # A few examples will help clarify the above. Let's consider for
+  # instance the following two networks:
+  #
+  #   ip1 = IPAddress("172.16.10.0/24")
+  #   ip2 = IPAddress("172.16.11.0/24")
+  #
+  # These two networks can be expressed using only one IP address
+  # network if we change the prefix. Let Ruby do the work:
+  #
+  #   IPAddress::IPv4::summarize(ip1,ip2).to_s
+  #     #=> "172.16.10.0/23"
+  #
+  # We note how the network "172.16.10.0/23" includes all the addresses
+  # specified in the above networks, and (more important) includes
+  # ONLY those addresses. 
+  #
+  # If we summarized +ip1+ and +ip2+ with the following network:
+  #
+  #   "172.16.0.0/16"
+  #
+  # we would have satisfied rule #1 above, but not rule #2. So "172.16.0.0/16"
+  # is not an aggregate network for +ip1+ and +ip2+.
+  #
+  # If it's not possible to compute a single aggregated network for all the
+  # original networks, the method returns an array with all the aggregate
+  # networks found. For example, the following four networks can be
+  # aggregated in a single /22:
+  #
+  #   ip1 = IPAddress("10.0.0.1/24")
+  #   ip2 = IPAddress("10.0.1.1/24")
+  #   ip3 = IPAddress("10.0.2.1/24")
+  #   ip4 = IPAddress("10.0.3.1/24")
+  #   IPAddress::IPv4::summarize(ip1,ip2,ip3,ip4).to_s
+  #     #=> "10.0.0.0/22", 
+  #
+  # But the following networks can't be summarized in a single network:
+  #
+  #   ip1 = IPAddress("10.0.1.1/24")
+  #   ip2 = IPAddress("10.0.2.1/24")
+  #   ip3 = IPAddress("10.0.3.1/24")
+  #   ip4 = IPAddress("10.0.4.1/24")
+  #   IPAddress::IPv4::summarize(ip1,ip2,ip3,ip4).map{|i| i.to_s}
+  #     #=> ["10.0.1.0/24","10.0.2.0/23","10.0.4.0/24"]
+  #
   def self.summarize(*args)
     # one network? no need to summarize
     return args.flatten.first if args.size == 1