Net::IP::XS(3pm)

✨ Net::IP::XS ✨

okay so bestie, welcome to Net::IP::XS — it's the IPv4/IPv6 address library 💖 that lives in your Perl, and she is fast because she's written in C. Pull up a chair, we're going through the whole thing, no skips, no skimming, periodt. 🎀

---

🌸 SYNOPSIS 🌸

like, here's the whole vibe in one go:

  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 🦋

So basically: this is an XS (C) implementation of Net::IP. 💅 If you wanna know all the functions and methods that are available, go read Net::IP's documentation — as at version 1.25. That's the tea. 🍓

---

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

this is the part where she's like "not to be that girl but i'm different" — and honestly, iconic of her. 👑

🌈 Exports

Nothing is exported by default. nope, not a single thing, you gotta ask for it bestie. 🙈

🌈 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. lowkey a plot twist. 💀

🌈 ip_auth

Returns undef on failure, instead of dying. she's gentle like that. 🫶

🌈 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. slay. ✨

🌈 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

okay this one has lore:

• 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

two whole moods here, buckle up:

• 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>" — the girlboss behind all of this. 💖

---

🎀 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. bestie, she wants your feedback, spill it. 🙈

---

🌟 ACKNOWLEDGEMENTS 🌟

Manuel Valente ("<manuel.valente@gmail.com>") and the other authors of Net::IP. giving credit where credit is due, as one does. 🫶

---

🔥 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.

okay but fr fr, if you're shipping this anywhere real, read that license section properly. no cap. 🫡

---

and that's the whole page bestie!! 🌈✨ this was built against perl v5.40.0 and dated 2024-12-07 — so if you're reading this way later, vibe check the docs again, mwah 💅💖🦋