1Net::Works::Network(3)User Contributed Perl DocumentationNet::Works::Network(3)
2
6 Net::Works::Network - An object representing a single IP address (4 or
7 6) subnet
8
10 version 0.22
11
13 use Net::Works::Network;
14 my $network = Net::Works::Network->new_from_string( string => '192.0.2.0/24' );
16 print $network->as_string(); # 192.0.2.0/24
17 print $network->prefix_length(); # 24
18 print $network->bits(); # 32
19 print $network->version(); # 4
20 my $first_address = $network->first();
22 print $first_address->as_string(); # 192.0.2.0
23 my $last_address = $network->last();
25 print $last_address->as_string(); # 192.0.2.255
26 my $iterator = $network->iterator();
28 while ( my $ip = $iterator->() ) { print $ip . "\n"; }
29 my $network_32 = Net::Works::Network->new_from_string( string => '192.0.2.4/32' );
31 print $network_32->max_prefix_length(); # 30
32 # All methods work with IPv4 and IPv6 subnets
34 my $ipv6_network = Net::Works::Network->new_from_string( string => '2001:db8::/48' );
35 my @subnets = Net::Works::Network->range_as_subnets( '192.0.2.1', '192.0.2.32' );
37 print $_->as_string, "\n" for @subnets;
38 # 192.0.2.1/32
39 # 192.0.2.2/31
40 # 192.0.2.4/30
41 # 192.0.2.8/29
42 # 192.0.2.16/28
43 # 192.0.2.32/32
44
46 Objects of this class represent an IP address network. It can handle
47 both IPv4 and IPv6 subnets. It provides various methods for getting
48 information about the subnet.
49 For IPv6, it uses 128-bit integers (via Math::Int128) to represent the
51 numeric value of an address as needed.
52
54 This class provides the following methods:
55 Net::Works::Network->new_from_string( ... )
57 This method takes a "string" parameter and an optional "version"
58 parameter. The "string" parameter should be a string representation of
59 an IP address subnet, e.g., "192.0.2.0/24".
60 my $network = Net::Works::Network->new_from_string(
62 string => '192.0.2.0/24'
63 );
64 print $network->as_string; # 192.0.2.0/24
65 The "version" parameter should be either 4 or 6, but you don't really
67 need this unless you're trying to force a dotted quad to be interpreted
68 as an IPv6 network or to a force an IPv6 address colon-separated hex
69 number to be interpreted as an IPv4 network.
70 If you pass an IPv4 network but specify the version as 6 then we will
72 add 96 to the netmask.
73 my $network = Net::Works::Network->new_from_string(
75 string => '192.0.2.0/24',
76 version => 6,
77 );
78 print $network->as_string; # ::192.0.2.0/120
79 Net::Works::Network->new_from_integer( ... )
81 This method takes an "integer" parameter, "prefix_length" parameter,
82 and an optional "version" parameter. The "integer" parameter should be
83 an integer representation of an IP within the subnet. The
84 "prefix_length" parameter should be an integer between 0 and 32 for
85 IPv4 or 0 and 128 for IPv6. The "version" parameter should be either 4
86 or 6.
87 Note that if you are passing an IPv4 address that you want treated as
89 an IPv6 address you need to manually add 96 to the "prefix_length"
90 yourself.
91 $network->as_string()
93 Returns a string representation of the network like "192.0.2.0/24" or
94 "2001:db8::/48". The IP address in the string is the first address
95 within the subnet.
96 $network->version()
98 Returns a 4 or 6 to indicate whether this is an IPv4 or IPv6 network.
99 $network->prefix_length()
101 Returns the length of the netmask as an integer.
102 $network->bits()
104 Returns the number of bit of an address in the network, which is either
105 32 (IPv4) or 128 (IPv6).
106 $network->max_prefix_length()
108 This returns the maximum possible numeric subnet that this network
109 could fit in. In other words, the 192.0.2.0/28 subnet could be part of
110 the 192.0.2.0/23 subnet, so this returns 23.
111 $network->first()
113 Returns the first IP in the network as an Net::Works::Address object.
114 $network->first_as_integer()
116 Returns the first IP in the network as an integer. This may be a
117 Math::Int128 object.
118 $network->last()
120 Returns the last IP in the network as an Net::Works::Address object.
121 $network->last_as_integer()
123 Returns the last IP in the network as an integer. This may be a
124 Math::Int128 object.
125 $network->is_single_address()
127 Returns true if the network contains just a single address (/32 in IPv4
128 or /128 in IPv6).
129 $network->iterator()
131 This returns an anonymous sub that returns one IP address in the range
132 each time it's called.
133 For single address subnets (/32 or /128), this returns a single
135 address.
136 When it has exhausted all the addresses in the network, it returns
138 "undef"
139 $network->contains($address_or_network)
141 This method accepts a single Net::Works::Address or Net::Works::Network
142 object. It returns true if the given address or network is contained by
143 the network it is called on. Note that a network always contains
144 itself.
145 $network->split()
147 This returns a list of two new network objects representing the
148 original network split into two halves. For example, splitting
149 "192.0.2.0/24" returns "192.0.2.0/25" and "192.0.2.128/25".
150 If the original networks is a single address network (a /32 in IPv4 or
152 /128 in IPv6) then this method returns an empty list.
153 Net::Works::Network->range_as_subnets( $first_address, $last_address,
155 $version )
156 Given two IP addresses as strings, this method breaks the range up into
157 the largest subnets that include all the IP addresses in the range
158 (including the two passed to this method).
159 This method also excludes any reserved subnets such as the RFC1918
161 <http://tools.ietf.org/html/rfc1918> IPv4 private address space,
162 RFC5735 <http://tools.ietf.org/html/rfc5735> IPv4 special-use address
163 space and RFC5156 <http://tools.ietf.org/html/rfc5156> IPv6 special-use
164 address space.
165 An overview can be found at the IANA IPv4
167 <http://www.iana.org/assignments/iana-ipv4-special-registry/iana-
168 ipv4-special-registry.xhtml> and IPv6
169 <http://www.iana.org/assignments/iana-ipv6-special-registry/iana-
170 ipv6-special-registry.xhtml> special-purpose address registries.
171 The networks currently treated as reserved are:
173 0.0.0.0/8
175 10.0.0.0/8
176 100.64.0.0/10
177 127.0.0.0/8
178 169.254.0.0/16
179 172.16.0.0/12
180 192.0.0.0/29
181 192.0.2.0/24
182 192.88.99.0/24
183 192.168.0.0/16
184 198.18.0.0/15
185 198.51.100.0/24
186 203.0.113.0/24
187 224.0.0.0/4
188 240.0.0.0/4
189 100::/64
191 2001::/23
192 2001:db8::/32
193 fc00::/7
194 fe80::/10
195 ff00::/8
196 This method works with both IPv4 and IPv6 addresses. You can pass an
198 explicit version as the final argument. If you don't, we check whether
199 either address contains a colon (:). If either of them does, we assume
200 you want IPv6 subnets.
201 When given an IPv6 range that includes the first 32 bits of addresses
203 (the IPv4 space), both IPv4 and IPv6 reserved networks are removed from
204 the range.
205
207 This class overloads comparison, allowing you to compare two objects
208 and to sort them (either as numbers or strings). Objects are compared
209 based on the first IP address in their networks, and then by prefix
210 length if they have the same starting address.
211 It also overloads stringification to call the "$network->as_string()"
213 method.
214
216 Prior to version 0.17, this package referred to the prefix length as
217 mask length. The "mask_length()" and "max_mask_length()" methods are
218 deprecated, and will probably start warning in a future release. In
219 addition, passing a "mask_length" key to the "new_from_integer()"
220 constructor has been replaced by "prefix_length". The old key will
221 continue to work for now but may start warning in a future release.
222
224 • Dave Rolsky <autarch@urth.org>
225 • Greg Oschwald <oschwald@cpan.org>
227 • Olaf Alders <oalders@wundercounter.com>
229
231 This software is copyright (c) 2016 by MaxMind, Inc.
232 This is free software; you can redistribute it and/or modify it under
234 the same terms as the Perl 5 programming language system itself.
235perl v5.34.0 2022-01-21 Net::Works::Network(3)