.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::CIDR::Set 3pm"
.TH Net::CIDR::Set 3pm "2023-12-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::CIDR::Set \- Manipulate sets of IP addresses
.SH "VERSION"
.IX Header "VERSION"
This document describes Net::CIDR::Set version 0.13
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::CIDR::Set;
\&
\&  my $priv = Net::CIDR::Set\->new( \*(Aq10.0.0.0/8\*(Aq, \*(Aq172.16.0.0/12\*(Aq,
\&    \*(Aq192.168.0.0/16\*(Aq );
\&  for my $ip ( @addr ) {
\&    if ( $priv\->contains( $ip ) ) {
\&      print "$ip is private\en";
\&    }
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Net::CIDR::Set\*(C'\fR represents sets of \s-1IP\s0 addresses and allows standard
set operations (union, intersection, membership test etc) to be
performed on them.
.PP
In spite of the name it can work with sets consisting of arbitrary
ranges of \s-1IP\s0 addresses \- not just \s-1CIDR\s0 blocks.
.PP
Both IPv4 and IPv6 addresses are handled \- but they may not be mixed in
the same set. You may explicitly set the personality of a set:
.PP
.Vb 1
\&  my $ip4set = Net::CIDR::Set\->new({ type => \*(Aqipv4 }, \*(Aq10.0.0.0/8\*(Aq);
.Ve
.PP
Normally this isn't necessary \- the set will guess its personality from
the first data that is added to it.
.SH "INTERFACE"
.IX Header "INTERFACE"
.ie n .SS """new"""
.el .SS "\f(CWnew\fP"
.IX Subsection "new"
Create a new Net::CIDR::Set. All arguments are optional. May be passed a
list of list of \s-1IP\s0 addresses or ranges which, if present, will be
passed to \f(CW\*(C`add\*(C'\fR.
.PP
The first argument may be a hash reference which will be inspected for
named options. Currently the only option that may be passed is \f(CW\*(C`type\*(C'\fR
which should be 'ipv4', 'ipv6' or the name of a coder class. See
Net::CIDR::Set::IPv4 and Net::CIDR::Set::IPv6 for examples of
coder classes.
.ie n .SS """invert"""
.el .SS "\f(CWinvert\fP"
.IX Subsection "invert"
Invert (negate, complement) a set in-place.
.PP
.Vb 2
\&  my $set = Net::CIDR::Set\->new;
\&  $set\->invert;
.Ve
.ie n .SS """copy"""
.el .SS "\f(CWcopy\fP"
.IX Subsection "copy"
Make a deep copy of a set.
.PP
.Vb 1
\&  my $set2 = $set\->copy;
.Ve
.ie n .SS """add"""
.el .SS "\f(CWadd\fP"
.IX Subsection "add"
Add a number of addresses or ranges to a set.
.PP
.Vb 5
\&  $set\->add(
\&    \*(Aq10.0.0.0/8\*(Aq, 
\&    \*(Aq192.168.0.32\-192.168.0.63\*(Aq, 
\&    \*(Aq127.0.0.1\*(Aq
\&  );
.Ve
.PP
It is legal to add ranges that overlap with each other and/or with the
ranges already in the set. Overlapping ranges are merged.
.ie n .SS """remove"""
.el .SS "\f(CWremove\fP"
.IX Subsection "remove"
Remove a number of addresses or ranges from a set.
.PP
.Vb 4
\&  $set\->remove(
\&    \*(Aq8.8.0.0/16\*(Aq,
\&    \*(Aq158.152.1.58\*(Aq
\&  );
.Ve
.PP
There is no requirement that the addresses being removed be members
of the set.
.ie n .SS """merge"""
.el .SS "\f(CWmerge\fP"
.IX Subsection "merge"
Merge the contents of other sets into this set.
.PP
.Vb 2
\&  $set = Net::CIDR::Set\->new;
\&  $set\->merge($s1, $s2);
.Ve
.ie n .SS """contains"""
.el .SS "\f(CWcontains\fP"
.IX Subsection "contains"
A synonmym for \f(CW\*(C`contains_all\*(C'\fR.
.ie n .SS """contains_all"""
.el .SS "\f(CWcontains_all\fP"
.IX Subsection "contains_all"
Return true if the set contains all of the supplied addresses.
Given this set:
.PP
.Vb 1
\&  my $set = Net::CIDR::Set\->new(\*(Aq244.188.12.0/8\*(Aq);
.Ve
.PP
this condition is true:
.PP
.Vb 3
\&  if ( $set\->contains_all(\*(Aq244.188.12.128/3\*(Aq) ) {
\&    # ...
\&  }
.Ve
.PP
while this condition is false:
.PP
.Vb 3
\&  if ( $set\->contains_all(\*(Aq244.188.12.0/12\*(Aq) ) {
\&    # ...
\&  }
.Ve
.ie n .SS """contains_any"""
.el .SS "\f(CWcontains_any\fP"
.IX Subsection "contains_any"
Return true if there is any overlap between the supplied
addresses/ranges and the contents of the set.
.ie n .SS """complement"""
.el .SS "\f(CWcomplement\fP"
.IX Subsection "complement"
Return a new set that is the complement of this set.
.PP
.Vb 1
\&  my $inv = $set\->complement;
.Ve
.ie n .SS """union"""
.el .SS "\f(CWunion\fP"
.IX Subsection "union"
Return a new set that is the union of a number of sets. This is
equivalent to a logical \s-1OR\s0 between sets.
.PP
.Vb 1
\&  my $everything = $east\->union($west);
.Ve
.ie n .SS """intersection"""
.el .SS "\f(CWintersection\fP"
.IX Subsection "intersection"
Return a new set that is the intersection of a number of sets. This is
equivalent to a logical \s-1AND\s0 between sets.
.PP
.Vb 1
\&  my $overlap = $north\->intersection($south);
.Ve
.ie n .SS """xor"""
.el .SS "\f(CWxor\fP"
.IX Subsection "xor"
Return a new set that is the exclusive-or of existing sets.
.PP
.Vb 1
\&  my $xset = $this\->xor($that);
.Ve
.PP
The resulting set will contain all addresses that are members of one set
but not the other.
.ie n .SS """diff"""
.el .SS "\f(CWdiff\fP"
.IX Subsection "diff"
Return a new set containing all the addresses that are present in this
set but not another.
.PP
.Vb 1
\&  my $diff = $this\->diff($that);
.Ve
.ie n .SS """is_empty"""
.el .SS "\f(CWis_empty\fP"
.IX Subsection "is_empty"
Return a true value if the set is empty.
.PP
.Vb 3
\&  if ( $set\->is_empty ) {
\&    print "Nothing there!\en";
\&  }
.Ve
.ie n .SS """superset"""
.el .SS "\f(CWsuperset\fP"
.IX Subsection "superset"
Return true if this set is a superset of the supplied set.
.ie n .SS """subset"""
.el .SS "\f(CWsubset\fP"
.IX Subsection "subset"
Return true if this set is a subset of the supplied set.
.ie n .SS """equals"""
.el .SS "\f(CWequals\fP"
.IX Subsection "equals"
Return true if this set is identical to another set.
.PP
.Vb 3
\&  if ( $set\->equals($foo) ) {
\&    print "We have the same addresses.\en";
\&  }
.Ve
.SH "Retrieving Set Contents"
.IX Header "Retrieving Set Contents"
The following methods allow the contents of a set to be retrieved in
various representations. Each of the following methods accepts an
optional numeric argument that controls the formatting of the returned
addresses. It may take one of the following values:
.ie n .IP "0" 4
.el .IP "\f(CW0\fR" 4
.IX Item "0"
Format each range of addresses as compactly as possible. If the range
contains only a single address format it as such. If it can be
represented as a single \s-1CIDR\s0 block use \s-1CIDR\s0 representation (<ip>/<mask>)
otherwise format it as an arbitrary range (<start>\-<end>).
.ie n .IP "1" 4
.el .IP "\f(CW1\fR" 4
.IX Item "1"
Always format as either a \s-1CIDR\s0 block or an arbitrary range even if the
range is just a single address.
.ie n .IP "2" 4
.el .IP "\f(CW2\fR" 4
.IX Item "2"
Always use arbitrary range format (<start>\-<end>) even if the range is a
single address or a legal \s-1CIDR\s0 block.
.PP
Here's an example of the different formatting options:
.PP
.Vb 2
\&  my $set = Net::CIDR::Set\->new( \*(Aq127.0.0.1\*(Aq, \*(Aq192.168.37.0/24\*(Aq,
\&    \*(Aq10.0.0.11\-10.0.0.17\*(Aq );
\&
\&  for my $fmt ( 0 .. 2 ) {
\&    print "Using format $fmt:\en";
\&    print "  $_\en" for $set\->as_range_array( $fmt );
\&  }
.Ve
.PP
And here's the output from that code:
.PP
.Vb 12
\&  Using format 0:
\&    10.0.0.11\-10.0.0.17
\&    127.0.0.1
\&    192.168.37.0/24
\&  Using format 1:
\&    10.0.0.11\-10.0.0.17
\&    127.0.0.1/32
\&    192.168.37.0/24
\&  Using format 2:
\&    10.0.0.11\-10.0.0.17
\&    127.0.0.1\-127.0.0.1
\&    192.168.37.0\-192.168.37.255
.Ve
.PP
Note that this option never affects the addresses that are returned;
only how they are formatted.
.PP
For most purposes the formatting argument can be omitted; it's default
value is \f(CW0\fR which provides the most general formatting.
.ie n .SS """iterate_addresses"""
.el .SS "\f(CWiterate_addresses\fP"
.IX Subsection "iterate_addresses"
Return an iterator (a closure) that will return each of the addresses in
the set in ascending order. This code
.PP
.Vb 5
\&  my $set = Net::CIDR::Set\->new(\*(Aq192.168.37.0/24\*(Aq);
\&  my $iter = $set\->iterate_addresses;
\&  while ( my $ip = $iter\->() ) {
\&    print "Got $ip\en";
\&  }
.Ve
.PP
outputs 256 distinct addresses from 192.168.37.0 to 192.168.27.255.
.ie n .SS """iterate_cidr"""
.el .SS "\f(CWiterate_cidr\fP"
.IX Subsection "iterate_cidr"
Return an iterator (a closure) that will return each of the \s-1CIDR\s0 blocks
in the set in ascending order. This code
.PP
.Vb 5
\&  my $set = Net::CIDR::Set\->new(\*(Aq192.168.37.9\-192.168.37.134\*(Aq);
\&  my $iter = $set\->iterate_cidr;
\&  while ( my $cidr = $iter\->() ) {
\&    print "Got $cidr\en";
\&  }
.Ve
.PP
outputs
.PP
.Vb 9
\&  Got 192.168.37.9
\&  Got 192.168.37.10/31
\&  Got 192.168.37.12/30
\&  Got 192.168.37.16/28
\&  Got 192.168.37.32/27
\&  Got 192.168.37.64/26
\&  Got 192.168.37.128/30
\&  Got 192.168.37.132/31
\&  Got 192.168.37.134
.Ve
.PP
This is the most compact \s-1CIDR\s0 representation of the set because its
limits don't fall on convenient \s-1CIDR\s0 boundaries.
.ie n .SS """iterate_ranges"""
.el .SS "\f(CWiterate_ranges\fP"
.IX Subsection "iterate_ranges"
Return an iterator (a closure) that will return each of the ranges
in the set in ascending order. This code
.PP
.Vb 9
\&  my $set = Net::CIDR::Set\->new(
\&    \*(Aq192.168.37.9\-192.168.37.134\*(Aq,
\&    \*(Aq127.0.0.1\*(Aq,
\&    \*(Aq10.0.0.0/8\*(Aq 
\&  );
\&  my $iter = $set\->iterate_ranges;
\&  while ( my $range = $iter\->() ) {
\&    print "Got $range\en";
\&  }
.Ve
.PP
outputs
.PP
.Vb 3
\&  Got 10.0.0.0/8
\&  Got 127.0.0.1
\&  Got 192.168.37.9\-192.168.37.134
.Ve
.ie n .SS """as_array"""
.el .SS "\f(CWas_array\fP"
.IX Subsection "as_array"
Convenience method that gathers all of the output from one of the
iterators above into an array.
.PP
.Vb 1
\&  my @ranges = $set\->as_array( $set\->iterate_ranges );
.Ve
.PP
Normally you will use one of \f(CW\*(C`as_address_array\*(C'\fR, \f(CW\*(C`as_cidr_array\*(C'\fR or
\&\f(CW\*(C`as_range_array\*(C'\fR instead.
.ie n .SS """as_address_array"""
.el .SS "\f(CWas_address_array\fP"
.IX Subsection "as_address_array"
Return an array containing all of the distinct addresses in a set. Note
that this may very easily create a very large array. At the time of
writing it is, for example, unlikely that you have enough memory for an
array containing all of the possible IPv6 addresses...
.ie n .SS """as_cidr_array"""
.el .SS "\f(CWas_cidr_array\fP"
.IX Subsection "as_cidr_array"
Return an array containing all of the distinct \s-1CIDR\s0 blocks in a set.
.ie n .SS """as_range_array"""
.el .SS "\f(CWas_range_array\fP"
.IX Subsection "as_range_array"
Return an array containing all of the ranges in a set.
.ie n .SS """as_string"""
.el .SS "\f(CWas_string\fP"
.IX Subsection "as_string"
Return a compact string representation of a set.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Armstrong  \f(CW\*(C`<andy.armstrong@messagesystems.com>\*(C'\fR
.SH "CREDITS"
.IX Header "CREDITS"
The encode and decode routines were stolen en masse from Douglas
Wilson's Net::CIDR::Lite.
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.PP
Copyright (c) 2009, Message Systems, Inc.
All rights reserved.
.PP
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:
.PP
.Vb 9
\&    * Redistributions of source code must retain the above copyright
\&      notice, this list of conditions and the following disclaimer.
\&    * Redistributions in binary form must reproduce the above copyright
\&      notice, this list of conditions and the following disclaimer in
\&      the documentation and/or other materials provided with the
\&      distribution.
\&    * Neither the name Message Systems, Inc. nor the names of its
\&      contributors may be used to endorse or promote products derived
\&      from this software without specific prior written permission.
.Ve
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \*(L"AS
IS\*(R" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF USE, DATA, OR
PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING
NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0