Skip to content

Deprecate BloomFilter.invert and add difference (A NOT B) - #768

Merged
leerho merged 1 commit into
apache:mainfrom
jaideeppyne:bloom-difference-deprecate-invert-766
Sep 17, 2026
Merged

leerho merged 1 commit into
apache:mainfrom
jaideeppyne:bloom-difference-deprecate-invert-766

Conversation

@jaideeppyne

Copy link
Copy Markdown
Contributor

Fixes #766.

Summary

BloomFilter.invert() flips the backing bit array but has no sound set-membership interpretation (see the issue). The only boolean composition involving inversion with a clean per-item meaning is A AND NOT B. This PR:

  1. Deprecates BloomFilter.invert() with a pointer to the replacement.
  2. Adds BloomFilter.difference(BloomFilter other) — bitwise AND-NOT (this &= ~other) with documented exact-exclusion / possible left-item-drop semantics.
  3. Adds package-private BitArray.andNot (Heap + Direct implementations; read-only throws), matching BitSet.andNot.

Aligns with the already-merged Rust change: apache/datasketches-rust#278. Wire format unchanged.

difference semantics

  • Items inserted into other always query false: excluded exactly.
  • Items inserted only into this filter are kept unless a hash position collides with other (unlike union / intersect, items can drop).
  • False positives for never-inserted items stay bounded by this filter's prior FPP.
  • null other is a no-op; incompatible filters throw (same as union/intersect).

Tests

  • BloomFilterTest: basic difference, self-difference clears, empty right is identity, incompatible difference; tightened deprecated inversionTest (inserted items are always absent after invert).
  • HeapBitArrayTest / DirectBitArrayTest: andNot happy path + length mismatch.
  • DirectBitArrayRTest: read-only andNot throws.

AI disclosure

I used Cursor / Grok to help draft the patch and open this PR via the GitHub API (no local clone). Semantics follow #766 and the merged Rust difference API.

invert() flips bits but has no sound set-membership reading; the only
composition with a clean per-item meaning is A AND NOT B. Add
BloomFilter.difference (bitwise AND-NOT), deprecate invert(), and mirror
the BitArray change as andNot. Aligns with datasketches-rust apache#278.

Fixes apache#766.

@leerho leerho left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for looking at this!
And fixing it!

@leerho
leerho merged commit 44c6201 into apache:main Sep 17, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BloomFilter.invert() has no sound set-membership semantics; consider an A NOT B operation instead

2 participants