Bloom::Filter(3pm)

💖 Bloom::Filter 💖

okay bestie, so this is Bloom::Filter, a page from section 3pm of the User Contributed Perl Documentation (yep, the perl crew's own little corner of the manual), and it's a whole sample Perl Bloom filter implementation. no cap, it's adorable and also genuinely useful.

---

✨ NAME ✨

Bloom::Filter — a sample Perl Bloom filter implementation. that's the whole name section, short king energy 💅

---

🌸 DESCRIPTION 🌸

okay so picture this: a Bloom filter is a probabilistic algorithm for doing existence tests in less memory than a full list of keys would require. the tradeoff?? a certain configurable risk of false positives 🫣 like yes she's cheap but sometimes she lies about knowing someone.

this module implements a simple Bloom filter with configurable capacity and false positive rate. Bloom filters were first described in a 1970 paper by Burton Bloom, see <http://portal.acm.org/citation.cfm?id=362692&dl=ACM&coll=portal>. 1970?? and still eating. iconic.

---

🦋 SYNOPSIS 🦋

the vibe, verbatim:

use Bloom::Filter

my $bf = Bloom::Filter->new( capacity => 10, error_rate => .001 );

$bf->add( @keys );

while ( <> ) {
        chomp;
        print "Found $_\n" if $bf->check( $_ );
}

like look at her go 🥹 construct, add, check. that's it. that's the whole personality.

---

🎀 CONSTRUCTORS 🎀

new %PARAMS

creates a brand new instance, fresh out the box, main character energy. the allowable params are error_rate and capacity. that's it bestie, those are the two knobs.

init

calculates the best number of hash functions and optimum filter length, creates some random salts, and generates a blank bit vector. also, it's called automatically by the constructor — so like, she shows up to the party without you even texting her 💅 no need to call it yourself.

---

💜 ACCESSORS 💜

these are the little getter besties, they just report the tea:

• capacity — returns the total capacity of the Bloom filter
• error_rate — returns the configured maximum error rate
• length — returns the length of the Bloom filter in bits
• key_count — returns the number of items currently stored in the filter
• on_bits — returns the number of 'on' bits in the filter
• salts — returns the list of salts used to create the hash functions

---

⭐ PUBLIC METHODS ⭐

add @KEYS

adds the list of keys to the filter. > heads up bestie: she will fail, return undef and complain if the number of keys in the filter exceeds the configured capacity. so don't overstuff her, she will literally text the group chat about it 😭

check @KEYS

checks the provided key list against the Bloom filter, and returns a list of equivalent length, with true or false values depending on whether there was a match. so like, one answer per key, in order. cute, consistent, no chaos. 🌈

---

🧚 INTERNAL METHODS 🧚

iykyk, these are the behind-the-scenes girlies. you probably don't touch them, but here they are anyway because we keep every detail in this house 🫶

_calculate_shortest_filter_length CAPACITY ERR_RATE

given a desired error rate and maximum capacity, returns the optimum combination of vector length (in bits) and number of hash functions to use in building the filter, where "optimum" means shortest vector length. she's giving efficiency queen. periodt.

_get_cells KEY

given a key, hashes it using the list of salts and returns an array of cell indexes corresponding to the key. little salt sprinkle, then boom, cell coordinates ✨

---

👑 AUTHOR 👑

originally written by Maciej Ceglowski <maciej@ceglowski.com>. currently maintained by Grzegorz Rożniecki <xaerxess@gmail.com>. legends, honestly.

---

🙈 CONTRIBUTORS 🙈

Dmitriy Ryaboy <dmitriy.ryaboy@ask.com> — big speedup in February 2007, thanks! big speedup?? in 2007?? we love a glow-up 💖

---

📜 COPYRIGHT AND LICENSE 📜

(c) 2004 Maciej Ceglowski

this is free software, distributed under version 2 of the GNU Public License (GPL). free as in go wild, bestie 🦋

---

and that's the whole page, no notes 💅

this little manual page is from the perl v5.40.1 era, dated 2025-08-15 — so like, she's fresh, she's documented, she's Bloom::Filter(3pm) and she ATE. mwah 🎀