=head1 NAME

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

=head1 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
  }

=head1 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).

=head1 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)

=head1 METHODS/FUNCTIONS

=over 25

=item ->B<new_list>()

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

=item ->B<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]


=item ->B<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.

=item ->B<get_next_intersection_range>()

  Returns the next CIDR range in the intersection.

=item ->B<remove_list>($list)

  Removes a list from the collection.

=back

=head1 LICENSE  

  Sections of this code was 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.
