NAME¶
Net::CIDR::Lite - Perl extension for merging IPv4 or IPv6 CIDR addresses
SYNOPSIS¶
use Net::CIDR::Lite;
my $cidr = Net::CIDR::Lite->new;
$cidr->add($cidr_address);
@cidr_list = $cidr->list;
@ip_ranges = $cidr->list_range;
DESCRIPTION¶
Faster alternative to Net::CIDR when merging a large number of CIDR address
ranges. Works for IPv4 and IPv6 addresses.
METHODS¶
- new()
-
$cidr = Net::CIDR::Lite->new
$cidr = Net::CIDR::Lite->new(@args)
Creates an object to represent a list of CIDR address ranges. No particular
format is set yet; once an add method is called with a IPv4 or IPv6
format, only that format may be added for this cidr object. Any arguments
supplied are passed to add_any() (see below).
- add()
-
$cidr->add($cidr_address)
Adds a CIDR address range to the list.
- add_range()
-
$cidr->add_range($ip_range)
Adds a hyphenated IP address range to the list.
- add_cidr()
-
$cidr1->add_cidr($cidr2)
Adds address ranges from one object to another object.
- add_ip()
-
$cidr->add_ip($ip_address)
Adds a single IP address to the list.
- add_any()
-
$cidr->add_any($cidr_or_range_or_address);
Determines format of range or single ip address and calls add(),
add_range(), add_cidr(), or add_ip() as
appropriate.
- $cidr->clean()
-
$cidr->clean;
If you are going to call the list method more than once on the same data,
then for optimal performance, you can call this to purge null nodes in
overlapping ranges from the list. Boundary nodes in contiguous ranges are
automatically purged during add(). Only useful when ranges overlap
or when contiguous ranges are added out of order.
- $cidr->list()
-
@cidr_list = $cidr->list;
$list_ref = $cidr->list;
Returns a list of the merged CIDR addresses. Returns an array if called in
list context, an array reference if not.
- $cidr->list_range()
-
@cidr_list = $cidr->list_range;
$list_ref = $cidr->list_range;
Returns a list of the merged addresses, but in hyphenated range format.
Returns an array if called in list context, an array reference if
not.
- $cidr->list_short_range()
-
@cidr_list = $cidr->list_short_range;
$list_ref = $cidr->list_short_range;
Returns a list of the C subnet merged addresses, in short hyphenated range
format. Returns an array if called in list context, an array reference if
not.
Example:
1.1.1.1-2
1.1.1.5-7
1.1.1.254-255
1.1.2.0-2
1.1.3.5
1.1.3.7
- $cidr->find()
-
$found = $cidr->find($ip);
Returns true if the ip address is found in the CIDR range. False if not. Not
extremely efficient, is O(n*log(n)) to sort the ranges in the cidr object
O(n) to search through the ranges in the cidr object. The sort is cached
on the first call and used in subsequent calls, but if more addresses are
added to the cidr object, prep_find() must be called on the cidr
object.
- $cidr->bin_find()
- Same as find(), but forces a binary search. See also
prep_find.
- $cidr->prep_find()
-
$cidr->prep_find($num);
Caches the result of sorting the ip addresses. Implicitly called on the
first find call, but must be explicitly called if more addresses are added
to the cidr object. find() will do a binary search if the number of
ranges is greater than or equal to $num (default 20);
- $cidr->spanner()
-
$spanner = $cidr1->spanner($label1, $cidr2, $label2, ...);
Creates a spanner object to find out if multiple ip addresses are within
multiple labeled address ranges. May also be called as (with or without
any arguments):
Net::CIDR::Lite::Span->new($cidr1, $label1, $cidr2, $label2, ...);
- $spanner->add()
-
$spanner->add($cidr1, $label1, $cidr2, $label2,...);
Adds labeled address ranges to the spanner object. The 'address range' may
be a Net::CIDR::Lite object, a single CIDR address range, a single
hyphenated IP address range, or a single IP address.
- $spanner->find()
-
$href = $spanner->find(@ip_addresses);
Look up which range(s) ip addresses are in, and return a lookup table of the
results, with the keys being the ip addresses, and the value a hash
reference of which address ranges the ip address is in.
- $spanner->bin_find()
- Same as find(), but forces a binary search. See also
prep_find.
- $spanner->prep_find()
-
$spanner->prep_find($num);
Called implicitly the first time $spanner->find(..) is called, must be
called again if more cidr objects are added to the spanner object. Will do
a binary search if ratio of the number of ip addresses to the number of
ranges is less than $num percent (default 4).
- $spanner->clean()
-
$clean_address = $spanner->clean($ip_address);
Validates and returns a cleaned up version of an ip address (which is what
you will find as the key in the result from the $spanner->find(..), not
necessarily what the original argument looked like). E.g. removes
unnecessary leading zeros, removes null blocks from IPv6 addresses,
etc.
CAVEATS¶
Garbage in/garbage out. This module does do validation, but maybe not enough to
suit your needs.
AUTHOR¶
Douglas Wilson, <dougw@cpan.org> w/numerous hints and ideas borrowed from
Tye McQueen.
COPYRIGHT¶
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
SEE ALSO¶
Net::CIDR.