Package org.apache.commons.collections4.bloomfilter

# Class SparseBloomFilter

java.lang.Object
org.apache.commons.collections4.bloomfilter.SparseBloomFilter

All Implemented Interfaces:
  `BitMapProducer`, `BloomFilter`, `IndexProducer`

public final class SparseBloomFilter extends Object implements BloomFilter
A bloom filter using a TreeSet of integers to track enabled bits. This is a standard implementation and should work well for most low cardinality Bloom filters.

Since:
  4.5

- ## Field Summary

  ### Fields inherited from interface org.apache.commons.collections4.bloomfilter.BloomFilter

  `SPARSE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SparseBloomFilter(Shape shape)`
  Constructs an empty BitSetBloomFilter.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `long[]`
  `asBitMapArray()`
  Return a copy of the BitMapProducer data as a bit map array.
  `int`
  `cardinality()`
  Gets the cardinality (number of enabled bits) of this Bloom filter.
  `int`
  `characteristics()`
  Returns the characteristics of the filter.
  `void`
  `clear()`
  Resets the filter to its initial, unpopulated state.
  `boolean`
  `contains(BitMapProducer bitMapProducer)`
  Returns `true` if this filter contains the bits specified in the bit maps produced by the bitMapProducer.
  `boolean`
  `contains(IndexProducer indexProducer)`
  Returns `true` if this filter contains the indices specified IndexProducer.
  `SparseBloomFilter`
  `copy()`
  Creates a new instance of the BloomFilter with the same properties as the current one.
  `boolean`
  `forEachBitMap(LongPredicate consumer)`
  Each bit map is passed to the predicate in order.
  `boolean`
  `forEachIndex(IntPredicate consumer)`
  Each index is passed to the predicate.
  `Shape`
  `getShape()`
  Gets the shape that was used when the filter was built.
  `boolean`
  `isEmpty()`
  Determines if all the bits are off.
  `boolean`
  `merge(BitMapProducer bitMapProducer)`
  Merges the specified hasher into this Bloom filter.
  `boolean`
  `merge(BloomFilter other)`
  Merges the specified Bloom filter into this Bloom filter.
  `boolean`
  `merge(Hasher hasher)`
  Merges the specified hasher into this Bloom filter.
  `boolean`
  `merge(IndexProducer indexProducer)`
  Merges the specified IndexProducer into this Bloom filter.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.apache.commons.collections4.bloomfilter.BitMapProducer

  `forEachBitMapPair`

  ### Methods inherited from interface org.apache.commons.collections4.bloomfilter.BloomFilter

  `contains, contains, estimateIntersection, estimateN, estimateUnion, isFull, uniqueIndices`

  ### Methods inherited from interface org.apache.commons.collections4.bloomfilter.IndexProducer

  `asIndexArray`

- ## Constructor Details

  - ### SparseBloomFilter

    public SparseBloomFilter(Shape shape)
    Constructs an empty BitSetBloomFilter.
    Parameters:
      `shape` - The shape of the filter.

