Skip to content

Clarify BloomFilter semantics after invert and correct builder documentation #194

Description

@tisonkun

Three related BloomFilter contract/documentation issues should be resolved together:

  1. invert flips the backing bit array and therefore the resulting object no longer satisfies the normal Bloom-filter no-false-negative guarantee advertised at the type and module level.
  2. is_empty is documented in terms of inserted items, but after invert it only reports whether the backing bit array has zero set bits.
  3. BloomFilterBuilder::build documents a panic when neither accuracy nor size was configured, but that state is not constructible through the public API: the builder has no public default constructor and both public entry points initialize a valid configuration.

Design questions:

  • Should invert remain on the normal BloomFilter API, move to a raw/diagnostic API, or make the altered guarantee observable in the type/state?
  • Should is_empty retain a logical-stream meaning, be renamed to describe bit state, or document mode-dependent semantics?
  • Which module/type/method guarantees need a post-invert qualification?
  • Remove the unreachable build panic documentation and, if possible, encode the configured builder state more directly.

This issue intentionally excludes adding try_union/try_intersect; that is a separate fallibility/API-consistency decision.

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsImprovements or additions to documentationquestionFurther information is requested

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions