ipaddress 0.7.5 → 0.8.0

data/CHANGELOG.rdoc

@@ -1,3 +1,16 @@
+== ipaddress 0.8.0
+
+CHANGED:: Removed extension methods and extension directory to facilitate integration with the stdlib
+CHANGED:: Reworked IPv4#<=>, now intuitively sorts objects based on the prefix
+CHANGED:: IPv4#supernet now returns "0.0.0.0/0" if supernetting with a prefix less than 1
+CHANGED:: IPv4#subnet now accept a new prefix instead of number of subnets (as per RFC3531) 
+NEW::     IPv6#network
+NEW::     Prefix128#host_prefix
+NEW::     IPv6#broadcast_u128
+NEW::     IPv6#each
+NEW::     IPv6#<=>
+NEW::     IPv4#split
+
 == ipaddress 0.7.5
 
 CHANGED:: IPAddress::IPv4#each_host to improve speed

data/README.rdoc

@@ -14,44 +14,22 @@ examples of typical usage.
 
 == Requirements
 
-* Ruby >= 1.8.6 (not tested with previous versions)
+* Ruby >= 1.8.7 (not tested with previous versions)
+* Ruby 1.9.2 or later is strongly recommended 
 
-IPAddress works perfectly on:
+IPAddress 0.8.0 has been tested on:
 
-* Ruby 1.8.6 (2007-03-13 patchlevel 0) 
-* Ruby 1.8.7 
-* Ruby 1.9.1 
-* Ruby 1.9.2dev (2010-06-08 revision 28230)
-* Ruby 1.9.2dev (2010-07-15 revision 28653)
-* Rubinius 1.0.1 (1.8.7 release 2010-06-03 JI)
-* Ironruby >= 1.0
+* ruby-1.8.7-p334 [ i386 ]
+* ree-1.8.7-2011.03 [ i386 ]
+* rbx-head [ ]
+* jruby-1.6.1 [ linux-i386-java ]
+* ruby-1.9.1-p431 [ i386 ]
+* ruby-1.9.2-p180 [ i386 ]
 
