=encoding UTF-8

=head1 NAME

Net::IPv6Addr - Check and manipulate IPv6 addresses

=head1 VERSION

This documents version 1.02 of Net::IPv6Addr corresponding to
L<git commit f9065cb7b044da442df16443d65593a5a3fc6baa|https://github.com/benkasminbullock/net-ipv6addr/commit/f9065cb7b044da442df16443d65593a5a3fc6baa> released on Wed Mar 31 11:11:47 2021 +0900.

=head1 SYNOPSIS

    
    use Net::IPv6Addr;
    my $addr = "dead:beef:cafe:babe::f0ad";
    Net::IPv6Addr::ipv6_parse($addr);
    my $x = Net::IPv6Addr->new($addr);
    print $x->to_string_preferred(), "\n";


produces output

    dead:beef:cafe:babe:0:0:0:f0ad


(This example is included as L<F<synopsis.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/synopsis.pl> in the distribution.)


=head1 DESCRIPTION

C<Net::IPv6Addr> checks whether strings contain valid IPv6 addresses,
and converts IPv6 addresses into various formats.

All of L</new>, L</is_ipv6>, and L</ipv6_parse> can
process the following formats:

=over

=item Preferred form: x:x:x:x:x:x:x:x

C<2001:db8:0:0:0:ff00:42:8329>

This is the form described as the "preferred form" in section 2.2 of
L</RFC1884> et al. Output with L</to_string_preferred>.

=item Compressed form with double colon: x::x etc.

C<2001:db8::ff00:42:8329>

This is the "canonical text representation format" of L</RFC5952>.
Output with L</to_string_compressed>.

=item Mixed IPv4/IPv6 format: x:x:x:x:x:x:d.d.d.d

C<2001:db8:0:0:0:ff00:0.66.131.41>

Output with L</to_string_ipv4>.

=item Mixed IPv4/IPv6 with compression: x::x:d.d.d.d, etc.

C<2001:db8::ff00:0.66.131.41>

Output with L</to_string_ipv4_compressed>.

=item Big integers

An IPv6 can be changed to a L<Math::BigInt> object or a digit string
using L</to_bigint>. Big integers can also be input with
L</from_bigint>.

=item Base-85-encoded: [0-9A-Za-z!#$%&()*+;<=>?@^_`{|}~-]{20}

C<9R}vSQ9RqiCvG6zn?Zyh>

This encoding was given in L</RFC1924> as an April Fool's joke. Output
with L</to_string_base85>.

=back

In addition, the following formats can be output:

=over

=item Arrays

An IPv6 can be processed into its component pieces with L</to_array>
or L</to_intarray>.

=item Reverse-address pointer

An IPv6 can be processed into its reverse-address pointer, as defined
by L</RFC1886>, using L</to_string_ip6_int>.

=back

=head1 METHODS AND FUNCTIONS

The methods and functions are listed in alphabetical order. All except
L</new> serve as both object methods and standalone functions.

=head2 from_bigint

    
    use Net::IPv6Addr 'from_bigint';
    print from_bigint ('12345678901234567890')->to_string_compressed ();
    


produces output

    ::ab54:a98c:eb1f:ad2

(This example is included as L<F<from-bigint.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/from-bigint.pl> in the distribution.)


Given a string or a L<Math::BigInt> object containing a number, this
converts it into a Net::IPv6Addr object.

=head3 Parameters

A string or a Math::BigInt object. If the input is a scalar, it's
converted into a Math::BigInt object.

=head3 Returns

A Net::IPv6Addr object

=head3 Notes

Invalid input will generate an exception.

This function was added in L</0.95>.

=head2 in_network

    
    use Net::IPv6Addr;
    my $obj = Net::IPv6Addr->new ('dead:beef:cafe:babe:dead:beef:cafe:babe');
    if ($obj->in_network ('dead:beef:ca0::/21')) {
        print $obj->to_string_compressed, " is in network.\n";
    }
    
    


produces output

    dead:beef:cafe:babe:dead:beef:cafe:babe is in network.


(This example is included as L<F<inet.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/inet.pl> in the distribution.)


