NAME

List::BinarySearch::PP - Pure-Perl Binary Search functions.

SYNOPSIS

This module is a plugin for List::BinarySearch providing a graceful fallback to a pure-Perl binary search implementation in case the optional (but default) List::BinarySearch::XS dependency cannot be built on a target system. It is provided by the List::BinarySearch distribution.

Examples:

    use List::BinarySearch qw( binsearch  binsearch_pos  binsearch_range );

    # Find the lowest index of a matching element.
    $index = binsearch {$a <=> $b} 300, @{[ 100, 200, 300, 400 ]};
    $index = binsearch {$a cmp $b} 'Mozart', @{[ qw/ Bach Brahms Mozart / ]};
    $index = binsearch {$a <=> $b} 42, @{[ 10, 20, 30 ]}      # not found: undef

    # Find the lowest index of a matching element, or best insert point.
    $index = binsearch_pos {$a cmp $b} 'Chopin', @{[ qw/ Bach Brahms Mozart/ ]};  # Insert at [2].
    $index = binsearch_pos {$a <=> $b} 60, @{[ 10, 20, 30, 40, 50, 70 ]}; # Insert at [5].
    $index = binsearch_pos {$a <=> $b} 20, @{[ 10, 20, 30 ]}; # Matched at [1]

DESCRIPTION

This module is intended to be used by List::BinarySearch, and shouldn't need to be used directly in user-code.

This module provides pure-Perl implementations of the "binsearch" and "binsearch_pos" functions for use by List::BinarySearch. Please refer to the documentation for List::BinarySearch for a full description of those functions. What follows is a very brief overview.

These pure-Perl functions will be overridden by XS code when used via List::BinarySearch if List::BinarySearch::XS is installed (the default, and recommended). The pure-Perl functions exist as a gracefull downgrade in case users aren't able to use XS modules.

EXPORT

List::BinarySearch::PP exports by default "binsearch" and "binsearch_pos".

SUBROUTINES/METHODS

binsearch CODE NEEDLE ARRAY_HAYSTACK

    $first_found_ix = binsearch { $a cmp $b } $needle, @haystack;

Uses the supplied code block as a comparator to search for $needle within @haystack. If $needle is found, return value will be the lowest index of a matching element, or "undef" if the needle isn't found.

binsearch_pos CODE NEEDLE ARRAY_HAYSTACK

    $first_found_ix = binsearch_pos { $a cmp $b } $needle, @haystack;

Uses the supplied code block as a comparator to search for $needle within @haystack. If $needle is found, return value will be the lowest index of a matching element, or the index of the best insertion point for the needle if it isn't found.

CONFIGURATION AND ENVIRONMENT

Perl 5.8 or newer required. This module is part of the List::BinarySearch distribution, and is intended for use by the "List::BinarySearch" module. Though the user interface is unlikely to change, it shouldn't be directly used by code outside of this distribution.

DEPENDENCIES

Perl 5.8.

INCOMPATIBILITIES

Perl versions prior to 5.8 aren't supported by this distribution. See the POD from List::BinarySearch for a more detailed explanation.

AUTHOR

David Oswald, "<davido at cpan.org>"

If the documentation fails to answer your question, or if you have a comment or suggestion, send me an email.

DIAGNOSTICS

BUGS AND LIMITATIONS

Please report any bugs or feature requests to <https://github.com/daoswald/List-BinarySearch/issues>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc List::BinarySearch

This module is maintained in a public repo at Github. You may look for information at:

Github: Development is hosted on Github at:
<http://www.github.com/daoswald/List-BinarySearch>
GitHub Issue tracker (report bugs here)
<https://github.com/daoswald/List-BinarySearch/issues>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/List-BinarySearch>
CPAN Ratings
<http://cpanratings.perl.org/d/List-BinarySearch>
Search CPAN
<http://search.cpan.org/dist/List-BinarySearch/>

ACKNOWLEDGEMENTS

Mastering Algorithms with Perl <http://shop.oreilly.com/product/9781565923980.do>, from O'Reilly <http://www.oreilly.com>: much of the code behind the positional search.

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.