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¶

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

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

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¶

Copyright 2013 David Oswald.

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.