NAME

Net::CIDR::Compare - Find intersections across multiple lists of CIDR ranges, fast.

SYNOPSIS

use Net::CIDR::Compare;

my $collection = Net::CIDR::Compare->new(print_errors => 1);

my $first_list = $collection->new_list();
$collection->add_range($first_list, "10.10.0.0/16", 1);

my $second_list = $collection->new_list();
$collection->add_range($second_list, "10.10.200.0/24", 1);

$collection->process_intersection(expand_cidr => 8);
while (my $cidr_range = $collection->get_next_intersection_range()) {
  print "$cidr_range\n"; # prints 10.10.200.0/24
}

$collection->remove_list($second_list);

$collection->process_intersection(expand_cidr => 8);
while (my $cidr_range = $collection->get_next_intersection_range()) {
  print "$cidr_range\n"; # prints 10.10.0.0/16
}

DESCRIPTION

This module accepts various formats of IPv4 ranges, converts non-CIDR
ranges to CIDR, and produces the intersection of CIDR ranges across
all the lists in the collection.

Net::CIDR::Compare was designed to handle large IPv4 lists and compute
the intersection of these lists in a memory-efficient and speedy way.
The intersection code is C code and Perl-wrapped using XS.  You will
need a C compiler to install this code.

Although the main driver for this module's creation is to find the
intersection across several lists, this module can also be used with just
a single list to convert non-CIDR range formats to CIDR and merge ranges
quickly.

Net::CIDR::Compare also requires Net::CIDR and Net::Netmask for some
of the range format conversions (e.g. converting 10.0.0.* to 10.0.0.0/24).

CONSTRUCTING

Net::CIDR::Compare objects are created with one optional parameter,
print_errors.  Errors are always stored in $collection->{error} (from
above example).  If print_errors is set (default yes) then errors
are also printed to STDERR.

$collection = Net::CIDR::Compare->new(print_errors => 1)

METHODS/FUNCTIONS

->new_list()

Creates a new list (C binary tree).  Returns a list pointer.

->add_range($list, $iprange, $skip_check)

Adds an IP range to the list specified. If the $skip_check parameter is
set (default no), the range is assumed to be CIDR and no validation checks
are run.  This greatly improves performance, but if an invalid range is
passed the result is unknown.

Non-CIDR formats are silently converted to CIDR unless $skip_check is set.
Accepted IP range formats:
CIDR: 1.1.1.0/24
Wildcard: 1.1.1.*
Start-End Pair: 1.1.1.0-1.1.1.255
Bracket Octet Range: 1.1.1.[0-255]

->process_intersection(expand_cidr => 8)

Finds the intersection across all lists in the collection.  Returns nothing.

An optional parameter, expand_cidr, sets the minimum CIDR value.  For example,
setting this parameter to 32 would produce single IP results.  The default is
0, which produces the smallest CIDR value (largest network size) results.

->get_next_intersection_range()

Returns the next CIDR range in the intersection.

->remove_list($list)

Removes a list from the collection.

LICENSE

Sections of this code were obtained from a C program called cidr-convert
which can be found on numerous sites.  The sourcecode claimed to be of 
"the public domain."  This code is also part of the public domain.

Please send feedback to grjones@gmail.com.