NAME

       Net::IP::XS - IPv4/IPv6 address library

SYNOPSIS

         use Net::IP::XS;

         my $ip = new Net::IP::XS ('193.0.1/24') or die (Net::IP::XS::Error());
         print ("IP  : ".$ip->ip()."\n");
         print ("Sho : ".$ip->short()."\n");
         print ("Bin : ".$ip->binip()."\n");
         print ("Int : ".$ip->intip()."\n");
         print ("Mask: ".$ip->mask()."\n");
         print ("Last: ".$ip->last_ip()."\n");
         print ("Len : ".$ip->prefixlen()."\n");
         print ("Size: ".$ip->size()."\n");
         print ("Type: ".$ip->iptype()."\n");
         print ("Rev:  ".$ip->reverse_ip()."\n");

DESCRIPTION

       An XS (C) implementation of Net::IP. See Net::IP's documentation (as at version 1.25) for
       the functions and methods that are available.

DIFFERENCES BETWEEN NET::IP AND NET::IP::XS

       Exports
           Nothing is exported by default.

       Error messages
           In some instances this won't set error codes or messages where "Net::IP" would, though
           it should be mostly the same.

       Object-oriented interface
           The object-oriented interface uses function calls and hashref lookups internally, such
           that subclassing "Net::IP::XS" will not have the same effect as it does with
           "Net::IP".

       ip_auth
           Returns "undef" on failure, instead of dying.

       ip_binadd
           Returns "undef" if either of the bitstring arguments is more than 128 characters in
           length.

           Any character of the bitstring that is not a 0 is treated as a 1. The "Net::IP"
           version returns different results for different digits, and treats non-digits as 0.

       ip_bintoint
           The integer returned will be at most ((1 << 128) - 1) (i.e. the largest possible IPv6
           address). "Net::IP" handles bitstrings of arbitrary length.

       ip_compress_address
           Returns "undef" if the IPv6 address argument is invalid.

       ip_compress_v4_prefix
           Returns "undef" if the "len" argument is negative or greater than 32.

       ip_expand_address
           Does not set "Error" or "Errno" where there is a problem with an embedded IPv4 address
           within an IPv6 address.

           Returns the zero IP address if the empty string is provided. The "Net::IP" version
           returns "undef".

           Returns a full IPv6 address if a partial address is provided (e.g.  returns
           'ffff:ffff:0000:0000:0000:0000:0000:0000' if 'ffff:ffff' is provided).  The "Net::IP"
           version returns the partial address.

           Returns "undef" on an invalid IPv4/IPv6 address. The "Net::IP" version returns the
           zero address for IPv4 and whatever was provided for IPv6.

       ip_get_mask
           The mask returned will always have a length equal to the number of bits in an address
           of the specified IP version (e.g. an IPv4 mask will always comprise 32 characters).
           The "Net::IP" version will return a longer mask when the "len" argument is larger than
           the number of bits in the specified IP version.

           If a negative "len" is provided, it will be treated as zero.

       ip_inttobin
           The bitstring returned will always be either 32 or 128 characters in length, and it
           returns "undef" if the integer argument would require more than 128 characters to
           represent as a bitstring. If an invalid version is provided, the returned bitstring
           will be 128 characters in length. The "Net::IP" version handles arbitrary integers and
           expands to accommodate those integers, regardless of the version argument.  Also, if
           an invalid version is provided, the returned bitstring is only as long as is necessary
           to accommodate the bitstring.

       ip_iptobin
           Returns "undef" on an invalid IPv4/IPv6 address.

       ip_last_address_bin
           Returns an empty string if an invalid version (i.e. not 4 or 6) is provided. If the
           bitstring provided is longer than the number of bits in the specified version, then
           only the first 32/128 bits will be used in determining the last address. If the "len"
           provided is invalid (negative or more than 32/128 depending on the version), it will
           be treated as the maximum length of the specified version.

       ip_normalize
           For the 'plus' style of string (e.g. '1.0.0.0 + 255'), whitespace between the plus
           character and the parts before and after it is optional. In the "Net::IP" version,
           there has to be some whitespace before and after the plus character. Also, "undef"
           will be returned if the part after the plus sign is not a number. The "Net::IP"
           version will return two copies of the single address in this instance.

           For the 'prefix range' style of string (e.g. '1.0.0.0/8'), the part after the slash
           must be a number. If it is not, "undef" will be returned. The "Net::IP" version will
           return two copies of the single address in this instance.

       ip_range_to_prefix
           Returns "undef" if the version argument is invalid.

       ip_reverse
           The "len" argument determines the length of the reverse domain - e.g., if the
           arguments are '127.0.0.1', '16' and '4', the reverse domain will be
           '0.127.in-addr.arpa.'. The "Net::IP" version does not take the "len" argument into
           account for IPv4 addresses. For IPv6 addresses, a compressed IP address string may be
           provided.

       ip_splitprefix
           Returns "undef" unless the first component of the string is less than or equal to 64
           characters in length. The "Net::IP" version handles strings of arbitrary length.

       prefix
           Returns a string with a prefix length of zero (e.g. '127.0.0.1/0') where "prefixlen"
           is not defined in the object. The "Net::IP" version will not include any prefix length
           in the returned string (e.g. '127.0.0.1/').

AUTHOR

       Tom Harrison, "<tomhrr@cpan.org>"

BUGS

       Please report any bugs or feature requests to "bug-net-ip-xs at rt.cpan.org", or through
       the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-IP-XS>.

ACKNOWLEDGEMENTS

       Manuel Valente ("<manuel.valente@gmail.com>") and the other authors of Net::IP.

SEE ALSO

       Net::IP, IP::Authority.

COPYRIGHT & LICENSE

       Copyright (C) 2010-2023 Tom Harrison <tomhrr@cpan.org>.

       Original inet_pton4 and inet_pton6 functions are copyright (C) 2006 Free Software
       Foundation.

       Original interface, and the auth and ip_auth functions, are copyright (C) 1999-2002 RIPE
       NCC.

       This program is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
       Boston, MA 02110-1301 USA.