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

VERSION
    version 20140113

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
    *   Set::IntervalTree versions < 0.03 have a known bug where

        in_filter('128.0.0.0') will give a false positive if there are any
        ranges in the filter. 128.0.0.0 is 2^31. This is fixed in version
        0.03 onwards.

TODO
    *   Support for IPv6 Addresses. This would need a lot of work, as

        Set::IntervalTree uses long ints internally, and IPv6 needs 128-bit
        numbers.

SEE ALSO
    *   Config::IPFilter - Moose-based pure Perl IP address filter.

    *   Net::BitTorrent::Network::IPFilter - Moose-based pure Perl IP
        address filter.

    *   NET::IPFilter - Pure Perl extension for Accessing eMule / Bittorrent

        IPFilter.dat Files and checking a given IP against this ipfilter.dat
        IP Range.

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) 2014 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.