-It hasn't yet been tested on any other platform, so if you want to collaborate feel 
+If you want to collaborate feel 
 free to send a small report to my email address, or 
 {join the discussion}[http://groups.google.com/group/ruby-ipaddress]. 
 
-== Why not using IPAddr?
-
-IPAddr is the IP addresses library that comes with Ruby standard
-lib. We found this library, although very well written, not very
-suitable for all our needs, and not very flexible. 
-
-Some quick examples of things you can't do with IPAddr:
-
-* store both the address and the prefix information
-* quickly find the broadcast address of a network
-* iterate over hosts 
-* perform subnetting or network aggregation
-
-Many methods and procedures are so old that they have been 
-declared deprecated by the IETF, and some others have bugs in their 
-implementation.  
-
-Moreover, IPAddress is more robust and is already around 50% faster than IPAddr,
-in addition to provide an organic API with logical separation and OO structure.
-
-We hope that IPAddress will address all these issues and meet all your
-needs in network programming.
 
 == Installation
 
@@ -81,7 +59,7 @@ documentation with Rake:
   ipaddress$ rake rdoc
 
 The latest documentation can be found online at 
-{this address}[http://rubydoc.info/gems/ipaddress/0.7.0/frames]
+{this address}[http://rubydoc.info/gems/ipaddress/0.8.0/frames]
  
 == IPv4
 
@@ -127,9 +105,12 @@ networks. Therefore, the default prefix will be /32, or
 255.255.255.255. For example:
 
   # let's declare an host address
-  host = IPAddress::IPv4.new "10.1.1.1."
+  host = IPAddress::IPv4.new "10.1.1.1"
+
+  puts host.to_string
+    #=> "10.1.1.1/32"
   
-The new created object will have prefix /32, which is the same 
+The new created object has prefix /32, which is the same 
 as we created the following:
 
   host = IPAddress::IPv4.new "10.1.1.1/32"
@@ -222,7 +203,7 @@ address:
   net.to_string
     #=> "172.16.10.0/24"
 
-The IPv4#network method creates a new IPv4 object from the network
+Method IPv4#network creates a new IPv4 object from the network
 number, calculated after the original object. We want to outline here
 that the network address is a perfect legitimate IPv4 address, which
 just happen to have all zeroes in the host portion. 
@@ -402,63 +383,83 @@ For example, if you have network "172.16.10.0/24", we can subnet it
 into 4 smaller subnets. The new prefix will be /26, because 4 is 2^2
 and therefore we add 2 bits to the network prefix (24+2=26).
 
-Subnetting is easy with IPAddress. Let's work out the last example:
+Subnetting is easy with IPAddress. You actually have two options:
 
-  network = IPAddress("172.16.10.0/24")
+* IPv4#subnet: specify a new prefix
+* IPv4#split: tell IPAddress how many subnets you want to create.
 
-  subnets = network / 4
-    #=> [#<IPAddress::IPv4:0xb7b10e10 @octets=[172,16,10,0] [...]
-         #<IPAddress::IPv4:0xb7b0f1b4 @octets=[172,16,10,64] [...]
-         #<IPAddress::IPv4:0xb7b0e5ac @octets=[172,16,10,128] [...]  
-         #<IPAddress::IPv4:0xb7b0e0c0 @octets=[172,16,10,192] [...]]
+Let's examine IPv4#subnet first. Say you have network "172.16.10.0/24"
+and you want to subnet it into /26 networks. With IPAddress it's very 
+easy:
+
+  network = IPAddress "172.16.10.0/24"
+
+  subnets = network.subnet(26)
 
   subnets.map{|i| i.to_string}
-    #=> ["172.16.10.0/26", "172.16.10.64/26", "172.16.10.128/26", 
+    #=> ["172.16.10.0/26", 
+         "172.16.10.64/26", 
+         "172.16.10.128/26", 
          "172.16.10.192/26"]
 
-You can also use method IPv4#subnets, which is an alias for
-IPv4#/. Please note that you don't have to specify a network to
-calculate a subnet: if the IPv4 object is a host IPv4, the method will
-calculate the network number for that network and then subnet it. For
-example:
+As you can see, an Array has been created, containing 4 new IPv4 objects
+representing the new subnets. 
 
-  ip = IPAddress("172.16.10.58/24")
- 
-  ip.subnet(4).map{|i| i.to_string}
-    #=> ["172.16.10.0/26", "172.16.10.64/26", "172.16.10.128/26",
-         "172.16.10.192/26"]
+Another way to create subnets is to tell IPAddress how many subnets you'd 
+like to have, and letting the library calculate the new prefix for you.
+
+Let's see how it works, using IPv4#split method. Say you want 4 new subnets:
+
+  network = IPAddress("172.16.10.0/24")
+
+  subnets = network.split(4)
 
-Usually, subnetting implies dividing a network to a number of subnets
-which is a power of two: in this way, you can be sure that the network
-will be divided evenly, and all the subnets will have the same number
-of hosts. 
+  subnets.map{|i| i.to_string}
+    #=> ["172.16.10.0/26", 
+         "172.16.10.64/26", 
+         "172.16.10.128/26", 
+         "172.16.10.192/26"]
 
-==== Uneven subnetting
+Hey, that's the same result as before! This actually makes sense, as the
+two operations are complementary. When you use IPv4#subnet with the new
+prefix, IPAddress will always create a number of subnets that is a power 
+of two. This is equivalent to use IPv4#split with a power of 2.
 
-IPAddress also handles un-even subnetting: if you specify any number
-(up to the prefix limit), the network will be divided so that the
-first power-of-two networks will be even, and all the rest will just
-fill out the space. 
+Where IPv4#split really shines is with the so called "uneven subnetting".
+You are not limited to split a network into a power-of-two numbers of
+subnets: IPAddress lets you create any number of subnets, and it will
+try to organize the new created network in the best possible way, making
+an efficent allocation of the space.
 
