netaddr 1.2.0 → 1.3.0

data/lib/ip_math.rb

@@ -4,6 +4,24 @@ private
 
 # IP MATH METHODS
 
+#==============================================================================#
+# binary_mirror()
+#==============================================================================#
+
+# given an integer and number of bits to consider, return its binary mirror
+#
+def binary_mirror(num, bit_count)
+    mirror = 0
+    bit_count.times do # make mirror image of num by capturning lsb and left-shifting it onto mirror
+        mirror = mirror << 1
+        lsb = num & 1
+        num = num >> 1
+        mirror = mirror | lsb
+    end
+    return(mirror)
+end
+module_function :binary_mirror
+
 #==============================================================================#
 # bits_to_mask()
 #==============================================================================#
@@ -71,15 +89,15 @@ module_function :ip_count_to_size
 
 # unpack an int into an ip address string
 #
-def ip_int_to_str(packed_ip, version, ipv4_mapped=nil)
+def ip_int_to_str(ip_int, version, ipv4_mapped=nil)
     ip = nil
-    version = 4 if (!version && packed_ip < 2**32)
+    version = 4 if (!version && ip_int < 2**32)
     if (version == 4)
         octets = []
         4.times do
-            octet = packed_ip & 0xFF
+            octet = ip_int & 0xFF
             octets.unshift(octet.to_s)
-            packed_ip = packed_ip >> 8
+            ip_int = ip_int >> 8
         end
         ip = octets.join('.')
     else
@@ -88,16 +106,16 @@ def ip_int_to_str(packed_ip, version, ipv4_mapped=nil)
             loop_count = 8
         else
             loop_count = 6
-            packed_v4 = packed_ip & 0xffffffff
-            ipv4_addr = ip_int_to_str(packed_v4, 4)
+            ipv4_int = ip_int & 0xffffffff
+            ipv4_addr = ip_int_to_str(ipv4_int, 4)
             fields.unshift(ipv4_addr)
-            packed_ip = packed_ip >> 32
+            ip_int = ip_int >> 32
         end
 
         loop_count.times do 
-            octet = packed_ip & 0xFFFF
+            octet = ip_int & 0xFFFF
             octet = octet.to_s(16)
-            packed_ip = packed_ip >> 16
+            ip_int = ip_int >> 16
 
             # if octet < 4 characters, then pad with 0's
             (4 - octet.length).times do
@@ -118,13 +136,13 @@ module_function :ip_int_to_str
 # convert an ip string into an int
 #
 def ip_str_to_int(ip,version)
-    packed_ip = 0
+    ip_int = 0
     if ( version == 4)
         octets = ip.split('.')
         (0..3).each do |x|
             octet = octets.pop.to_i
             octet = octet << 8*x
-            packed_ip = packed_ip | octet
+            ip_int = ip_int | octet
         end
 
     else
@@ -157,12 +175,12 @@ def ip_str_to_int(ip,version)
 
         if (dotted_dec)
             ipv4_addr = fields.pop
-            packed_v4 = NetAddr.pack_ip_addr(ipv4_addr, :Version => 4)
+            ipv4_int = NetAddr.ip_to_i(ipv4_addr, :Version => 4)
             octets = []
             2.times do
-                octet = packed_v4 & 0xFFFF
+                octet = ipv4_int & 0xFFFF
                 octets.unshift(octet.to_s(16))
-                packed_v4 = packed_v4 >> 16
+                ipv4_int = ipv4_int >> 16
             end
             fields.concat(octets)
         end
@@ -171,11 +189,11 @@ def ip_str_to_int(ip,version)
         (0..7).each do |x|
             field = fields.pop.to_i(16)
             field = field << 16*x
-            packed_ip = packed_ip | field
+            ip_int = ip_int | field
         end
 
    end
-    return(packed_ip)
+    return(ip_int)
 end
 module_function :ip_str_to_int
 
@@ -185,23 +203,23 @@ module_function :ip_str_to_int
 
 # convert integer into a cidr formatted netmask (bits)
 #
-def mask_to_bits(packed_netmask)
-    return(packed_netmask) if (packed_netmask == 0)
+def mask_to_bits(netmask_int)
+    return(netmask_int) if (netmask_int == 0)
 
     mask = nil
