/ 
Net-IPAM-IP-1.09
River stage one • 2 direct dependents • 2 total dependents
/ Net::IPAM::IP

NAME

Net::IPAM::IP - A library for reading, formatting, sorting and converting IP-addresses.

SYNOPSIS

use Net::IPAM::IP;

# parse and normalize
$ip1 = Net::IPAM::IP->new('1.2.3.4') // die 'wrong format,';
$ip2 = Net::IPAM::IP->new('fe80::1') // die 'wrong format,';

$ip3 = $ip2->incr // die 'overflow,';

say $ip1;    # 1.2.3.4
say $ip2;    # fe80::1
say $ip3;    # fe80::2

say $ip1->cmp($ip2);    # -1

say $ip2->expand;       # fe80:0000:0000:0000:0000:0000:0000:0001
say $ip2->reverse;      # 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.e.f

$ip = Net::IPAM::IP->new_from_bytes(pack('C4', 192, 168, 0, 1));       # 192.168.0.1
$ip = Net::IPAM::IP->new_from_bytes(pack('N4', 0x20010db8, 0, 0, 1,)); # 2001:db8::1

METHODS

Net::IPAM::IP implements the following methods:

new

Parse the input string as IPv4/IPv6 address and returns the IP address object.

IPv4-mapped-IPv6 addresses are normalized and sorted as IPv4 addresses.

::ffff:1.2.3.4    => 1.2.3.4

Returns undef on illegal input.

clone

Just a blessed shallow copy of the {binary} attribute.

new_from_bytes

$ip = Net::IPAM::IP->new_from_bytes("\x0a\x00\x00\x01")

Parse the input as packed IPv4/IPv6/IPv4-mapped-IPv6 address and returns the IP address object.

Croaks on illegal input.

bytes

$ip = Net::IPAM::IP->new('fe80::');
$bytes = $ip->bytes;    # "\xfe\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"

$ip    = Net::IPAM::IP->new('10.0.0.1');
$bytes = $ip->bytes;    # "\x0a\x00\x00\x01"

Returns the packed IP address as byte-string. It's the opposite to "new_from_bytes"

cmp

Compare IP objects, returns -1, 0, +1

$this->cmp($other)

@sorted_ips = sort { $a->cmp($b) } @unsorted_ips;

Fast bytewise lexical comparison of the binary representation in network byte order.

IPv4 addresses are always treated as smaller than IPv6 addresses.

version

$v = Net::IPAM::IP->new('fe80::1')->version    # 6

Returns 4 or 6.

to_string

Returns the input string in canonical form.

lower case hexadecimal characters
zero compression
remove leading zeros

say Net::IPAM::IP->new('Fe80::0001')->to_string;  # fe80::1

Stringification is overloaded with "to_string"

my $ip = Net::IPAM::IP->new('Fe80::0001') // die 'wrong format,';;
say $ip; # fe80::1

incr

Returns the next IP address, returns undef on overflow.

$next_ip = Net::IPAM::IP->new('fe80::1')->incr // die 'overflow,';
say $next_ip;   # fe80::2

expand

Expand IP address into canonical form, useful for grep, aligned output and lexical sort

Net::IPAM::IP->new('1.2.3.4')->expand;   # '001.002.003.004'
Net::IPAM::IP->new('fe80::1')->expand;   # 'fe80:0000:0000:0000:0000:0000:0000:0001'

reverse

Reverse IP address, needed for PTR entries in DNS zone files.

Net::IPAM::IP->new('fe80::1')->reverse; # '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.e.f'
Net::IPAM::IP->new('1.2.3.4')->reverse; # '4.3.2.1'

FUNCTIONS

Net::IPAM::IP implements the following functions;

incr_n($n)

Increment a packed IPv4 or IPv6 address, no need for Math::BigInt. Needed by methods in Net::IPAM::Block.

OPERATORS

Net::IPAM::IP overloads the following operators.

bool

my $bool = !!$ip;

Always true.

stringify

my $str = "$ip";

Alias for "to_string".

WARNING

Some Socket::inet_XtoY implementations are hopelessly buggy.

Tests are made during loading and in case of errors, these functions are redefined with a (slower) pure-perl implementation.

AUTHOR

Karl Gaissmaier, <karl.gaissmaier(at)uni-ulm.de>

BUGS

Please report any bugs or feature requests to bug-net-ipam-ip at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-IPAM-IP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::IPAM::IP

You can also look for information at:

  • on github

    TODO

SEE ALSO

Net::IPAM::Block Net::IPAM::Tree

LICENSE AND COPYRIGHT

This software is copyright (c) 2020 by Karl Gaissmaier.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.