- ## Method Details

  - ### asBitMapArray

    public long[] asBitMapArray()
    Description copied from interface: `BitMapProducer`
    Return a copy of the BitMapProducer data as a bit map array.

    The default implementation of this method is slow. It is recommended that implementing classes reimplement this method.

    Specified by:
      `asBitMapArray` in interface `BitMapProducer`
    Returns:
      An array of bit map data.

  - ### cardinality

    public int cardinality()
    Description copied from interface: `BloomFilter`
    Gets the cardinality (number of enabled bits) of this Bloom filter.

    This is also known as the Hamming value or Hamming number.

    Specified by:
      `cardinality` in interface `BloomFilter`
    Returns:
      the cardinality of this filter

  - ### characteristics

    public int characteristics()
    Description copied from interface: `BloomFilter`
    Returns the characteristics of the filter.

    Characteristics are defined as bits within the characteristics integer.

    Specified by:
      `characteristics` in interface `BloomFilter`
    Returns:
      the characteristics for this bloom filter.

  - ### clear

    public void clear()
    Description copied from interface: `BloomFilter`
    Resets the filter to its initial, unpopulated state.
    Specified by:
      `clear` in interface `BloomFilter`

  - ### contains

    public boolean contains(BitMapProducer bitMapProducer)
    Description copied from interface: `BloomFilter`
    Returns `true` if this filter contains the bits specified in the bit maps produced by the bitMapProducer.
    Specified by:
      `contains` in interface `BloomFilter`
    Parameters:
      `bitMapProducer` - the `BitMapProducer` to provide the bit maps.
    Returns:
      `true` if this filter is enabled for all bits specified by the bit maps

  - ### contains

    public boolean contains(IndexProducer indexProducer)
    Description copied from interface: `BloomFilter`
    Returns `true` if this filter contains the indices specified IndexProducer.

    Specifically this returns `true` if this filter is enabled for all bit indexes identified by the `IndexProducer`.

    Specified by:
      `contains` in interface `BloomFilter`
    Parameters:
      `indexProducer` - the IndexProducer to provide the indexes
    Returns:
      `true` if this filter is enabled for all bits specified by the IndexProducer

  - ### copy

    public SparseBloomFilter copy()
    Description copied from interface: `BloomFilter`
    Creates a new instance of the BloomFilter with the same properties as the current one.
    Specified by:
      `copy` in interface `BloomFilter`
    Returns:
      a copy of this BloomFilter

  - ### forEachBitMap

    public boolean forEachBitMap(LongPredicate consumer)
    Description copied from interface: `BitMapProducer`
    Each bit map is passed to the predicate in order. The predicate is applied to each bit map value, if the predicate returns `false` the execution is stopped, `false` is returned, and no further bit maps are processed.

    If the producer is empty this method will return true.

    Any exceptions thrown by the action are relayed to the caller.

    Specified by:
      `forEachBitMap` in interface `BitMapProducer`
    Parameters:
      `consumer` - the function to execute
    Returns:
      `true` if all bit maps returned `true`, `false` otherwise.

  - ### forEachIndex

    public boolean forEachIndex(IntPredicate consumer)
    Description copied from interface: `IndexProducer`
    Each index is passed to the predicate. The predicate is applied to each index value, if the predicate returns `false` the execution is stopped, `false` is returned, and no further indices are processed.

    Any exceptions thrown by the action are relayed to the caller.

    Indices ordering and uniqueness is not guaranteed.

    Specified by:
      `forEachIndex` in interface `IndexProducer`
    Parameters:
      `consumer` - the action to be performed for each non-zero bit index.
    Returns:
      `true` if all indexes return true from consumer, `false` otherwise.

  - ### getShape

    public Shape getShape()
    Description copied from interface: `BloomFilter`
    Gets the shape that was used when the filter was built.
    Specified by:
      `getShape` in interface `BloomFilter`
    Returns:
      The shape the filter was built with.

  - ### isEmpty

    public boolean isEmpty()
    Description copied from interface: `BloomFilter`
    Determines if all the bits are off. This is equivalent to `cardinality() == 0`.

    Note: This method is optimised for non-sparse filters. Implementers are encouraged to implement faster checks if possible.

    Specified by:
      `isEmpty` in interface `BloomFilter`
    Returns:
      `true` if no bits are enabled, `false` otherwise.

  - ### merge

    public boolean merge(BitMapProducer bitMapProducer)
    Description copied from interface: `BloomFilter`
    Merges the specified hasher into this Bloom filter. Specifically all bit indexes that are identified by the `producer` will be enabled in this filter.

    Note: This method should return `true` even if no additional bit indexes were enabled. A `false` result indicates that this filter may or may not contain all the indexes enabled in the `producer`. This state may occur in complex Bloom filter implementations like counting Bloom filters.

    Specified by:
      `merge` in interface `BloomFilter`
    Parameters:
      `bitMapProducer` - The producer to merge.
    Returns:
      true if the merge was successful

  - ### merge

    public boolean merge(BloomFilter other)
    Description copied from interface: `BloomFilter`
    Merges the specified Bloom filter into this Bloom filter.

    Specifically all bit indexes that are identified by the `other` will be enabled in this filter.

    Note: This method should return `true` even if no additional bit indexes were enabled. A `false` result indicates that this filter may or may not contain the `other` Bloom filter. This state may occur in complex Bloom filter implementations like counting Bloom filters.

    Specified by:
      `merge` in interface `BloomFilter`
    Parameters:
      `other` - The bloom filter to merge into this one.
    Returns:
      true if the merge was successful

  - ### merge

    public boolean merge(Hasher hasher)
    Description copied from interface: `BloomFilter`
    Merges the specified hasher into this Bloom filter. Specifically all bit indexes that are identified by the `hasher` will be enabled in this filter.

    Note: This method should return `true` even if no additional bit indexes were enabled. A `false` result indicates that this filter may or may not contain the `hasher` values. This state may occur in complex Bloom filter implementations like counting Bloom filters.

    Specified by:
      `merge` in interface `BloomFilter`
    Parameters:
      `hasher` - The hasher to merge.
    Returns:
      true if the merge was successful

  - ### merge

    public boolean merge(IndexProducer indexProducer)
    Description copied from interface: `BloomFilter`
    Merges the specified IndexProducer into this Bloom filter. Specifically all bit indexes that are identified by the `producer` will be enabled in this filter.

    Note: This method should return `true` even if no additional bit indexes were enabled. A `false` result indicates that this filter may or may not contain all the indexes of the `producer`. This state may occur in complex Bloom filter implementations like counting Bloom filters.

    Specified by:
      `merge` in interface `BloomFilter`
    Parameters:
      `indexProducer` - The IndexProducer to merge.
    Returns:
      true if the merge was successful