Net::CIDR::Lite(3pm)

1Lite(3)               User Contributed Perl Documentation              Lite(3)
2
3
4

NAME

6       Net::CIDR::Lite - Perl extension for merging IPv4 or IPv6 CIDR
7       addresses
8

SYNOPSIS

10         use Net::CIDR::Lite;
11
12         my $cidr = Net::CIDR::Lite->new;
13         $cidr->add($cidr_address);
14         @cidr_list = $cidr->list;
15         @ip_ranges = $cidr->list_range;
16

DESCRIPTION

18       Faster alternative to Net::CIDR when merging a large number of CIDR
19       address ranges. Works for IPv4 and IPv6 addresses.
20

METHODS

22       new()
23            $cidr = Net::CIDR::Lite->new
24            $cidr = Net::CIDR::Lite->new(@args)
25
26           Creates an object to represent a list of CIDR address ranges.  No
27           particular format is set yet; once an add method is called with a
28           IPv4 or IPv6 format, only that format may be added for this cidr
29           object. Any arguments supplied are passed to add_any() (see below).
30
31       add()
32            $cidr->add($cidr_address)
33
34           Adds a CIDR address range to the list.
35
36       add_range()
37            $cidr->add_range($ip_range)
38
39           Adds a hyphenated IP address range to the list.
40
41       add_cidr()
42            $cidr1->add_cidr($cidr2)
43
44           Adds address ranges from one object to another object.
45
46       add_ip()
47            $cidr->add_ip($ip_address)
48
49           Adds a single IP address to the list.
50
51       add_any()
52            $cidr->add_any($cidr_or_range_or_address);
53
54           Determines format of range or single ip address and calls add(),
55           add_range(), add_cidr(), or add_ip() as appropriate.
56
57       $cidr->clean()
58            $cidr->clean;
59
60           If you are going to call the list method more than once on the same
61           data, then for optimal performance, you can call this to purge null
62           nodes in overlapping ranges from the list. Boundary nodes in
63           contiguous ranges are automatically purged during add().  Only
64           useful when ranges overlap or when contiguous ranges are added out
65           of order.
66
67       $cidr->list()
68            @cidr_list = $cidr->list;
69            $list_ref  = $cidr->list;
70
71           Returns a list of the merged CIDR addresses. Returns an array if
72           called in list context, an array reference if not.
73
74       $cidr->list_range()
75            @cidr_list = $cidr->list;
76            $list_ref  = $cidr->list;
77
78           Returns a list of the merged addresses, but in hyphenated range
79           format. Returns an array if called in list context, an array
80           reference if not.
81
82       $cidr->find()
83            $found = $cidr->find($ip);
84
85           Returns true if the ip address is found in the CIDR range. False if
86           not.  Not extremely efficient, is O(n*log(n)) to sort the ranges in
87           the cidr object O(n) to search through the ranges in the cidr
88           object.  The sort is cached on the first call and used in
89           subsequent calls, but if more addresses are added to the cidr
90           object, prep_find() must be called on the cidr object.
91
92       $cidr->bin_find()
93           Same as find(), but forces a binary search. See also prep_find.
94
95       $cidr->prep_find()
96            $cidr->prep_find($num);
97
98           Caches the result of sorting the ip addresses. Implicitly called on
99           the first find call, but must be explicitly called if more
100           addresses are added to the cidr object. find() will do a binary
101           search if the number of ranges is greater than or equal to $num
102           (default 20);
103
104       $cidr->spanner()
105            $spanner = $cidr1->spanner($label1, $cidr2, $label2, ...);
106
107           Creates a spanner object to find out if multiple ip addresses are
108           within multiple labeled address ranges. May also be called as (with
109           or without any arguments):
110
111            Net::CIDR::Lite::Span->new($cidr1, $label1, $cidr2, $label2, ...);
112
113       $spanner->add()
114            $spanner->add($cidr1, $label1, $cidr2, $label2,...);
115
116           Adds labeled address ranges to the spanner object. The 'address
117           range' may be a Net::CIDR::Lite object, a single CIDR address
118           range, a single hyphenated IP address range, or a single IP
119           address.
120
121       $spanner->find()
122            $href = $spanner->find(@ip_addresses);
123
124           Look up which range(s) ip addresses are in, and return a lookup
125           table of the results, with the keys being the ip addresses, and the
126           value a hash reference of which address ranges the ip address is
127           in.
128
129       $spanner->bin_find()
130           Same as find(), but forces a binary search. See also prep_find.
131
132       $spanner->prep_find()
133            $spanner->prep_find($num);
134
135           Called implicitly the first time $spanner->find(..) is called, must
136           be called again if more cidr objects are added to the spanner
137           object. Will do a binary search if ratio of the number of ip
138           addresses to the number of ranges is less than $num percent
139           (default 4).
140
141       $spanner->clean()
142            $clean_address = $spanner->clean($ip_address);
143
144           Validates a returns a cleaned up version of an ip address (which is
145           what you will find as the key in the result from the
146           $spanner->find(..), not necessarily what the original argument
147           looked like). E.g. removes unnecessary leading zeros, removes null
148           blocks from IPv6 addresses, etc.
149

CAVEATS

151       Garbage in/garbage out. This module does do validation, but maybe not
152       enough to suit your needs.
153

AUTHOR

155       Douglas Wilson, <dougw@cpan.org> w/numerous hints and ideas borrowed
156       from Tye McQueen.
157

COPYRIGHT

159        This module is free software; you can redistribute it and/or
160        modify it under the same terms as Perl itself.
161