NAME
Net::IPAddress::Util - Version-agnostic representation of an IP address
VERSION
Version 0.09
SYNOPSIS
use Net::IPAddress::Util try => 'GMP,Pari', qw( IP );
my $ipv4 = IP('192.168.0.1');
my $ipv46 = IP('::ffff:192.168.0.1');
my $ipv6 = IP('fe80::1234:5678:90ab');
print "$ipv4\n"; # 192.168.0.1
print "$ipv46\n"; # 192.168.0.1
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('192.168.0.0'); $ip <= IP('192.168.0.255'); $ip++) {
# do something with $ip
}DESCRIPTION
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.
BACKEND LIBRARIES
This module subclasses Math::BigInt, and can take the same arguments to control the choice of backend math libraries, specifically try, lib, and only. In order, these will silently fail, fail with warn(), or fail with die(), if the specified backend librar(y|ies) cannot be loaded. The default backend (which will be fallen back to if your specified backend(s) cannot be loaded) is FastCalc, or Calc if FastCalc is not available.
CHOOSING A BACKEND
Rule 1 is "profile before optimizing". Rule 2 is "your mileage may vary". Rule 3 is "your users' mileage almost certainly will vary".
A general guideline seems to be that you can safely stick with the default if you're going to be using IPv4 addresses, or if you wont need to search & sort IPv6 addresses, but for searching and sorting large numbers of IPv6 addresses, you should at least try one or both of GMP and Pari, and consider testing the relative speed of radix_sort() on your platform.
GLOBAL VARIABLES
$Net::IPAddress::Util::DIE_ON_ERROR
Set to a true value to make errors confess(). Set to a false value to make errors cluck(). Defaults to false.
$Net::IPAddress::Util::PROMOTE_N32
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.
EXPORTABLE FUNCTIONS
explode_ip
implode_ip
Transform an IP address to and from an array of 128 bits, MSB-first.
common_prefix
Given two bit arrays (as provided by explode_ip), return the truncated bit array of the prefix bits those two arrays have in common.
prefix_mask
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.
ip_pad_prefix
Take a truncated bit array, and right-pad it with zeroes to the appropriate length.
radix_sort
Given an array of objects, sorts them in ascending order, faster than Perl's built-in sort command.
Note that this may only be faster for sufficiently large arrays, due to the overhead involved in setting up the radix sort.
Note also that radix_sort() discards duplicate addresses.
COMPATIBILITY API
ip2num
num2ip
validaddr
mask
fqdn
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.
EXPORT TAGS
:constr
Exports IP() and n32_to_ipv4(), both useful for creating objects based on arbitrary external data.
:manip
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.
:sort
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. Even then, you should profile before optimizing -- radix_sort() can be very much slower, instead of very much faster, under the wrong circumstances.
:compat
Exports the Compatibility API functions listed above.
:all
Exports all exportable functions.
CONSTRUCTORS
new
Create a new Net::IPAddress::Util object, based on a well-formed IPv4 or IPv6 address string (e.g. '192.168.0.1' 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').
IP
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 typingn32_to_ipv4
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.
OBJECT METHODS
All object methods supported by Math::BigInt are supported. In addition, the following methods exist specifically for IP Address manipulation:
is_ipv4
Returns true if this object represents an IPv4 address.
ipv4
Returns the dotted-quad representation of this object, or an error if it is not an IPv4 address, for instance '192.168.0.1'.
as_n32
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.
ipv6
Returns the canonical IPv6 string representation of this object, for instance 'fe80::1234:5678:90ab' or '::ffff:192.168.0.1'.
ipv6_expanded
Returns the IPv6 string representation of this object, without compressing extraneous zeroes, for instance 'fe80:0000:0000:0000:0000:1234:5678:90ab'.
normal_form
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'.
'""'
str
If this object is an IPv4 address, it stringifies to the result of ipv4, else it stringifies to the result of ipv6.
INTERNAL FUNCTIONS
ERROR
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.