=head3 Parameters

If used as an object method, a network and its size in bits

    my $ok = $x->in_network ("aa:bb:cc:dd::", 64);

If used as a subroutine, an IPv6 address string in any format,
followed by a network address string and its size in bits.

    my $addr = 'fd00::54:20c:29fe:fe14:ab4b';
    my $ok = Net::IPv6Addr::in_network ($addr, "aa:bb:cc:dd::", 64);

The network size may also be given with the / notation after the
network address string:

    my $ok = $x->in_network("aa:bb:cc:dd::/64");

=head3 Returns

A true value if the address C<$x> is a member of the network given as
the argument, or false otherwise.

=head3 Notes

Invalid input will generate an exception.

Prior to version L</0.9>, this did not work correctly unless the net
size was a multiple of sixteen.

=head2 in_network_of_size

    
    use Net::IPv6Addr 'in_network_of_size';
    my $obj = in_network_of_size ('dead:beef:cafe:babe:dead:beef:cafe:babe', 42);
    print $obj->to_string_compressed ();


produces output

    dead:beef:cac0::

(This example is included as L<F<inos.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/inos.pl> in the distribution.)


Given an input IPv6 address $x, this returns the C<$n>
most-significant bits of C<$x> as a new Net::IPv6Addr object.

=head3 Parameters

If used as an object method, network size in bits:

    my $obj = $x->in_network_of_size (64);

If used as a subroutine, an IPv6 address string in any format and a
network size in bits:

    my $obj = in_network_of_size ($addr, 64);

Network size may also be given with C</> notation:

    my $obj = in_network_of_size ("$addr/64");

=head3 Returns

The C<$n> most-significant bits of C<$x> as a new Net::IPv6Addr object.

=head3 Notes

Invalid input will generate an exception. 

Prior to version L</0.9>, this did not work correctly unless the net
size was a multiple of sixteen.

=head2 ipv6_chkip

    my $niok = ipv6_chkip ('dead:beef:cafe:babe::f0ad');

=head3 Parameters

An IPv6 address string, without a prefix.

=head3 Returns

A true value (a code reference for the parser for this IP) if it's a
valid address; a false value (C<undef>) if not.

=head2 ipv6_parse

    my ($ni, $pl) = ipv6_parse ('dead:beef:cafe:babe::f0ad');

=head3 Parameters

Either a string containing an IPv6 address string, which may also
include a C</> character and a numeric prefix length,

    my ($x, $y) = ipv6_parse ("a::/24");

or an IPv6 address string, with an optional second argument consisting
of a numeric prefix length:

    my ($x, $y) = ipv6_parse('a::', '24');

=head3 Returns

Called in array context, the return value is a list consisting of the
address string and the prefix, if it parses correctly. Called in
scalar context, the address and prefix are concatenated with "/".

=head3 Notes

Throws an exception on malformed input.

=head2 is_ipv6

    my $niok = is_ipv6 ('dead:beef:cafe:babe::f0ad');

=head3 Parameters

Identical to L</ipv6_parse>.

=head3 Returns

This returns the return value of L</ipv6_parse>, called in scalar
context, if it does parse out correctly, otherwise it returns
C<undef>. Unlike L</ipv6_parse>, C<is_ipv6> does not throw exceptions.

=head2 new

    my $ni = Net::IPv6Addr->new ('dead:beef:cafe:babe::f0ad');

Create a new Net::IPv6Addr object from a string. Internally, the
object is a blessed array reference containing the eight parts of the
address as integers.

=head3 Parameters

A string to be interpreted as an IPv6 address.

=head3 Returns

A C<Net::IPv6Addr> object if successful.

=head3 Notes

Throws an exception if the string isn't a valid address.

=head2 to_array

    
    use Net::IPv6Addr 'to_array';
    my @int = to_array ('dead::beef');
    my $ipobj = Net::IPv6Addr->new ('dead::beef');
    my @int2 = $ipobj->to_array ();
    print "@int\n@int2\n";