-As an example, let's divide network 172.16.10.0/24 into 3 different subnets:
+An example here is worth a thousand words. Let's use the same network
+as the previous examples:
 
   network = IPAddress("172.16.10.0/24")
 
-  network.subnet(3).map{|i| i.to_string}
+How do we split this network into 3 subnets? Very easy:
+
+  subnets = network.split(3)
+
+  subnets.map{|i| i.to_string}
     #=> ["172.16.10.0/26",
          "172.16.10.64/26",
          "172.16.10.128/25"]
 
-We can go even further and divide into 11 subnets:
+As you can see, IPAddress tried to perform a good allocation by filling up
+all the address space from the original network. There is no point in splitting
+a network into 3 subnets like "172.16.10.0/26", "172.16.10.64/26" and 
+"172.16.10.128/26", as you would end up having "172.16.10.192/26" wasted (plus,
+I suppose I wouldn't need a Ruby library to perform un-efficient IP 
+allocation, as I do that myself very well ;) ).
 
-  network = IPAddress("172.16.10.0/24")
+We can go even further and split into 11 subnets:
 
-  network.subnet(11).map{|i| i.to_string}
+  network.split(11)
     #=> ["172.16.10.0/28", "172.16.10.16/28", "172.16.10.32/28",
          "172.16.10.48/28", "172.16.10.64/28", "172.16.10.80/28",
          "172.16.10.96/28", "172.16.10.112/28", "172.16.10.128/27",
          "172.16.10.160/27", "172.16.10.192/26"]
-	 
+
 As you can see, most of the networks are /28, with a few /27 and one
 /26 to fill up the remaining space.
 
@@ -572,7 +573,7 @@ eight groups of four hexadecimal digits, each group representing 16
 bits or two octet. For example, the following is a valid IPv6
 address: 
 
-  1080:0000:0000:0000:0008:0800:200c:417a
+  2001:0db8:0000:0000:0008:0800:200c:417a
 
 Letters in an IPv6 address are usually written downcase, as per
 RFC. You can create a new IPv6 object using uppercase letters, but
@@ -592,7 +593,7 @@ simplifications and compressions that you can use to shorten them.
 Using compression, the IPv6 address written above can be shorten into
 the following, equivalent, address
 
-  1080::8:800:200c:417a
+  2001:db8::8:800:200c:417a
 
 This short version is often used in human representation.
 
@@ -601,7 +602,7 @@ This short version is often used in human representation.
 As we used to do with IPv4 addresses, an IPv6 address can be written
 using the prefix notation to specify the subnet mask:
 
-  1080::8:800:200c:417a/64
+  2001:db8::8:800:200c:417a/64
 
 The /64 part means that the first 64 bits of the address are
 representing the network portion, and the last 64 bits are the host
@@ -612,11 +613,11 @@ portion.
 All the IPv6 representations we've just seen are perfectly fine when
 you want to create a new IPv6 address:
 
-  ip6 = IPAddress "1080:0000:0000:0000:0008:0800:200C:417A"
+  ip6 = IPAddress "2001:0db8:0000:0000:0008:0800:200C:417A"
   
-  ip6 = IPAddress "1080:0:0:0:8:800:200C:417A"
+  ip6 = IPAddress "2001:db8:0:0:8:800:200C:417A"
  
-  ip6 = IPAddress "1080::8:800:200C:417A"
+  ip6 = IPAddress "2001:db8:8:800:200C:417A"
 
 All three are giving out the same IPv6 object. The default subnet mask
 for an IPv6 is 128, as IPv6 addresses don't have classes like IPv4
@@ -744,13 +745,13 @@ like in the following example:
 A new IPv6 address can also be created from an unsigned 128 bits
 integer:
 