-    if (packed_netmask < 2**32)
+    if (netmask_int < 2**32)
         mask = 32
-        validate_netmask_int(packed_netmask, 4, true)
+        validate_netmask_int(netmask_int, 4, true)
     else
         mask = 128
-        validate_netmask_int(packed_netmask, 6, true)
+        validate_netmask_int(netmask_int, 6, true)
     end
 
     mask.times do
-        if ( (packed_netmask & 1) == 1)
+        if ( (netmask_int & 1) == 1)
             break
         end
-        packed_netmask = packed_netmask >> 1
+        netmask_int = netmask_int >> 1
         mask = mask - 1
     end
     return(mask)
@@ -215,11 +233,11 @@ module_function :mask_to_bits
 # convert string into integer mask
 #
 def netmask_str_to_int(netmask,version)
-    packed_netmask = nil
+    netmask_int = nil
     all_f = 2**32-1
     all_f = 2**128-1 if (version == 6)
     if(netmask =~ /\./)
-        packed_netmask = NetAddr.pack_ip_addr(netmask)
+        netmask_int = NetAddr.ip_to_i(netmask)
     else
         # remove '/' if present
         if (netmask =~ /^\// )
@@ -227,9 +245,9 @@ def netmask_str_to_int(netmask,version)
             netmask.lstrip!
         end
         netmask = netmask.to_i
-        packed_netmask = all_f ^ (all_f >> netmask)
+        netmask_int = all_f ^ (all_f >> netmask)
     end
-    return(packed_netmask)
+    return(netmask_int)
 end
 module_function :netmask_str_to_int
 

data/lib/methods.rb

@@ -1,11 +1,146 @@
 =begin rdoc
- Copyleft (c) 2006 Dustin Spinhirne (www.spinhirne.com)
+ Copyleft (c) 2006 Dustin Spinhirne
 
  Licensed under the same terms as Ruby, No Warranty is provided.
 =end
 
 module NetAddr
 
+#==============================================================================#
+# i_to_bits()
+#==============================================================================#
+
+#===Synopsis
+#Convert an Integer representing a binary netmask into an Integer representing
+#the number of bits in that netmask.
+#
+# Example:
+# NetAddr.i_to_bits(0xfffffffe) => 31
+# NetAddr.i_to_bits(0xffffffffffffffff0000000000000000) => 64
+#
+#===Arguments:
+#* netmask_int = Integer representing a binary netmask
+#
+#===Returns:
+#* Integer
+#
+def i_to_bits(netmask_int)
+
+    # validate netmask_int
+    raise ArgumentError, "Integer expected for argument 'netmask_int', " +
+                         "but #{netmask_int.class} provided." if (!netmask_int.kind_of?(Integer))    
+
+
+    return( mask_to_bits(netmask_int) )
+end
+module_function :i_to_bits
+
+#==============================================================================#
+# i_to_ip()
+#==============================================================================#
+
+#===Synopsis
+#Convert an Integer into an IP address. This method will attempt to auto-detect the IP version
+#if not provided, however, a slight speed increase is realized if version is provided.
+#
+# Example:
+# NetAddr.i_to_ip(3232235906) => "192.168.1.130"
+# NetAddr.i_to_ip(0xffff0000000000000000000000000001, :Version => 6) => "ffff:0000:0000:0000:0000:0000:0000:0001"
+#
+#===Arguments:
+#* ip_int = IP address as an Integer
+#* options = Hash with the following keys:
+#     :Version -- IP version - Integer (optional)
+#     :IPv4Mapped -- if true, unpack IPv6 as an IPv4 mapped address (optional)
+#
+#===Returns:
+#* String
+#
+def i_to_ip(ip_int, options=nil)
+    known_args = [:Version, :IPv4Mapped]
+    ipv4_mapped = false
+    version = nil
+
+    # validate options
+    if (options)
+        raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash))
+        NetAddr.validate_args(options.keys,known_args)
+
+        if (options.has_key?(:Version))
+            version = options[:Version]
+            if (version != 4 && version != 6)
+                raise VersionError, ":Version should be 4 or 6, but was '#{version}'."
+            end
+        end
+
+        if (options.has_key?(:IPv4Mapped) && options[:IPv4Mapped] == true)
+            ipv4_mapped = true
+        end
+    end
+
+    # validate & unpack
+    raise ArgumentError, "Integer expected for argument 'ip_int', " +
+                         "but #{ip_int.class} provided." if (!ip_int.kind_of?(Integer))
+    version = validate_ip_int(ip_int, version)
+    ip = ip_int_to_str(ip_int, version, ipv4_mapped)
+
+    return(ip)
+end
+module_function :i_to_ip
+
+#==============================================================================#
+# ip_to_i()
+#==============================================================================#
+
+#===Synopsis
+#Convert IP addresses into an Integer. This method will attempt to auto-detect the IP version
+#if not provided, however a slight speed increase is realized if version is provided.
+#
+# Example:
+# NetAddr.ip_to_i('192.168.1.1') => 3232235777
+# NetAddr.ip_to_i('ffff::1', :Version => 6) => 340277174624079928635746076935438991361
+# NetAddr.ip_to_i('::192.168.1.1') => 3232235777
+#
+#===Arguments:
+#* ip = IP address as a String
+#* options = Hash with the following keys:
+#     :Version -- IP version - Integer
+#
+#===Returns:
+#* Integer
+#
+def ip_to_i(ip, options=nil)
+    known_args = [:Version]
+    to_validate = {}
+    version = nil
+
+    # validate options
+    if (options)
+        raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash))
+        validate_args(options.keys,known_args)
+
+        if (options.has_key?(:Version))
+            version = options[:Version]
+            to_validate[:Version] = version
+            if (version != 4 && version != 6)
+                raise  VersionError, ":Version should be 4 or 6, but was '#{version}'."
+            end
+        end
+    end
+
+    if ( ip.kind_of?(String) )
+        version = detect_ip_version(ip) if (!version)
+        validate_ip_str(ip,version)
+        ip_int = ip_str_to_int(ip,version)
+
+    else
+        raise ArgumentError, "String expected for argument 'ip' but #{ip.class} provided."
+    end
+
+    return(ip_int)
+end
+module_function :ip_to_i
+
 #==============================================================================#
 # merge()
 #==============================================================================#
