Dave Webb > Net-IPAddress-Filter-20121117 > Net::IPAddress::Filter

Download:
Net-IPAddress-Filter-20121117.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 20121117   Source   Latest Release: Net-IPAddress-Filter-20140113

NAME ^

Net::IPAddress::Filter - A compact and fast IP Address range filter

VERSION ^

version 20121117

SYNOPSIS ^

    my $filter = Net::IPAddress::Filter->new();

    #
    # Simple usage:
    #
    $filter->add_range('10.0.0.10', '10.0.0.50');
    $filter->add_range('192.168.1.1');
    print "In filter\n" if $filter->in_filter('10.0.0.25');

    #
    # CIDR syntax
    #
    $filter->add_range('172.168.0.0/24');
    # Equivalent to:
    $filter->add_range('172.168.0.0', '172.168.0.255');

    #
    # Annotated ranges
    #
    $filter->add_range_with_value('IANA-reserved range', '10.0.0.0', '10.255.255.255');
    my $array_ref = $filter->get_matches('10.128.0.0'); # [ 'IANA-reserved range' ]

DESCRIPTION ^

Net::IPAddress::Filter can be used to check if a given IP address is contained in a set of filtered ranges. A range can contain any number of addresses, and ranges can overlap.

Net::IPAddress::Filter uses the XS module Set::IntervalTree under the hood. An Interval Tree is a data structure optimised for fast insertions and searches of ranges, so sequential scans are avoided. The XS tree data structure is more compact than a pure Perl version of the same.

In testing on an AMD Athlon(tm) 64 X2 Dual Core Processor 4200+, Net::IPAddress::Filter did about 60k range inserts per second, and about 140k lookups per second. The process memory size grew by about 1MB per 10,000 ranges inserted.

METHODS ^

new ( )

Constructs new blank filter object.

Expects: None.

Returns: Blessed filter object.

add_range( )

Add a range of IP addresses to the filter.

The range can be specified in three ways.

    1) As a single IP address.

    2) As a pair of IP addresses.

    3) As a single IP address with a CIDR suffix. In this case, any second IP
    address passed in by the caller will be ignored.

Expects: $start_ip - A dotted quad IP address string with optional CIDR suffix. $end_ip - An optional dotted quad IP address string. Defaults to $start_ip.

Returns: 1 if it didn't die in the attempt - insert() returns undef.

add_range_with_value( )

Add a range of IP addresses to the filter, plus associate a scalar value with that range.

I couldn't think of a neat way to handle an optional value and an optional range end in the same method, otherwise I would have put this in add_range().

Expects: $value - A perl scalar to associate with this range. $start_ip - A dotted quad IP address string with optional CIDR suffix. $end_ip - An optional dotted quad IP address string. Defaults to $start_ip.

Returns: 1 if it didn't die in the attempt - insert() returns undef.

in_filter( )

Test whether a given IP address is in one of the ranges in the filter.

Expects: $test_ip - A dotted quad IP address string.

Returns: Number of ranges which span the test IP.

get_matches( )

Find any matching ranges for a given IP address. Each range holds a value field, and these values will be returned.

Expects: $test_ip - A dotted quad IP address string.

Returns: The value fields for any ranges spanning the test IP.

FUNCTIONS ^

_get_start_and_end_numbers( )

Utility function to convert the given IP addresses into numbers. It handles CIDR, and optional or out-of-order args.

Expects: $start_ip - A dotted quad IP address string with optional CIDR suffix. $end_ip - An optional dotted quad IP address string. Defaults to $start_ip.

Returns: Ordered pair of integers.

_ip_address_to_number( )

Utility function to convert a dotted quad IP address to a number.

TODO: Handle IPv6 addresses as well.

Expects: A dotted quad IP address string.

Returns: The integer representation of the IP address.

CAVEATS AND TIPS ^

TODO ^

SEE ALSO ^

BUGS OR FEATURE REQUESTS ^

See https://rt.cpan.org/Public/Dist/Display.html?Name=Net-IPAddress-Filter to report and view bugs, or to request features.

Alternatively, email bug-Net-IPAddress-Filter@rt.cpan.org

REPOSITORY ^

Net::IPAddress::Filter is hosted on github at https://github.com/d5ve/p5-Net-IPAddress-Filter.git

AUTHOR ^

Dave Webb <Net-IPAddress-Filter@d5ve.com>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2012 by Dave Webb.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: