Paul W Bennett


Net::IPAddress::Util - Version-agnostic representation of an IP address


Version 3.020


    use Net::IPAddress::Util qw( IP );

    my $ipv4  = IP('');
    my $ipv46 = IP('::ffff:');
    my $ipv6  = IP('fe80::1234:5678:90ab');

    print "$ipv4\n";  #
    print "$ipv46\n"; #
    print "$ipv6\n";  # fe80::1234:5678:90ab

    print $ipv4->normal_form()  . "\n"; # 00000000000000000000ffffc0a80001
    print $ipv46->normal_form() . "\n"; # 00000000000000000000ffffc0a80001
    print $ipv6->normal_form()  . "\n"; # fe8000000000000000001234567890ab

    for (my $ip = IP(''); $ip <= IP(''); $ip++) {
        # do something with $ip


The goal of the Net::IPAddress::Util modules is to make IP addresses easy to deal with, regardless of whether they're IPv4 or IPv6, and regardless of the source (and destination) of the data being manipulated. The module Net::IPAddress::Util is for working with individual addresses, Net::IPAddress::Util::Range is for working with individual ranges of addresses, and Net::IPAddress::Util::Collection is for working with collections of addresses and/or ranges.



Set to a true value to make errors confess(). Set to a false value to make errors cluck(). Defaults to false.


Set to a true value to make new() assume that bare 32-bit (or smaller) numbers are supposed to represent IPv4 addresses, and promote them accordingly (i.e. to do implicitly what n32_to_ipv4() does). Set to a false value to make new() treat all bare numbers as 128-bit numbers representing IPv6 addresses. Defaults to false.




Transform an IP address to and from an array of 128 bits, MSB-first.


Given two bit arrays (as provided by explode_ip), return the truncated bit array of the prefix bits those two arrays have in common.


Given two bit arrays (as provided by explode_ip), return a truncated bit array of ones of the same length as the shared common_prefix of the two arrays.


Take a truncated bit array, and right-pad it with zeroes to the appropriate length.


Returns a bitmask that can be ANDed against an IP to pull out only the IPv4-relevant bits, that is the N32 portion with the 0xffff appended to its front.


Returns a bitmask that can be ORed onto an N32 to make it a proper "IPv4 stored as IPv6" N128.


Given an array of objects, sorts them in ascending order, faster than Perl's built-in sort command.

For those who understand the math, a radix sort is O(N) instead of O(N log N) (the speed of Perl's builtin sort()), but it does discard duplicates, so ymmv. There are also (rare) corner cases in which radix_sort() can chew up so much RAM that it causes paging / swapping, which will slow down the process dramatically.

Also note that this particular radix sort implementation is technically kinda O(48 * N) (even though one would normally ignore a simple multiplier factor), so the break even point is actually nice and low (something close to 4 or more addresses) for it to be worth the setup and teardown costs associated.







These functions are exportable to provide a functionally-identical API to that provided by Net::IPAddress. They will cause warnings to be issued if they are called, to help you in your transition to Net::IPAddress::Util, if indeed that's what you're doing -- and I can't readily imagine any other reason you'd want to export them from here (as opposed to from Net::IPAddress) unless that's indeed what you're doing.



Exports IP() and n32_to_ipv4(), both useful for creating objects based on arbitrary external data.


Exports the functions for low-level "bit-twiddling" of addresses. You very probably don't need these unless you're writing your own equivalent of the Net::IPAddress::Util::Range or Net::IPAddress::Util::Collection modules.


Exports radix_sort(). You only need this if you're dealing with very large arrays of Net::IPAddress::Util objects, and runtime is of critical concern.


Exports the Compatibility API functions listed above.


Exports all exportable functions.



Create a new Net::IPAddress::Util object, based on a well-formed IPv4 or IPv6 address string (e.g. '' or 'fe80::1234:5678:90ab'), or based on what is known by this module as the "normal form", a 32-digit hex number (without the leading '0x').


The exportable function IP() is a shortcut for Net::IPAddress::Util->new().

    my $xyzzy = Net::IPAddress::Util->new($foo);
    my $plugh = IP($foo); # Exactly the same thing, but with less typing


The exportable function n32_to_ipv4() converts an IPv4 address in "N32" format (i.e. a network-order 32-bit number) into an Net::IPAddress::Util object representing the same IPv4 address.


This module overloads a number of operators (cmp, <=>, &, |, ~, +, -, <<, >>) in hopefully obvious ways.



Returns true if this object represents an IPv4 address.


Returns the dotted-quad representation of this object, or an error if it is not an IPv4 address, for instance ''.


Returns the "N32" representation of this object (that is, a 32-bit number in network order) if this object represents an IPv4 address, or an error if it does not.


Returns the "N128" representation of this object (that is, a 128-bit number in network order).

You may supply one optional argument. If this argument is true, the return value will be a Math::BigInt object (allowing quickish and easy math involving two such return values), otherwise (if it is false (the default)), then the N128 number will be returned as a bare string. If your platform can handle math with unsigned 128-bit integers, or if you will not be doing math on the results, then I strongly recommend the latter (default / false) option for performance reasons. In the true-argument case, you're advised to stringify the Math::BigInt math results as soon as is practical for performance reasons -- Math::BigInt is not "CPU free".


Returns the canonical IPv6 string representation of this object, for instance 'fe80::1234:5678:90ab' or '::ffff:'.


Returns the IPv6 string representation of this object, without compressing extraneous zeroes, for instance 'fe80:0000:0000:0000:0000:1234:5678:90ab'.


Returns the value of this object as a zero-padded 32-digit hex string, without the leading '0x', suitable (for instance) for storage in a database, or for other purposes where easy, fast sorting is desirable, for instance 'fe8000000000000000001234567890ab'.





If this object is an IPv4 address, it stringifies to the result of ipv4, else it stringifies to the result of ipv6.



Either confess()es or cluck()s the passed string based on the value of $Net::IPAddress::Util::DIE_ON_ERROR, and if possible returns undef.


May be redistributed and/or modified under terms of the Artistic License v2.0.


PWBENNETT -- paul(dot)w(dot)bennett(at)