@@ -127,8 +262,8 @@ module_function :merge
 #netmask (bits by default) required for that subnet. IP version is assumed to be 4 unless specified otherwise.
 #
 # Example:
-# NetAddr.minumum_size(14)
-# NetAddr.minumum_size(65536, :Version => 6)
+# NetAddr.minimum_size(14) => 28
+# NetAddr.minimum_size(65536, :Version => 6) => 112
 #
 #===Arguments:
 #* ipcount = IP count as an Integer
@@ -167,74 +302,21 @@ end
 module_function :minimum_size
 
 #==============================================================================#
-# pack_ip_addr()
-#==============================================================================#
-
-#===Synopsis
-#Convert IP addresses into an Integer. This method will attempt to auto-detect the IP version
-#if not provided, however a slight speed increase is realized if version is provided.
-#
-# Example:
-# pack_ip_addr('192.168.1.1')
-# pack_ip_addr(ffff::1', :Version => 6)
-# pack_ip_addr(::192.168.1.1')
-#
-#===Arguments:
-#* ip = IP address as a String
-#* options = Hash with the following keys:
-#     :Version -- IP version - Integer
-#
-#===Returns:
-#* Integer
-#
-def pack_ip_addr(ip, options=nil)
-    known_args = [:Version]
-    to_validate = {}
-    version = nil
-
-    # validate options
-    if (options)
-        raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash))
-        validate_args(options.keys,known_args)
-
-        if (options.has_key?(:Version))
-            version = options[:Version]
-            to_validate[:Version] = version
-            if (version != 4 && version != 6)
-                raise  VersionError, ":Version should be 4 or 6, but was '#{version}'."
-            end
-        end
-    end
-
-    if ( ip.kind_of?(String) )
-        version = detect_ip_version(ip) if (!version)
-        validate_ip_str(ip,version)
-        packed_ip = ip_str_to_int(ip,version)
-
-    else
-        raise ArgumentError, "String expected for argument 'ip' but #{ip.class} provided."
-    end
-
-    return(packed_ip)
-end
-module_function :pack_ip_addr
-
-#==============================================================================#
-# pack_ip_netmask()
+# netmask_to_i()
 #==============================================================================#
 
 #===Synopsis
 #Convert IP netmask into an Integer. Netmask may be in either CIDR (/yy) or
 #extended (y.y.y.y) format. CIDR formatted netmasks may either