produces output

    dead 0000 0000 0000 0000 0000 0000 beef
    dead 0000 0000 0000 0000 0000 0000 beef


(This example is included as L<F<array.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/array.pl> in the distribution.)


Convert an IPv6 address into an array of eight hexadecimal numbers.

=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

An array [0..7] of 16-bit hexadecimal numbers (strings).

=head3 Notes

Invalid input will generate an exception.

See also L</to_intarray> and L</to_bigint>.

=head2 to_bigint

    
    use Net::IPv6Addr 'to_bigint';
    my $int = to_bigint ('dead::beef');
    my $ipobj = Net::IPv6Addr->new ('dead::beef');
    my $int2 = $ipobj->to_bigint ();
    print "$int\n$int2\n";


produces output

    295986882420777848964380943247191621359
    295986882420777848964380943247191621359


(This example is included as L<F<bigint.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/bigint.pl> in the distribution.)


Convert an IPv6 address into a L<Math::BigInt> object containing the
IP address as a single number.

=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

The BigInt representation of the given IPv6 address.

=head3 Notes

Invalid input will generate an exception.

See also L</from_bigint>, L</to_intarray> and L</to_array>.

=head2 to_intarray

    
    use Net::IPv6Addr 'to_array';
    my @int = to_array ('dead::beef');
    my $ipobj = Net::IPv6Addr->new ('dead::beef');
    my @int2 = $ipobj->to_array ();
    print "@int\n@int2\n";


produces output

    dead 0000 0000 0000 0000 0000 0000 beef
    dead 0000 0000 0000 0000 0000 0000 beef


(This example is included as L<F<array.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/array.pl> in the distribution.)


Convert an IPv6 address into an array of eight integer numbers.

=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

An array [0..7] of numbers.

=head3 Notes

Invalid input will generate an exception.

See also L</to_array> and L</to_bigint>.

=head2 to_string_base85

=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

The IPv6 address in the style detailed by L</RFC1924>.

=head3 Notes

Invalid input will generate an exception. 

The base 85 encoding described in L</RFC1924> was an April Fool's
joke.

=head2 to_string_compressed

    
    use Net::IPv6Addr 'to_string_compressed';
    print to_string_compressed ('dead:beef:0000:0000:0000:0000:cafe:babe');


produces output

    dead:beef::cafe:babe

(This example is included as L<F<compressed.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/compressed.pl> in the distribution.)


This provides the "canonical text representation format" of
L</RFC5952>. 

=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

The IPv6 address in the "compressed" (L</RFC1884> et al.) or
"canonical" (L</RFC5952>) format. Hexadecimal numbers are reduced to
lower case, consecutive zero elements are reduced to double colons,
and leading zeros are removed from strings of hexadecimal digits. All
treatment of ambiguities is as per RFC5952. (See
L<F<t/rfc5952.t>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/t/rfc5952.t> for tests.)

=head3 Notes

Invalid input will generate an exception.

=head2 to_string_ip6_int

    
    use Net::IPv6Addr 'to_string_ip6_int';
    my $s = to_string_ip6_int ('dead::beef');
    my $ipobj = Net::IPv6Addr->new ('dead::beef');
    my $s2 = $ipobj->to_string_ip6_int ();
    print "$s\n$s2\n";


produces output

    f.e.e.b.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.e.d.IP6.INT.
    f.e.e.b.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.e.d.IP6.INT.


(This example is included as L<F<string-ip6-int.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/string-ip6-int.pl> in the distribution.)


=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

The reverse-address pointer as defined by L</RFC1886>.

=head3 Notes

Invalid input will generate an exception.

The reverse process of converting these into Net::IPv6Addr objects is
not supported.

=head2 to_string_ipv4

    
    use Net::IPv6Addr ':all';
    print to_string_ipv4_compressed ('dead:beef:0:3:2:1:cafe:babe');


produces output

    dead:beef::3:2:1:202.254.186.190

(This example is included as L<F<to-string-ipv4.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/to-string-ipv4.pl> in the distribution.)


=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

The IPv6 address in the IPv4 format detailed by L</RFC1884> et al.

=head3 Notes

