List::B...rch::PP(3)

📦 version 0.25, in alpine 3.24

💅 okay so you've landed on the List::BinarySearch::PP(3) manual page — part of the User Contributed Perl Documentation situation, and the pure-Perl bestie of the binary search world. no cap, it's giving "backup plan that still slays." 💅

🌸 NAME 🌸

List::BinarySearch::PP — Pure-Perl Binary Search functions. That's literally the whole name vibe. 🎀

🎀 SYNOPSIS 🎀

This module is a plugin for List::BinarySearch, and it's here to give you a graceful fallback to a pure-Perl binary search implementation if the optional (but default) List::BinarySearch::XS dependency can't be built on a target system. It ships as part of the List::BinarySearch distribution. 🦋

Examples, bestie — copy these exactly:

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 ✨

So this module is intended to be used by List::BinarySearch, and it shouldn't need to be used directly in user-code. It's a supporting character, not the main character — unless you're specifically poking at the pure-Perl guts. 💅

It provides pure-Perl implementations of the binsearch and binsearch_pos functions for use by List::BinarySearch. For a full description of those functions, please refer to the documentation for List::BinarySearch. 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 — which is the default, and recommended. The pure-Perl functions exist as a graceful downgrade in case users aren't able to use XS modules. 😭

Bestie, this is a support module. List::BinarySearch is the one driving. 🚗

🧚 EXPORT 🧚

List::BinarySearch::PP exports by default binsearch and binsearch_pos. That's it. Those two. Slay. ✨

🔥 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, the return value is the lowest index of a matching element. If it isn't found, you get undef. No match, no index, just undef energy. 😭

🦋 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, the return value is the lowest index of a matching element. If it isn't found, you get the index of the best insertion point for the needle. It's giving "you're not here yet, but here's where you should go." 💅

🛠️ CONFIGURATION AND ENVIRONMENT 🛠️

Perl 5.8 or newer required. That's the requirement, bestie. ⭐

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. It's an internal bestie, not a direct-use situation. 🫶

🍓 DEPENDENCIES 🍓

Perl 5.8. That's the whole dependency list. Iconic. 🎀

💀 INCOMPATIBILITIES 💀

Perl versions prior to 5.8 aren't supported by this distribution. See the POD from List::BinarySearch for a more detailed explanation. Do not pass go with pre-5.8 Perl. 🙈

👑 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. He literally said email him. 🫶

💀 DIAGNOSTICS 💀

No diagnostics listed here, bestie. crickets. 🦗

🐛 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. That's the whole feedback loop, and it's lowkey iconic. 💅

🌈 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:

🧚 ACKNOWLEDGEMENTS 🧚

Shoutout to Mastering Algorithms with Perl at http://shop.oreilly.com/product/9781565923980.do, from O'Reilly at http://www.oreilly.com — much of the code behind the positional search came from there. Respect the source, bestie. 📖✨

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. Choose your license adventure. 💅

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

Okay bye bestie — List::B...rch::PP(3) is signing off with perl v5.42.2 and a 2026-02-15 timestamp. 💖✨

📦 where this page comes from