Net::W...Network(3pm)

📦
version 0.22 · 5 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

👑 NAME 👑

Net::Works::Network — it's giving object, bestie, one single IP subnet (v4 or v6, both, we don't discriminate 💖). This is the Net::W...Network(3pm) page you're reading rn, in case you were wondering what you even opened.

✨ VERSION ✨

version 0.22 🎀

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, copy-paste ready:

use Net::Works::Network;

my $network = Net::Works::Network->new_from_string( string => '192.0.2.0/24' );
print $network->as_string();          # 192.0.2.0/24
print $network->prefix_length();        # 24
print $network->bits();               # 32
print $network->version();            # 4

my $first_address = $network->first();
print $first_address->as_string();    # 192.0.2.0

my $last_address = $network->last();
print $last_address->as_string();     # 192.0.2.255

my $iterator = $network->iterator();
while ( my $ip = $iterator->() ) { print $ip . "\n"; }

my $network_32 = Net::Works::Network->new_from_string( string => '192.0.2.4/32' );
print $network_32->max_prefix_length(); # 30

# All methods work with IPv4 and IPv6 subnets
my $ipv6_network = Net::Works::Network->new_from_string( string => '2001:db8::/48' );

my @subnets = Net::Works::Network->range_as_subnets( '192.0.2.1', '192.0.2.32' );
print $_->as_string, "\n" for @subnets;
# 192.0.2.1/32
# 192.0.2.2/31
# 192.0.2.4/30
# 192.0.2.8/29
# 192.0.2.16/28
# 192.0.2.32/32

no cap, that's the whole tour right there 💅

🦋 DESCRIPTION 🦋

So objects of this class represent an IP address network. She handles both IPv4 and IPv6 subnets, she's versatile like that. And she comes with a whole lil arsenal of methods for getting info about the subnet. main character energy tbh.

For IPv6, it uses 128-bit integers (via Math::Int128) to represent the numeric value of an address as needed. yes bestie, big numbers, big brain 🧠✨

💅 METHODS 💅

This class provides the following methods:

💜 Net::Works::Network->new_from_string( ... )

This method takes a string parameter and an optional version parameter. The string parameter should be a string representation of an IP address subnet, e.g., 192.0.2.0/24.

my $network = Net::Works::Network->new_from_string(
    string => '192.0.2.0/24'
);
print $network->as_string; # 192.0.2.0/24

The version parameter should be either 4 or 6, but honestly you don't really need this unless you're trying to force a dotted quad to be interpreted as an IPv6 network, or to force an IPv6 address colon-separated hex number to be interpreted as an IPv4 network. niche use case but okay, we support you 🫶

If you pass an IPv4 network but specify the version as 6 then we will add 96 to the netmask. math! iconic!

my $network = Net::Works::Network->new_from_string(
    string  => '192.0.2.0/24',
    version => 6,
);
print $network->as_string; # ::192.0.2.0/120

🍓 Net::Works::Network->new_from_integer( ... )

This method takes an integer parameter, a prefix_length parameter, and an optional version parameter. The integer parameter should be an integer representation of an IP within the subnet. The prefix_length parameter should be an integer between 0 and 32 for IPv4, or 0 and 128 for IPv6. The version parameter should be either 4 or 6.

Heads up bestie: if you are passing an IPv4 address that you want treated as an IPv6 address, you need to manually add 96 to the prefix_length yourself. The code will not do it for you, no matter how nicely you ask. 😭

🌈 $network->as_string()

Returns a string representation of the network like 192.0.2.0/24 or 2001:db8::/48. The IP address in the string is the first address within the subnet. so cute, so consistent.

⭐ $network->version()

Returns a 4 or 6 to indicate whether this is an IPv4 or IPv6 network. simple. flawless. periodt.

🎀 $network->prefix_length()

Returns the length of the netmask as an integer.

🌸 $network->bits()

Returns the number of bits of an address in the network, which is either 32 (IPv4) or 128 (IPv6).

🧚 $network->max_prefix_length()

This returns the maximum possible numeric subnet that this network could fit in. In other words, the 192.0.2.0/28 subnet could be part of the 192.0.2.0/23 subnet, so this returns 23. it's giving "how big can I go" energy.

🦋 $network->first()