When used as a subroutine, invalid input will generate an exception.

From version L</0.95>, this allows any IPv6 address to be produced, not
just the restricted forms allowed previously.

=head2 to_string_ipv4_compressed

    
    use Net::IPv6Addr ':all';
    print to_string_ipv4_compressed ('dead:beef:0:3:2:1:cafe:babe');


produces output

    dead:beef::3:2:1:202.254.186.190

(This example is included as L<F<to-string-ipv4-comp.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/to-string-ipv4-comp.pl> in the distribution.)


=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

The IPv6 address in the compressed IPv4 format detailed by
L</RFC1884> et al.

=head3 Notes

When used as a subroutine, invalid input will generate an exception.

From version L</0.95>, this allows any IPv6 address to be produced,
not just the restricted forms allowed previously.

=head2 to_string_preferred

    
    use Net::IPv6Addr 'to_string_preferred';
    print to_string_preferred ('dead:beef:cafe:babe::f0ad');


produces output

    dead:beef:cafe:babe:0:0:0:f0ad

(This example is included as L<F<preferred.pl>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/preferred.pl> in the distribution.)


=head3 Parameters

If used as an object method, none; if used as a subroutine,
an IPv6 address string in any format.

=head3 Returns

The IPv6 address, formatted in the "preferred" way (as detailed by
L</RFC1884> et al).

=head3 Notes

Invalid input will generate an exception.

=head1 EXPORTS

As of version 1.02, L</from_bigint>, L</in_network>, L</in_network_of_size>, L</ipv6_chkip>, L</ipv6_parse>, L</is_ipv6>, L</to_array>, L</to_bigint>, L</to_intarray>, L</to_string_base85>, L</to_string_compressed>, L</to_string_ip6_int>, L</to_string_ipv4>, L</to_string_ipv4_compressed>, L</to_string_preferred> may
be exported on demand. All the exported functions may be exported
using

    use Net::IPv6Addr ':all';

=head1 DEPENDENCIES

=over

=item L<Math::BigInt>

This is used by L</to_bigint> and L</from_bigint>.

=back

=head2 Reverse dependencies

L<Search grep.cpan.me for uses of this module|http://grep.cpan.me/?q=Net%3A%3AIPv6Addr%5Cb>

=head1 SEE ALSO

=head2 RFCs

The following RFCs (requests for comment, internet standards
documentation) contain information on IPv6.



=head3 Addressing Architecture series

These are all the same standard, with updates. The most recent one is
the active one.

=over

=item L<RFC1884|https://www.rfc-editor.org/rfc/rfc1884.txt>

I<IPv6 Addressing Architecture> - December 1995

=item L<RFC2373|https://www.rfc-editor.org/rfc/rfc2373.txt>

I<IP Version 6 Addressing Architecture> - July 1998

=item L<RFC3513|https://www.rfc-editor.org/rfc/rfc3513.txt>

I<Internet Protocol Version 6 (IPv6) Addressing Architecture> - April 2003

=item L<RFC4291|https://www.rfc-editor.org/rfc/rfc4291.txt>

I<IP Version 6 Addressing Architecture> - February 2006

=back

=head3 Other

=over

=item L<RFC1886|https://www.rfc-editor.org/rfc/rfc1886.txt>

I<DNS Extensions to support IP version 6> - December 1995

=item L<RFC1924|https://www.rfc-editor.org/rfc/rfc1924.txt>

I<A Compact Representation of IPv6 Addresses> - 1 April 1996

This was an April Fool's joke.

=item L<RFC5952|https://www.rfc-editor.org/rfc/rfc5952.txt>

I<A Recommendation for IPv6 Address Text Representation> - August 2010

This contains a "recommendation for a canonical text representation
format of IPv6 addresses" which corresponds to the output of
L</to_string_compressed> in this module.

=back

The links go to the plain text online versions of the RFCs.

=head2 Other CPAN modules

There are a very large number of CPAN modules which deal with IPv6
addresses. The following list gives all the ones I know about which
overlap with this module, in alphabetical order.

=over