-  u128 = 21932261930451111902915077091070067066
+  u128 = 42540766411282592856906245548098208122
 
   ip6 = IPAddress::IPv6::parse_u128 u128
   ip6.prefix = 64
 
   ip6.to_string
-    #=> "1080::8:800:200c:417a/64"
+    #=>"2001:db8::8:800:200c:417a/64"	
 
 Finally, a new IPv6 address can be created from an hex string:
 
@@ -909,6 +910,30 @@ group will be automatically added at the beginning
  
 making it a mapped IPv6 compatible address.
 
+== Why not using IPAddr?
+
+IPAddr is the IP addresses library that comes with Ruby standard
+lib. We found this library, although very well written, not very
+suitable for all our needs, and not very flexible. 
+
+Some quick examples of things you can't do with IPAddr:
+
+* store both the address and the prefix information
+* quickly find the broadcast address of a network
+* iterate over hosts 
+* perform subnetting or network aggregation
+
+Many methods and procedures are so old that they have been 
+declared deprecated by the IETF, and some others have bugs in their 
+implementation.  
+
+Moreover, IPAddress is more robust and is already around 50% faster than IPAddr,
+in addition to provide an organic API with logical separation and OO structure.
+
+We hope that IPAddress will address all these issues and meet all your
+needs in network programming.
+
+
 == Community
 
 Want to join the community? 
@@ -924,12 +949,13 @@ Feel free to join us and tell us what you think!
 Thanks to Luca Russo (vargolo) and Simone Carletti 
 (weppos) for all the support and technical review. Thanks to Marco Beri, 
 Bryan T. Richardson, Nicolas Fevrier, jdpace, Daniele Alessandri, jrdioko, 
-Ghislain Charrier, Pawel Krzesniak, Mark Sullivan, Erik Ahlström and 
-Steve Rawlinson for their support, feedback and bug reports.
+Ghislain Charrier, Pawel Krzesniak, Mark Sullivan, Leif Gensert, 
+Erik Ahlström, Peter Vandenberk and Steve Rawlinson for their support, 
+feedback and bug reports.
   
 == Copyright
 
 Copyright (c) 2009-2011 Marco Ceresa. See LICENSE for details.
 
 
- 
+ 

data/VERSION

@@ -1 +1 @@
-0.7.5
+0.8.0

data/ipaddress.gemspec

