ipaddress 0.5.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,7 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+server.rb
+ipaddr.html

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Marco Ceresa
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,866 @@
+= IPAddress
+
+IPAddress is a Ruby library designed to make the use of IPv4 and IPv6
+addresses easy, powerful and enjoyable. It provides a complete set of
+methods to handle IP addresses for any need, from simple scripting to
+full network design.
+
+IPAddress is written with a full OO interface, and its code is easy to
+read, maintain and extend. The documentation is full of examples, to
+let you start being productive immediately.
+
+This document provides a brief introduction to the library and
+examples of typical usage. 
+
+=== 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
+
+We hope that IPAddress will address all these issues and meet all your
+needs in network programming.
+
+= Installation
+
+Install the library using rubygems
+
+  $ gem install ipaddress
+
+You can then use it in your programs:
+  
+  require 'rubygems'  # optional
+  require 'ipaddress'
+
+Another way would be to clone the git repository
+
+  $ git clone git://github.com/bluemonk/net-dns.git
+
+And then install the library
+ 
+  $ cd ipaddress
+  ipaddress$ rake install
+
+= Documentation
+
+The code is fully documented with RDoc. You can generate the
+documentation with Rake:
+
+  ipaddress$ rake rdoc
+
+The latest documentation can be found online at the following address
+
+http://marcoceresa.com/ipaddress
+
+= Usage
+
+In this section I will illustrate how to use the IPAddress library
+through some examples of common tasks.
+
+== IPv4
+
+Class IPAddress::IPv4 is used to handle IPv4 type addresses. IPAddress
+is similar to other IP Addresses libraries, like Ruby's own
+IPAddr. However it works slightly different, as we will see.
+
+=== Create a new IPv4 address
+
+The usual way to express an IP Address is using its dotted decimal
+form, such as 172.16.10.1, and a prefix, such as 24, separated by a
+slash. 
+
+  172.16.10.1/24
+
+To create a new IPv4 object, you can use IPv4 own class
+
+  ip = IPAddress::IPv4.new "172.16.10.1/24"
+
+or, in a easier way, using the IPAddress wrapper method
+
+  ip = IPAddress "172.16.10.1/24"
+
+You can specify an IPv4 address in any of two ways:
+
+  IPAddress "172.16.10.1/24"
+  IPAddress "172.16.10.1/255.255.255.0"
+  
+In this example, prefix /24 and netmask 255.255.255.0 are the same and
+you have the flexibility to use either one of them.
+
+=== Classful networks
+
+If you don't specify a prefix (or a subnet mask), then the library
+will create an object base on the CLASSFUL network from the given
+IP. Remember the CLASSFUL network are the following (RFC 791)
+
+* Class A, from 0.0.0.0 to 127.255.255.255
+* Class B, from 128.0.0.0 to 191.255.255.255
+* Class C, from 192.0.0.0 to 255.255.255.255
+
+Since classful networks here are only considered to calculate the default
+prefix number, classes D and E are not considered. 
+
+You can easily check which CLASSFUL network the IP belongs:
+
+  ip = IPAddress("10.0.0.1/24")
+  ip.a?
+    #=> true
+  
+  ip = IPAddress("172.16.10.1/24")
+  ip.b?
+    #=> true
+  
+  ip = IPAddress("192.168.1.1/30")
+  ip.c?
+    #=> true
+
+These methods are only checking the address portion of an IP, and are
+indipendent from its prefix.
+
+For more information on CLASSFUL networks visit the following
+Wikipedia page: http://en.wikipedia.org/wiki/Classful_network
+
+=== Handling the IPv4 address
+
+Once created, you can obtain the attributes for an IPv4 object:
+
+  ip = IPAddress("172.16.10.1/24")
+
+  ip.address
+    #=> "172.16.10.1"
+  ip.prefix
+    #=> 24
+
+In case you need to retrieve the netmask in IPv4 format, you can use
+the IPv4#netmask method:
+
+  ip.netmask
+    #=> "255.255.255.0"
+
+A special attribute, IPv4#octets, is available to get the four 
+decimal octets from the IP address:
+
+  ip.octets
+    #=> [172,16,10,1]
+
+Shortcut method IPv4#[], provides access to a given octet whithin the
+range:
+
+  ip[1]
+    #=> 16
+
+If you need to print out the IPv4 address in a canonical form, you can
+use IPv4#to_s
+
+  ip.to_s
+    #=> "172.16.10.l/24"
+
+=== Changing netmask
+    
+You can set a new prefix (netmask) after creating an IPv4 
+object. For example:
+
+  ip.prefix = 25
+  ip.to_s
+    #=> "172.16.10.l/25"
+    
+If you need to use a netmask in IPv4 format, you can achive so by
+using the IPv4#netmask= method
+
+  ip.netmask = "255.255.255.252"
+  ip.to_s
+    #=> "172.16.10.1/30"
+
+=== Working with networks, broadcasts and addresses
+
+Some very important topics in dealing with IP addresses are the
+concepts of +network+ and +broadcast+, as well as the addresses
+included in a range.
+
+When you specify an IPv4 address such as "172.16.10.1/24", you are
+actually handling two different information: 
+ 
+* The IP address itself, "172.16.10.1"
+* The subnet mask which indicates the network
+
+The network number is the IP which has all zeroes in the host
+portion. In our example, because the prefix is 24, we identify our
+network number to have the last 8 (32-24) bits all zeroes.  Thus, IP
+address "172.16.10.1/24" belongs to network "172.16.10.0/24".
+
+This is very important because, for instance, IP "172.16.10.1/16" is
+very different to the previous one, belonging to the very different
+network "172.16.0.0/16".
+
+With IPAddress it's very easy to calculate the network for an IP
+address:
+
+  ip = IPAddress "172.16.10.1/24"
+  net = ip.network
+    #=> #<IPAddress::IPv4:0xb7a5ab24 @octets=[172, 16, 10, 0], 
+                                     @prefix=24,
+                                     @address="172.16.10.0">
+  net.to_s
+    #=> "172.16.10.0/24"
+
+The IPv4#network method 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. 
+
+You can use method IPv4#network? to check whether an IP address is a
+network or not:
+
+  ip1 = IPAddress "172.16.10.1/24"
+  ip2 = IPAddress "172.16.10.4/30"
+
+  ip1.network?
+    #=> false
+  ip2.network?
+    #=> true
+
+The broadcast address is the contrary than the network number: where
+the network number has all zeroes in the host portion, the broadcast
+address has all one's. For example, ip "172.16.10.1/24" has broadcast
+"172.16.10.255/24", where ip "172.16.10.1/16" has broadcast
+"172.16.255.255/16".
+
+Method IPv4#broadcast has the same behaviour as is #network
+counterpart: it creates a new IPv4 object to handle the broadcast
+address:
+ 
+  ip = IPAddress "172.16.10.1/24"
+  bcast = ip.broadcast
+    #=> #<IPAddress::IPv4:0xb7a406fc @octets=[172, 16, 10, 255],
+                                     @prefix=24, 
+                                     @address="172.16.10.255">
+  bcast.to_s
+    #=> "172.16.10.255/24"
+
+So we see that the netmask essentially specifies a range for IP
+addresses that are included in a network: all the addresses between
+the network number and the broadcast. IPAddress has many methods to
+iterate between those addresses. Let's start with IPv4#each, which
+iterates over all addresses in a range
+
+  ip = IPAddress "172.16.10.1/24"
+
+  ip.each do |addr|
+    puts addr
+  end
+
+It is important to note that it doesn't matter if the original IP is a
+host IP or a network number (or a broadcast address): the #each method
+only considers the range that the original IP specifies. 
+
+If you only want to iterate over hosts IP, use the Ipv4#each_host
+method:
+
+  ip = IPAddress "172.16.10.1/24"
+
+  ip.each_host do |host|
+    puts host
+  end
+
+Methods IPv4#first and IPv4#last return a new object containing
+respectively the first and the last host address in the range
+
+  ip = IPAddress "172.16.10.100/24"
+
+  ip.first.to_s
+    #=> "172.16.10.1/24"
+
+  ip.last.to_s
+    #=> "172.16.10.254/24"
+
+=== IP special formats    
+
+The IPAddress library provides a complete set of methods to access an
+IPv4 address in special formats, such as binary, 32 bits unsigned int,
+data and hexadecimal.
+
+Let's take the following IPv4 as an example:
+
+  ip = IPAddress "172.16.10.1/24"
+  ip.address
+    #=> "172.16.10.1"
+
+The first thing to highlight here is that all these conversion methods
+only take into consideration the address portion of an IPv4 object and
+not the prefix (netmask).
+
+So, to express the address in binary format, use the IPv4#bits method:
+
+  ip.bits
+    #=> "10101100000100000000101000000001"
+
+To calculate the 32 bits unsigned int format of the ip address, use
+the IPv4#to_u32 method
+
+  ip.to_u32
+    #=> 2886732289
+
+This method is the equivalent of the Unix call pton(), expressing an
+IP address in the so called +network byte order+ notation. However, if
+you want to trasmit your IP over a network socket, you might need to
+transform it in data format using the IPv4#data method:
+
+  ip.data
+    #=> "\254\020\n\001"
+
+Finally, you can transform an IPv4 address into a format which is
+suitable to use in IPv4-IPv6 mapped addresses:
+
+  ip.to_ipv6
+    #=> "ac10:0a01"
+
+
+== Network design with IPAddress
+
+IPAddress includes a lot of useful methods to manipulate IPv4 and IPv6
+networks and do some basic network design. 
+
+=== Subnetting
+
+The process of subnetting is the division of a network into smaller
+(in terms of hosts capacity) networks, called subnets, so that they
+all share a common root, which is the starting network. 
+
+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:
+
+  network = IPAddress("172.16.10.0/24")
+
+  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] [...]]
+
+  subnets.map{|i| i.to_s}
+    #=> ["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:
+
+  ip = IPAddress("172.16.10.58/24")
+ 
+  ip.subnet(4).map{|i| i.to_s}
+    #=> ["172.16.10.0/26", "172.16.10.64/26", "172.16.10.128/26",
+         "172.16.10.192/26"]
+
+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 divived evenly, and all the subnets will have the same number
+of hosts. 
+
+=== Uneven subnetting
+
+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. 
+
+As an example, let's divide network 172.16.10.0/24 into 3 different subnets:
+
+  network = IPAddress("172.16.10.0/24")
+  network.subnet(3).map{|i| i.to_s}
+    #=> ["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:
+
+  network = IPAddress("172.16.10.0/24")
+  network.subnet(11).map{|i| i.to_s}
+    #=> ["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 remaning space.
+
+=== Summarization
+
+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"]
+
+In this case, the two summarizables networks have been aggregated into
+a single /23, while the other two networks have been left untouched.
+
+=== Supernetting
+
+Supernetting is a different operation than aggregation, as it only
+works on a single network and returns a new single IPv4 object,
+representing the supernet.
+
+Supernetting is similar to subnetting, except that you getting as a
+result a network with a smaller prefix (bigger host space). For
+example, given the network
+
+  ip = IPAddress("172.16.10.0/24")
+
+you can supernet it with a new /23 prefix
+
+  ip.supernet(23).to_s
+    #=> "172.16.10.0/23"
+
+However if you supernet it with a /22 prefix, the network address will
+change: 
+
+  ip.supernet(22).to_s
+    #=> "172.16.8.0/22"
+
+This is because "172.16.10.0/22" is not a network anymore, but an host
+address.
+
+
+=IPv6
+
+IPAddress is not only fantastic for IPv4 addresses, it's also great to
+handle IPv6 addresses family! Let's discover together how to use it in
+our projects.
+
+== IPv6 addresses
+
+IPv6 addresses are 128 bits long, in contrast with IPv4 addresses
+which are only 32 bits long. An IPv6 address is generally written as
+eight groups of four hexadecimal digits, each group representing 16
+bits or two octect. For example, the following is a valid IPv6
+address: 
+
+  1080:0000: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
+they will be converted.
+
+=== Compression
+
+Since IPv6 addresses are very long to write, there are some
+semplifications and compressions that you can use to shorten them. 
+
+* Leading zeroes: all the leading zeroes within a group can be
+  omitted: "0008" would become "8"
+  
+* A string of consecutive zeroes can be replaced by the string
+  "::". This can be only applied once.
+
+Using compression, the IPv6 address written above can be shorten into
+the following, equivalent, address
+
+  1080::8:800:200c:417a
+
+This short version is often used in human representation.
+
+=== Network Mask
+
+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
+
+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
+portion. 
+
+== Using IPAddress with IPv6 addresses
+
+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 "1080:0:0:0:8:800:200C:417A"
+ 
+  ip6 = IPAddress "1080::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
+addresses. If you want a different mask, you can go ahead and explicit
+it:
+
+  ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
+
+Access the address portion and the prefix by using the respective
+methods:
+
+  ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
+
+  ip6.address
+    #=> "2001:0db8:0000:0000:0008:0800:200c:417a"
+
+  ip6.prefix
+    #=> 64
+
+A compressed version of the IPv6 address can be obtained with the
+IPv6#compressed method:
+
+  ip6 = IPAddress "2001:0db8:0000:0000:0008:200c:417a:00ab/64"
+
+  ip6.compressed
+    #=> "2001:db8::8:800:200c:417a"
+
+== Handling the IPv6 address
+
+Accessing the groups that form an IPv6 address is very easy with the
+IPv6#groups method:
+
+  ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
+ 
+  ip6.groups
+    #=> [8193, 3512, 0, 0, 8, 2048, 8204, 16762]
+
+As with IPv4 addresses, each individual group can be accessed using
+the IPv6#[] shortcut method:
+
+  ip6[0]
+    #=> 8193
+  ip6[1]
+    #=> 3512
+  ip6[2]
+    #=> 0
+  ip6[3]
+    #=> 0
+
+Note that each 16 bits group is expressed in its decimal form. You can
+also obtain the groups into hexadecimal format using the IPv6#hexs
+method:
+
+  ip6.hexs
+    #=> => ["2001", "0db8", "0000", "0000", "0008", "0800", "200c", "417a"]
+
+A few other methods are available to transform an IPv6 address into
+decimal representation, with IPv6.to_i
+
+  ip6.to_i
+    #=> 42540766411282592856906245548098208122
+
+or to hexadecimal representation
+
+  ip6.to_hex
+    #=> "20010db80000000000080800200c417a"
+
+To print out an IPv6 address in human readable form, use the IPv6#to_s
+and IPv6#to_string methods
+
+  ip6 = IPAddress "2001:db8::8:800:200c:417a/64"
+ 
+  ip6.to_s
+    #=> "2001:db8::8:800:200c:417a/96"
+
+  ip6.to_string
+    #=> "2001:0db8:0000:0000:0008:0800:200c:417a/96"
+
+As you can see, IPv6.to_s prints out the compressed form, while
+IPv6.to_string uses the expanded version.
+
+=== Compressing and uncompressing
+
+If you have a string representing an IPv6 address, you can easily
+compress it and uncompress it using the two class methods IPv6::expand
+and IPv6::compress.
+
+For example, let's say you have the following uncompressed IPv6
+address:
+
+  ip6str = "2001:0DB8:0000:CD30:0000:0000:0000:0000"
+
+Here is the compressed version:
+
+  IPAddress::IPv6.compress ip6str
+    #=> "2001:db8:0:cd30::"
+
+The other way works as well:
+
+  ip6str = "2001:db8:0:cd30::"
+
+  IPAddress::IPv6.expand ip6str
+    #=> "2001:0DB8:0000:CD30:0000:0000:0000:0000"
+
+These methods can be used when you don't want to create a new object
+just for expanding or compressing an address (although a new object is
+actually created internally).
+ 
+== New IPv6 address from other formats
+
+You can create a new IPv6 address from different formats than just a
+string representing the colon-hex groups.
+
+For instance, if you have a data stream, you can use IPv6::parse_data,
+like in the following example:
+
+  data = " \001\r\270\000\000\000\000\000\b\b\000 \fAz"
+
+  ip6 = IPAddress::IPv6::parse_data data 
+  ip6.prefix = 64
+
+  ip6.to_s
+    #=> "2001:db8::8:800:200c:417a/64"
+
+A new IPv6 address can also be created from an unsigned 128 bits
+integer:
+
+  u128 = 21932261930451111902915077091070067066
+
+  ip6 = IPAddress::IPv6::parse_u128 u128
+  ip6.prefix = 64
+
+  ip6.to_s
+    #=> "1080::8:800:200c:417a/64"
+
+Finally, a new IPv6 address can be created from an hex string:
+
+  hex = "20010db80000000000080800200c417a"   
+
+  ip6 = IPAddress::IPv6::parse_hex hex
+  ip6.prefix = 64
+
+  ip6.to_s
+    #=> "2001:db8::8:800:200c:417a/64"
+
+== Special IPv6 addresses
+
+Some IPv6 have a special meaning and are expressed in a special form,
+quite different than an usual IPv6 address. IPAddress has builtin
+support for unspecified, loopback and mapped IPv6 addresses.
+
+=== Unspecified address
+
+The address with all zero bits is called the +unspecified+ address
+(corresponding to 0.0.0.0 in IPv4). It should be something like this:
+
+  0000:0000:0000:0000:0000:0000:0000:0000
+
+but, with the use of compression, it is usually written as just two
+colons:
+
+  ::
+
+or, specifying the netmask:
+
+  ::/128
+
+With IPAddress, create a new unspecified IPv6 address using its own
+subclass:
+
+  ip = IPAddress::IPv6::Unspecified.new
+
+  ip.to_s
+    #=> => "::/128"
+
+You can easily check if an IPv6 object is an unspecified address by
+using the IPv6#unspecified? method
+
+  ip.unspecified?
+    #=> true
+
+An unspecified IPv6 address can also be created with the wrapper
+method, like we've seen before
+
+  ip = IPAddress "::"
+
+  ip.unspecified?
+    #=> true
+
+This address must never be assigned to an interface and is to be used
+only in software before the application has learned its host's source
+address appropriate for a pending connection. Routers must not forward
+packets with the unspecified address.
+
+=== Loopback address
+
+The loopback  address is a unicast localhost address. If an
+application in a host sends packets to this address, the IPv6 stack
+will loop these packets back on the same virtual interface.
+
+Loopback addresses are expressed in the following form:
+
+  ::1
+
+or, with their appropriate prefix,
+
+  ::1/128
+
+As for the unspecified addresses, IPv6 loopbacks can be created with
+IPAddress calling their own class:
+
+  ip = IPAddress::IPv6::Loopback.new
+
+  ip.to_s
+    #=> "::1/128"
+
+or by using the wrapper:
+
+  ip = IPAddress "::1"
+
+  ip.to_s
+    #=> "::1/128"
+
+Checking if an address is loopback is easy with the IPv6#loopback?
+method:
+
+  ip.loopback?
+    #=> true
+  
+The IPv6 loopback address corresponds to 127.0.0.1 in IPv4.
+
+=== Mapped address
+
+It is usually identified as a IPv4 mapped IPv6 address, a particular
+IPv6 address which aids the transition from IPv4 to IPv6. The
+structure of the address is 
+
+  ::ffff:w.y.x.z
+
+where w.x.y.z is a normal IPv4 address. For example, the following is
+a mapped IPv6 address:
+
+  ::ffff:192.168.100.1
+
+IPAddress is very powerful in handling mapped IPv6 addresses, as the
+IPv4 portion is stored internally as a normal IPv4 object. Let's have
+a look at some examples. To create a new mapped address, just use the
+class builder itself
+
+  ip6 = IPAddress::IPv6::Mapped.new "::ffff:172.16.10.1/128"
+
+or just use the wrapper method
+
+  ip6 = IPAddress "::ffff:172.16.10.1/128"
+
+Let's check it's really a mapped address:
+
+  ip6.mapped?
+    #=> true
+
+  ip6.to_s
+    #=> "::FFFF:172.16.10.1/128"
+
+Now with the +ipv4+ attribute, we can easily access the IPv4 portion
+of the mapped IPv6 address:
+
+  ip6.ipv4.address
+    #=> "172.16.10.1"
+
+Internally, the IPv4 address is stored as two 16 bits
+groups. Therefore all the usual methods for an IPv6 address are
+working perfectly fine:
+
+  ip6.to_hex
+    #=> "00000000000000000000ffffac100a01"
+
+  ip6.address
+    #=> "0000:0000:0000:0000:0000:ffff:ac10:0a01"
+
+A mapped IPv6 can also be created just by specify the address in the
+following format:
+  
+  ip6 = IPAddress "::172.16.10.1"
+
+That is, two colons and the IPv4 address. However, as by RFC, the ffff 
+group will be automatically added at the beginning
+
+  ip6.to_s
+    => "::ffff:172.16.10.1/128"
+ 
+making it a mapped IPv6 compatible address.
+
+= Future versions:
+
+Some new features we'd like to add in the future versions:
+
+* support for wildmasks
+* network design methods for IPv6
+* parameter to IPv4#subnet to select where to fill the space
+  (beginning or ending)
+* method to check if a network is private
+
+Stay tuned!
+
+= Thanks to
+ 
+Thanks to Luca Russo (vargolo) for all the support and technical
+review.
+  
+= Copyright
+
+Copyright (c) 2009-2010 Marco Ceresa. See LICENSE for details.
+
+
+