=item L<Data::Validate::IP>

This module uses L<Socket> to validate IP addresses. It offers a
number of facilities for special-purpose sub networks, like
C<is_discard_ipv6>, which are not offered in Net::IPv6Addr.

=item L<IPv6::Address>

Its description says "A pure Perl IPv6 address manipulation
library. Emphasis on manipulation of prefixes and addresses."

It insists on having a prefix with the IP address, so

    my $ipv6 = IPv6::Address->new ('2001:0:0:1:0:0:0:1');

actually fails, you have to use

    my $ipv6 = IPv6::Address->new ('2001:0:0:1:0:0:0:1/64');

=item L<Net::IP>

Features binary IPs (strings like '101001'), etc.

=item L<Net::IP::Minimal>

It's a simplified version of L</Net::IP>.

=item L<Net::IPAddress::Util>

It's a "Version-agnostic representation of an IP address". I have not
tried this module.

=item L<Net::IPv6Address>

This module is broken and strongly not recommended.

=item L<NetAddr::IP>

=item L<NetAddr::IP::Lite>

These are two things in the same distribution. The documentation is
quite offputting, but there are a lot of users of the module and stars
on metacpan.

=item L<Regexp::IPv6>

This module consists of a regex for validating IPv6s. Because this
module had a lot more and better tests than Net::IPv6Addr, I included
the tests and one regex from C<Regexp::IPv6> in this module. (See
L<F<t/Regexp-IPv6.t>|https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/t/Regexp-IPv6.t>) Unlike C<Net::IPv6Addr>,
C<Regexp::IPv6> disallows C<::>, "the unspecified addresses". See the
module's documentation for details.

=back

=head2 Other

=over

=item Online validator

L<https://www.helpsystems.com/intermapper/ipv6-test-address-validation>

=back

=head1 HISTORY

This module was originally written by Tony Monroe in 2001 to simplify
the task of maintaining DNS records after he set himself up with
Freenet6.

In 2017 the module was adopted by Ben Bullock with the help of Neil
Bowers as part of "CPAN day". Significant changes to the module since
then include the following:

=over

=item 1.02

L<Net::IPv4Addr> dependence removed. This module suffered from the
"octal bug". This module had only been used to validate ipv4 addresses
and was easy to remove.

Math::Base85 dependence removed. This module is only needed to support
the April Fool's joke method of IPv6 addresses, so if the user doesn't
already have Math::Base85, the module now disables support for the
April Fool addresses.

=item 1.0

Checking of base 85 addresses and prefixes was made stricter in
response to user complaints.

=item 0.95

The L</from_bigint> method was added and the documentation updated to
reflect the current internet standards. 

The restriction on mixed address inputs removed in L</0.92> was also
removed in the output routines L</to_string_ipv4> and
L</to_string_ipv4_compressed>.

=item 0.92

The valid format consisting of a compressed-but-non-zero six-element
IPv6 followed by an IPv4, such as C<fe80::204:61ff:254.157.241.86>, is
accepted by the module.

=item 0.9

L</in_network> and L</in_network_of_size> were fixed to allow more
kinds of previxes.

=item 0.8

Exporting of some functions was added. Prior to this, everything had
to be done fully-qualified, as in
C<Net::IPv6Addr::to_string_compressed>.

=back

=head1 AUTHOR

Tony Monroe(*)

The module's interface resembles L<Net::IPv4Addr> by Francis
J. Lacoste E<lt>francis dot lacoste at iNsu dot COME<gt>.

Some fixes and subroutines from Jyrki Soini E<lt>jyrki dot soini
at sonera dot comE<gt>.

(*) The current module maintainer (BKB) does not have any contact
information for Tony Monroe. Those wishing to contact him can do so
via Neil Bowers (see L<his CPAN user page for contact
details|https://metacpan.org/author/NEILB>).

=head1 LICENSE

This distribution is copyright (c) 2001-2002 Tony Monroe.  All rights
reserved.  This software is distributed under the same license terms
as Perl itself.  This software comes with NO WARRANTIES WHATSOEVER,
express, implied, or otherwise.