@@ -0,0 +1,55 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ipaddress}
+  s.version = "0.8.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Marco Ceresa"]
+  s.date = %q{2011-05-17}
+  s.description = %q{      IPAddress is a Ruby library designed to make manipulation 
+      of IPv4 and IPv6 addresses both powerful and simple. It mantains
+      a layer of compatibility with Ruby's own IPAddr, while 
+      addressing many of its issues.
+}
+  s.email = %q{ceresa@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    "CHANGELOG.rdoc",
+    "LICENSE",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "ipaddress.gemspec",
+    "lib/ipaddress.rb",
+    "lib/ipaddress/ipv4.rb",
+    "lib/ipaddress/ipv6.rb",
+    "lib/ipaddress/prefix.rb",
+    "test/ipaddress/ipv4_test.rb",
+    "test/ipaddress/ipv6_test.rb",
+    "test/ipaddress/prefix_test.rb",
+    "test/ipaddress_test.rb",
+    "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/bluemonk/ipaddress}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{IPv4/IPv6 addresses manipulation library}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/lib/ipaddress.rb

@@ -14,8 +14,6 @@
 
 require 'ipaddress/ipv4'
 require 'ipaddress/ipv6'
-require 'ipaddress/extensions/extensions'
-
 
 module IPAddress
 
@@ -145,6 +143,9 @@ module IPAddress
     false
   end
 
+  # 
+  # Deprecate method
+  #
   def self.deprecate(message = nil) # :nodoc:
     message ||= "You are using deprecated behavior which will be removed from the next major or minor release."
     warn("DEPRECATION WARNING: #{message}")
@@ -185,4 +186,17 @@ def IPAddress(str)
   IPAddress::parse str
 end
 
+#
+# Compatibility with Ruby 1.8
+#
+if RUBY_VERSION =~ /1\.8/
+  class Hash # :nodoc:
+    alias :key :index
+  end
+  module Math # :nodoc:
+    def Math.log2(n) 
+      log(n) / log(2) 
+    end
+  end
+end
 

data/lib/ipaddress/ipv4.rb

@@ -426,14 +426,22 @@ module IPAddress;
     end
 
     #
-    # Spaceship operator to compare IP addresses
+    # Spaceship operator to compare IPv4 objects
     #
-    # An IP address is considered to be minor if it 
-    # has a greater prefix (thus smaller hosts
-    # portion) and a smaller u32 value.
+    # Comparing IPv4 addresses is useful to ordinate
+    # them into lists that match our intuitive 
+    # perception of ordered IP addresses.
+    # 
+    # The first comparison criteria is the u32 value.
+    # For example, 10.100.100.1 will be considered 
+    # to be less than 172.16.0.1, because, in a ordered list,
+    # we expect 10.100.100.1 to come before 172.16.0.1.
     #
-    # For example, "10.100.100.1/8" is smaller than
-    # "172.16.0.1/16", but it's bigger than "10.100.100.1/16".
+    # The second criteria, in case two IPv4 objects 
+    # have identical addresses, is the prefix. An higher
+    # prefix will be considered greater than a lower
+    # prefix. This is because we expect to see
+    # 10.100.100.0/24 come before 10.100.100.0/25.
     #
     # Example:
     #
@@ -443,22 +451,15 @@ module IPAddress;
     #
     #   ip1 < ip2
     #     #=> true
-    #   ip1 < ip3
+    #   ip1 > ip3
     #     #=> false
     #
+    #   [ip1,ip2,ip3].sort.map{|i| i.to_string}
+    #     #=> ["10.100.100.1/8","10.100.100.1/16","172.16.0.1/16"]
+    #
     def <=>(oth)
-      if to_u32 > oth.to_u32
-        return 1
-      elsif to_u32 < oth.to_u32
-        return -1
-      else
-        if prefix < oth.prefix
-          return 1
-        elsif prefix > oth.prefix
-          return -1
-        end
-      end
-      return 0
+      return prefix <=> oth.prefix if to_u32 == oth.to_u32  
+      to_u32 <=> oth.to_u32
     end
     
     #
@@ -552,30 +553,6 @@ module IPAddress;
       others.all? {|oth| include?(oth)}
     end
     
-    #
-    # True if the object is an IPv4 address
-    #
-    #   ip = IPAddress("192.168.10.100/24")
-    #
-    #   ip.ipv4?
-    #     #-> true
-    #
-#    def ipv4?
-#      true
-#    end
-
-    #
-    # True if the object is an IPv6 address
-    #
-    #   ip = IPAddress("192.168.10.100/24")
-    #
-    #   ip.ipv6?
-    #     #-> false
-    #
-#    def ipv6?
-#      false
-#    end
-
     #
     # Checks if an IPv4 address objects belongs
     # to a private network RFC1918
@@ -607,10 +584,10 @@ module IPAddress;
     alias_method :arpa, :reverse
     
     #
-    # Subnetting a network
+    # Splits a network into different subnets
     #
     # If the IP Address is a network, it can be divided into
-    # multiple networks. If +self+ is not a network, the
+    # multiple networks. If +self+ is not a network, this
     # method will calculate the network from the IP and then
     # subnet it.
     #
@@ -636,15 +613,19 @@ module IPAddress;
     #          "172.16.10.64/26",
     #          "172.16.10.128/25"]
     #
-    # Returns an array of IPAddress objects
+    # Returns an array of IPv4 objects
     #
-    def subnet(subnets=2)
+    def split(subnets=2)
       unless (1..(2**@prefix.host_prefix)).include? subnets
         raise ArgumentError, "Value #{subnets} out of range" 
       end
-      calculate_subnets(subnets)
+      networks = subnet(newprefix(subnets))
+      until networks.size == subnets
+        networks = sum_first_found(networks)
+      end
+      return networks
     end
-    alias_method :/, :subnet
+    alias_method :/, :split
 
     #
     # Returns a new IPv4 object from the supernetting
@@ -667,11 +648,44 @@ module IPAddress;
     #
     #   ip.supernet(22).to_string
     #     #=> "172.16.8.0/22"
-    # 
+    #
+    # If +new_prefix+ is less than 1, returns 0.0.0.0/0
+    #
     def supernet(new_prefix)
-      raise ArgumentError, "Can't supernet a /1 network" if new_prefix < 1
       raise ArgumentError, "New prefix must be smaller than existing prefix" if new_prefix >= @prefix.to_i
-      self.class.new(@address+"/#{new_prefix}").network
+      return self.class.new("0.0.0.0/0") if new_prefix < 1
+      return self.class.new(@address+"/#{new_prefix}").network
+    end
+
+    #
+    # This method implements the subnetting function 
+    # similar to the one described in RFC3531.
+    #
+    # By specifying a new prefix, the method calculates
+    # the network number for the given IPv4 object
+    # and calculates the subnets associated to the new
+    # prefix.
+    #
+    # For example, given the following network:
+    #
+    #   ip = IPAddress "172.16.10.0/24"
+    #
+    # we can calculate the subnets with a /26 prefix
+    #
+    #   ip.subnets(26).map{&:to_string)
+    #     #=> ["172.16.10.0/26", "172.16.10.64/26", 
+    #          "172.16.10.128/26", "172.16.10.192/26"]
+    #
+    # The resulting number of subnets will of course always be
+    # a power of two.
+    #
+    def subnet(subprefix)
+      unless ((@prefix.to_i)..32).include? subprefix
+        raise ArgumentError, "New prefix must be between #@prefix and 32"
+      end
+      Array.new(2**(subprefix-@prefix.to_i)) do |i|
+        self.class.parse_u32(network_u32+(i*(2**(32-subprefix))), subprefix)
+      end
     end
 
     #
@@ -928,9 +942,6 @@ module IPAddress;
     # * Class B, from 128.0.0.0 to 191.255.255.255
     # * Class C, D and E, from 192.0.0.0 to 255.255.255.254
     #
-    # Note that classes C, D and E will all have a default
-    # prefix of /24 or 255.255.255.0
-    #
     # Example:
     #
     #   ip = IPAddress::IPv4.parse_classful "10.0.0.1"
@@ -940,6 +951,9 @@ module IPAddress;
     #   ip.a?
     #     #=> true
     #
+    # Note that classes C, D and E will all have a default
+    # prefix of /24 or 255.255.255.0
+    #
     def self.parse_classful(ip)
       if IPAddress.valid_ipv4?(ip)
         address = ip.strip
@@ -954,25 +968,19 @@ module IPAddress;
     # private methods
     #
     private
-    
-    def calculate_subnets(subnets)
-      po2 = subnets.closest_power_of_2
-      new_prefix = @prefix + Math::log2(po2).to_i
-      networks = Array.new
-      (0..po2-1).each do |i|
-        mul = i * (2**(32-new_prefix))
-        networks << IPAddress::IPv4.parse_u32(network_u32+mul, new_prefix)
-      end
-      until networks.size == subnets
-        networks = sum_first_found(networks)
+
+    def newprefix(num)
+      num.upto(32) do |i|
+        if (a = Math::log2(i).to_i) == Math::log2(i)
+          return @prefix + a 
+        end
       end
-      return networks
     end
     
     def sum_first_found(arr)
       dup = arr.dup.reverse
       dup.each_with_index do |obj,i|
-        a = [IPAddress::IPv4.summarize(obj,dup[i+1])].flatten
+        a = [self.class.summarize(obj,dup[i+1])].flatten
         if a.size == 1
           dup[i..i+1] = a
           return dup.reverse