-#be a String or an Integer. IP version defaults to 4. It may be necessary 
+#be a String or an Integer. IP version defaults to 4. It may be necessary
 #to specify the version if an IPv6 netmask of /32 or smaller is provided.
 #
 # Example:
-# NetAddr.pack_ip_netmask('255.255.255.0')
-# NetAddr.pack_ip_netmask('24')
-# NetAddr.pack_ip_netmask(24)
-# NetAddr.pack_ip_netmask('/24')
-# NetAddr.pack_ip_netmask('32', :Version => 6)
+# NetAddr.netmask_to_i('255.255.255.0') => 4294967040
+# NetAddr.netmask_to_i('24') => 4294967040
+# NetAddr.netmask_to_i(24) => 4294967040
+# NetAddr.netmask_to_i('/24') => 4294967040
+# NetAddr.netmask_to_i('32', :Version => 6) => 340282366841710300949110269838224261120
 #
 #===Arguments
 #* netmask = Netmask as a String or Integer
@@ -244,10 +326,10 @@ module_function :pack_ip_addr
 #===Returns:
 #* Integer
 #
-def pack_ip_netmask(netmask, options=nil)
+def netmask_to_i(netmask, options=nil)
     known_args = [:Version]
     version = 4
-    packed_netmask = nil
+    netmask_int = nil
 
     # validate options
     if (options)
@@ -264,20 +346,20 @@ def pack_ip_netmask(netmask, options=nil)
 
     if (netmask.kind_of?(String))
         validate_netmask_str(netmask, version)
-        packed_netmask = netmask_str_to_int(netmask,version)
+        netmask_int = netmask_str_to_int(netmask,version)
 
     elsif (netmask.kind_of?(Integer))
         validate_netmask_int(netmask, version, true)
-        packed_netmask = bits_to_mask(netmask,version)
+        netmask_int = bits_to_mask(netmask,version)
 
     else
         raise ArgumentError, "String or Integer expected for argument 'netmask', " +
-                             "but #{netmask.class} provided." if (!netmask.kind_of?(Integer) && !netmask.kind_of?(String))    
+                             "but #{netmask.class} provided." if (!netmask.kind_of?(Integer) && !netmask.kind_of?(String))
     end
 
-    return(packed_netmask)
+    return(netmask_int)
 end
-module_function :pack_ip_netmask
+module_function :netmask_to_i
 
 #==============================================================================#
 # range()
@@ -311,6 +393,15 @@ module_function :pack_ip_netmask
 #===Returns:
 #* Array of Strings or NetAddr::CIDR objects, or an Integer
 #
+#===Note:
+#If you do not need all of the fancy options in this method, then please consider
+#using the standard Ruby Range class as shown below.
+#
+# Example:
+# start = NetAddr::CIDR.create('192.168.1.0')
+# fin = NetAddr::CIDR.create('192.168.2.3')
+# (start..fin).each {|addr| puts addr.desc}
+#
 def range(lower, upper, options=nil)
     known_args = [:Bitstep, :Inclusive, :Limit, :Objectify, :Short, :Size]
     list = []
@@ -374,7 +465,7 @@ def range(lower, upper, options=nil)
     # check version, store & sort
     if (lower.version == upper.version)
         version = lower.version
-        boundaries = [lower.packed_ip, upper.packed_ip]
+        boundaries = [lower.to_i(:ip), upper.to_i(:ip)]
         boundaries.sort
     else
         raise VersionError, "Provided NetAddr::CIDR objects are of different IP versions."
@@ -422,7 +513,7 @@ module_function :range
 #The address should not contain a netmask.
 #
 # Example:
-# NetAddr.shorten('fec0:0000:0000:0000:0000:0000:0000:0001')
+# NetAddr.shorten('fec0:0000:0000:0000:0000:0000:0000:0001') => "fec0::1"
 #
 #===Arguments:
 #* addr = String
