IPv6::Address - IPv6 Address Manipulation Library


version 0.208

Coverage Status


 use IPv6::Address;

 my $ipv6 = IPv6::Address->new('2001:648:2000::/48');

 $ipv6->contains('2001:648:2000::/64'); #true

 say $ipv6->to_string;
 say $ipv6->string; # Same as previous
 say $ipv6; # Same as previous

 say $ipv6->string(nocompress=>1); # do not compress using the :: notation
 say $ipv6->string(ipv4=>1); #print the last 32 bits as an IPv4 address
 $ipv6->addr_string; # Returns '2001:648:2000::'
 $ipv6->split(4); # Split the prefix into 2^4 smaller prefixes. Returns a list.  

 $ipv6->apply_mask; # Apply the mask to the address. All bits beyond the mask length become 0.



 $a->enumerate_with_offset( 5 , 64 ); #returns 2001:648:2000:4::/64 


A pure Perl IPv6 address manipulation library. Emphasis on manipulation of prefixes and addresses. Very easy to understand and modify. The internal representation of an IPv6::Address is a blessed hash with two keys, a prefix length (0-128 obviously) and a 128-bit string. A multitude of methods to do various tasks is provided.


new( ipv6_string )

Takes a string representation of an IPv6 address and creates a corresponding IPv6::Address object.

raw_new( bitstr, length )

Creates a new IPv6::Address out of a bitstring and a prefix length. The bitstring must be binary, please do not use a '0' or '1' character string.


Returns the bitstr of the object.


Returns the prefix length of the address.


Returns a 128-bit string with the first prefix-length bits equal to 1, rest equal to 0. Essentially takes the prefix length of the object and returns a corresponding bit mask.


Returns the bitstring, after zeroing out all the bits after the prefix length. Essentially applies the prefix mask to the address.

generate_bitstr( number )

Not a method, returns 128-bit string, first n-items are 1, rest is 0.

bitstr_and( bitstr1 , bitstr2 )

Not a method, AND's two bitstrings, returns result.

bitstr_or( bitstr1 , bitstr2)

Not a method, OR's two bitstrings, returns result.

bitstr_not( bitstr )

Not a method, inverts a bitstring.

from_str( string_bitstring )

Not a method, takes a string of characters 0 or 1, returns corresponding binary bitstring. Please do not use more than 128 characters, rest will be ignored.

to_str( bitstring )

Not a method, takes a binary bitstring, returns a string composed of 0's and 1's. Please supply bitstrings of max. 128 bits, rest of the bits will be ignored.

contains( other_address )

This method takes an argument which is either an IPv6::Address or a plain string that can be promoted to a valid IPv6::Address, and tests whether the object contains it. Obviously returns true or false.


Returns the address part of the IPv6::Address. Using the option ipv4=>1 like


will make the last 32-bits appear as an IPv4 address. Also, using nocompress=>1 like

 $a->addr_string( nocompress => 1 ) 

will prevent the string from containing a '::' part. So it will be 8 parts separated by ':' colons.


Returns the full IPv6 address, with the prefix in its end.


Used internally by the overload module.

split( exponent , target_length )

Splits the address to the order of two of the number given as first argument. Example: if argument is 3, 2^3=8, address is split into 8 parts. The final parts have prefix length equal to the target_length specified in the second argument.


Applies the prefix length mask to the address. Does not return anything. Works on $self. WARNING:This will alter the object.


Returns the first address of the prefix that is represented by the object. E.g. consider 2001:648:2000::1234/64. First address will be 2001:648:2000::/64.


Returns the last address of the prefix that is represented by the object. E.g. consider 2001:648:2000::1234/64. Last address will be 2001:648:2000::ffff:ffff:ffff:ffff/64.

is_unspecified , is_loopback , is_multicast

Returns true or false depending on whether the address falls into the corresponding category stated by the method name. E.g.

 IPv6::Address->new('::1')->is_loopback # returns true

Not a method, takes an IPv4 address, returns a character string consisting of 32 characters that are 0 or 1. Used internally, not too useful for the end user.

enumerate_with_IPv4( ipv4, mask )

Takes an IPv4 address and uses a part of it to enumerate inside the Ipv6 prefix of the object. E.g.

 IPv6::Address->new('2001:648:2001::/48')->enumerate_with_IPv4('',0x0000ffff) #will yield 2001:648::2001:0001::/64

The return value will be a new IPv6::Address object, so the original object remains intact. The part that will be used as an offset is extracted from the ipv4 by using the mask.

enumerate_with_offset( offset, desired_length )

Takes a non-negative integer offset and returns a prefix whose relative position inside the object is defined by the offset. The prefix length of the result is defined by the second argument. E.g.

 IPv6::Address->new('2001:648:2000::/48')->enumerate_with_offset( 5 , 64 ) #2001:648:2000:4::/64
increment( offset )

Increments the IPv6::Address object by offset. Offsets larger than 2^32-1 are not acceptable. This method is probably not too useful, but is provided for completeness.


Takes the bitstring of the address and unpacks it using the first argument. Internal use mostly.


Splits the address into an 8-item array of unsigned short integers. Network byte order is implied, a short integer is 16-bits long.


Splits the address into an 4-item array of unsigned long integers. Network byte order is implied, a long integer is 32-bits long.

n_cmp( a , b )

Takes two 128-bit bitstr arguments, compares them and returns the result as -1, 0 or 1. The semantics are the same as that of the spaceship operator <=>.

This method will overload the <=> operator for IPv6::Address objects, so comparing IPv6::Address objects like they were integers produces the correct results.

n_sort( array )

Sorts an array of bitstrs using the n_cmp function.


Returns a string suitable to be returned as an IPv6 Radius AV-pair. See RFC 3162 for an explanation of the format.


Athanasios Douitsis <>


Please open a ticket at


Copyright 2008-2015 Athanasios Douitsis, all rights reserved.

This program is free software; you can use it under the terms of Artistic License 2.0 which can be found at