Returns the first IP in the network as a Net::Works::Address object.

💖 $network->first_as_integer()

Returns the first IP in the network as an integer. This may be a Math::Int128 object.

👑 $network->last()

Returns the last IP in the network as a Net::Works::Address object.

💜 $network->last_as_integer()

Returns the last IP in the network as an integer. This may be a Math::Int128 object.

✨ $network->is_single_address()

Returns true if the network contains just a single address (/32 in IPv4 or /128 in IPv6). just one lil guy 🥺

🌈 $network->iterator()

This returns an anonymous sub that returns one IP address in the range each time it's called. it's like a lil vending machine for addresses fr fr.

For single address subnets (/32 or /128), this returns a single address.

When it has exhausted all the addresses in the network, it returns undef. and then it's done, no more, thank you for coming 💀

🍓 $network->contains($address_or_network)

This method accepts a single Net::Works::Address or Net::Works::Network object. It returns true if the given address or network is contained by the network it is called on. Note that a network always contains itself — self-love, we love to see it 💅

🎀 $network->split()

This returns a list of two new network objects representing the original network split into two halves. For example, splitting 192.0.2.0/24 returns 192.0.2.0/25 and 192.0.2.128/25. mitosis! 🧬

If the original network is a single address network (a /32 in IPv4 or /128 in IPv6) then this method returns an empty list. can't split what's already one, bestie.

🧚 Net::Works::Network->range_as_subnets( $first_address, $last_address, $version )

Given two IP addresses as strings, this method breaks the range up into the largest subnets that include all the IP addresses in the range (including the two passed to this method). it's giving efficient packing.

This method also excludes any reserved subnets such as the RFC1918 <http://tools.ietf.org/html/rfc1918> IPv4 private address space, RFC5735 <http://tools.ietf.org/html/rfc5735> IPv4 special-use address space and RFC5156 <http://tools.ietf.org/html/rfc5156> IPv6 special-use address space.

An overview can be found at the IANA IPv4 <http://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml> and IPv6 <http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml> special-purpose address registries.

The networks currently treated as reserved are:

0.0.0.0/8
10.0.0.0/8
100.64.0.0/10
127.0.0.0/8
169.254.0.0/16
172.16.0.0/12
192.0.0.0/29
192.0.2.0/24
192.88.99.0/24
192.168.0.0/16
198.18.0.0/15
198.51.100.0/24
203.0.113.0/24
224.0.0.0/4
240.0.0.0/4

100::/64
2001::/23
2001:db8::/32
fc00::/7
fe80::/10
ff00::/8

This method works with both IPv4 and IPv6 addresses. You can pass an explicit version as the final argument. If you don't, we check whether either address contains a colon (:). If either of them does, we assume you want IPv6 subnets. detective work 🔍✨

When given an IPv6 range that includes the first 32 bits of addresses (the IPv4 space), both IPv4 and IPv6 reserved networks are removed from the range. double the filtering, double the fun.

🔥 OVERLOADING 🔥

This class overloads comparison, allowing you to compare two objects and to sort them (either as numbers or strings). Objects are compared based on the first IP address in their networks, and then by prefix length if they have the same starting address. tie-breaker! iconic!

It also overloads stringification to call the $network->as_string() method. so you can just print it like it's nothing 🫶

😭 DEPRECATED METHODS AND ATTRIBUTES 😭

Prior to version 0.17, this package referred to the prefix length as mask length. The mask_length() and max_mask_length() methods are deprecated, and will probably start warning in a future release. In addition, passing a mask_length key to the new_from_integer() constructor has been replaced by prefix_length. The old key will continue to work for now but may start warning in a future release.

bestie, don't use the old names in new code. they still work but they're on thin ice 💀 use prefix_length.

🌸 AUTHORS 🌸

  • Dave Rolsky <autarch@urth.org>
  • Greg Oschwald <oschwald@cpan.org>
  • Olaf Alders <oalders@wundercounter.com>

This software is copyright (c) 2016 by MaxMind, Inc.

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

okay that's the whole page, you ate it up, go forth and subnet responsibly 🧚✨ this was perl v5.32.0, dated 2021-01-09, signing off from the Net::W...Network(3pm) page — love u, bye 💅💖

📦 where this page comes from