@@ -510,10 +601,9 @@ module_function :shorten
 #==============================================================================#
 
 #===Synopsis
-#Given a list of CIDR addresses or NetAddr::CIDR objects, 
+#Given a list of CIDR addresses or NetAddr::CIDR objects,
 #sort them from lowest to highest by Network/Netmask. This method will use the
-#base address passed during the initialization of any NetAddr::CIDR 
-#objects, or the base address of any CIDR addresses passed
+#base address of any NetAddr::CIDR objects or CIDR addresses provided.
 #
 # Example:
 # cidr1 = NetAddr::CIDR.create('192.168.1.32/27')
@@ -568,87 +658,6 @@ def sort(list)
 end
 module_function :sort
 
-#==============================================================================#
-# unpack_ip_addr()
-#==============================================================================#
-
-#===Synopsis
-#Unack a packed IP address back into a printable string. This method will attempt to auto-detect the IP version
-#if not provided, however a slight speed increase is realized if version is provided.
-#
-# Example:
-# NetAddr.unpack_ip_addr(3232235906)
-# NetAddr.unpack_ip_addr(packed, :Version => 6)
-#
-#===Arguments:
-#* packed_ip = Packed IP address as an Integer
-#* options = Hash with the following keys:
-#     :Version -- IP version - Integer (optional)
-#     :IPv4Mapped -- if true, unpack IPv6 as an IPv4 mapped address (optional)
-#
-#===Returns:
-#* String
-#
-def unpack_ip_addr(packed_ip, options=nil)
-    known_args = [:Version, :IPv4Mapped]
-    ipv4_mapped = false
-    version = nil
-
-    # validate options
-    if (options)
-        raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash))
-        NetAddr.validate_args(options.keys,known_args)
-
-        if (options.has_key?(:Version))
-            version = options[:Version]
-            if (version != 4 && version != 6)
-                raise VersionError, ":Version should be 4 or 6, but was '#{version}'."
-            end
-        end
-
-        if (options.has_key?(:IPv4Mapped) && options[:IPv4Mapped] == true)
-            ipv4_mapped = true
-        end
-    end
-
-    # validate & unpack
-    raise ArgumentError, "Integer expected for argument 'packed_ip', " +
-                         "but #{packed_ip.class} provided." if (!packed_ip.kind_of?(Integer))
-    version = validate_ip_int(packed_ip, version)
-    ip = ip_int_to_str(packed_ip, version, ipv4_mapped)
-
-    return(ip)
-end
-module_function :unpack_ip_addr 
-
-#==============================================================================#
-# unpack_ip_netmask()
-#==============================================================================#
-
-#===Synopsis
-#Unpack a packed IP netmask into an Integer representing the number of
-#bits in the CIDR mask.
-#
-# Example:
-# NetAddr.unpack_ip_netmask(0xfffffffe)
-#
-#===Arguments:
-#* packed_netmask = Packed netmask as an Integer
-#
-#===Returns:
-#* Integer
-#
-def unpack_ip_netmask(packed_netmask)
-
-    # validate packed_netmask
-    raise ArgumentError, "Integer expected for argument 'packed_netmask', " +
-                         "but #{packed_netmask.class} provided." if (!packed_netmask.kind_of?(Integer))    
-
-
-    return( mask_to_bits(packed_netmask) )
-end
-module_function :unpack_ip_netmask
-
 #==============================================================================#
 # unshorten()
 #==============================================================================#
@@ -658,7 +667,7 @@ module_function :unpack_ip_netmask
 #notation. The address should not contain a netmask.
 #
 # Example:
-# NetAddr.unshorten('fec0::1')
+# NetAddr.unshorten('fec0::1') => "fec0:0000:0000:0000:0000:0000:0000:0001"
 #
 #===Arguments:
 #* ip = CIDR address as a String
@@ -676,11 +685,11 @@ def unshorten(ip)
     validate_ip_str(ip, 6)
     ipv4_mapped = true if (ip =~ /\./)
 
-    packed = pack_ip_addr(ip, :Version => 6)
+    ip_int = ip_to_i(ip, :Version => 6)
     if (!ipv4_mapped)
-        long = ip_int_to_str(packed, 6)
+        long = ip_int_to_str(ip_int, 6)
     else
-        long = ip_int_to_str(packed, 6, true)
+        long = ip_int_to_str(ip_int, 6, true)
     end
 
     return(long)
@@ -695,7 +704,7 @@ module_function :unshorten
 #Validate an EUI-48 or EUI-64 address. Raises NetAddr::ValidationError on validation failure.
 #
 # Example:
-# NetAddr.validate_eui('01-00-5e-12-34-56')
+# NetAddr.validate_eui('01-00-5e-12-34-56') => true
 #
 # - Arguments
 #* eui = EUI address as a String
@@ -751,12 +760,12 @@ module_function :validate_eui
 #Raises NetAddr::ValidationError on validation failure.
 #
 # Example:
-# NetAddr.validate_ip_addr('192.168.1.1')
-# NetAddr.validate_ip_addr('ffff::1', :Version => 6)
-# NetAddr.validate_ip_addr('::192.168.1.1')
-# NetAddr.validate_ip_addr(0xFFFFFF)
-# NetAddr.validate_ip_addr(2**128-1)
-# NetAddr.validate_ip_addr(2**32-1, :Version => 4)
+# NetAddr.validate_ip_addr('192.168.1.1') => true
+# NetAddr.validate_ip_addr('ffff::1', :Version => 6) => true
+# NetAddr.validate_ip_addr('::192.168.1.1') => true
+# NetAddr.validate_ip_addr(0xFFFFFF) => true
+# NetAddr.validate_ip_addr(2**128-1) => true
+# NetAddr.validate_ip_addr(2**32-1, :Version => 4) => true
 #
 #===Arguments
 #* ip = IP address as a String or Integer
@@ -804,26 +813,26 @@ module_function :validate_ip_addr
 #==============================================================================#
 
 #===Synopsis
-#Validate IP Netmask.Version defaults to 4 if not specified. 
+#Validate IP Netmask. Version defaults to 4 if not specified.
 #Raises NetAddr::ValidationError on validation failure.
 #
 # Examples:
-# NetAddr.validate_ip_netmask('/32')
-# NetAddr.validate_ip_netmask(32)
-# NetAddr.validate_ip_netmask(0xffffffff, :Packed => true)
+# NetAddr.validate_ip_netmask('/32') => true
+# NetAddr.validate_ip_netmask(32) => true
+# NetAddr.validate_ip_netmask(0xffffffff, :Integer => true) => true
 #
 #===Arguments:
 #* netmask = Netmask as a String or Integer
 #* options = Hash with the following keys:
-#     :Packed -- if true, the provided Netmask is a packed Integer
+#     :Integer -- if true, the provided Netmask is an Integer mask
 #     :Version -- IP version - Integer (optional)
 #
 #===Returns:
 #* True
 #
 def validate_ip_netmask(netmask, options=nil)
-    known_args = [:Packed, :Version]
-    packed = false
+    known_args = [:Integer, :Version]
+    is_integer = false
     version = 4
 
     # validate options
@@ -831,8 +840,8 @@ def validate_ip_netmask(netmask, options=nil)
         raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash))
         NetAddr.validate_args(options.keys,known_args)
 
-        if (options.has_key?(:Packed) && options[:Packed] == true)
-            packed = true
+        if (options.has_key?(:Integer) && options[:Integer] == true)
+            is_integer = true
         end
 
         if (options.has_key?(:Version))
@@ -847,7 +856,7 @@ def validate_ip_netmask(netmask, options=nil)
     if (netmask.kind_of?(String))
         validate_netmask_str(netmask,version)
     elsif (netmask.kind_of?(Integer) )
-        validate_netmask_int(netmask,version,packed)
+        validate_netmask_int(netmask,version,is_integer)
     else
         raise ArgumentError, "Integer or String expected for argument 'netmask' but " +
                              "#{netmask.class} provided." if (!netmask.kind_of?(String) && !netmask.kind_of?(Integer))
@@ -877,7 +886,7 @@ module_function :validate_ip_netmask
 #* ip = Wildcard IP address as a String
 #
 #===Returns:
-#* CIDR object 
+#* CIDR object
 #
 def wildcard(ip)
     version = 4