Package org.apache.commons.collections4.bloomfilter

# Class SimpleBloomFilter

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

All Implemented Interfaces:
  `BitMapExtractor`, `BloomFilter<SimpleBloomFilter>`, `IndexExtractor`

public final class SimpleBloomFilter extends Object implements BloomFilter<SimpleBloomFilter>
A bloom filter using an array of bit maps to track enabled bits. This is a standard implementation and should work well for most Bloom filters.

Since:
  4.5.0-M1

- ## Field Summary

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

  `SPARSE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SimpleBloomFilter(Shape shape)`
  Creates an empty instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `long[]`
  `asBitMapArray()`
  Return a copy of the BitMapExtractor data as a bit map array.
  `int`
  `cardinality()`
  Gets the cardinality (number of enabled bits) of this Bloom filter.
  `int`
  `characteristics()`
  Gets the characteristics of the filter.
  `void`
  `clear()`
  Clears the filter to by resetting it to its initial, unpopulated state.
  `boolean`
  `contains(IndexExtractor indexExtractor)`
  Returns `true` if this filter contains the indices specified IndexExtractor.
  `SimpleBloomFilter`
  `copy()`
  Creates a new instance of this `SimpleBloomFilter` with the same properties as the current one.
  `Shape`
  `getShape()`
  Gets the shape that was used when the filter was built.
  `boolean`
  `isEmpty()`
  Determines if all the bits are off.
  `boolean`
  `merge(BitMapExtractor bitMapExtractor)`
  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(IndexExtractor indexExtractor)`
  Merges the specified IndexExtractor into this Bloom filter.
  `boolean`
  `processBitMapPairs(BitMapExtractor other, LongBiPredicate func)`
  Applies the `func` to each bit map pair in order.
  `boolean`
  `processBitMaps(LongPredicate consumer)`
  Each bit map is passed to the predicate in order.
  `boolean`
  `processIndices(IntPredicate consumer)`
  Each index is passed to the predicate.

  ### 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.BloomFilter

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

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

  `asIndexArray`

- ## Constructor Details

  - ### SimpleBloomFilter

    public SimpleBloomFilter(Shape shape)
    Creates an empty instance.
    Parameters:
      `shape` - The shape for the filter.

- ## Method Details

  - ### asBitMapArray

    public long[] asBitMapArray()
    Description copied from interface: `BitMapExtractor`
    Return a copy of the BitMapExtractor 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 `BitMapExtractor`
    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<SimpleBloomFilter>`
    Returns:
      the cardinality of this filter

  - ### characteristics

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

    Characteristics are defined as bits within the characteristics integer.

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

  - ### clear

    public void clear()
    Description copied from interface: `BloomFilter`
    Clears the filter to by resetting it to its initial, unpopulated state.
    Specified by:
      `clear` in interface `BloomFilter<SimpleBloomFilter>`

  - ### contains

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

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

    Specified by:
      `contains` in interface `BloomFilter<SimpleBloomFilter>`
    Parameters:
      `indexExtractor` - the IndexExtractor to provide the indexes
    Returns:
      `true` if this filter is enabled for all bits specified by the IndexExtractor

  - ### copy

    public SimpleBloomFilter copy()
    Creates a new instance of this `SimpleBloomFilter` with the same properties as the current one.
    Specified by:
      `copy` in interface `BloomFilter<SimpleBloomFilter>`
    Returns:
      a copy of this `SimpleBloomFilter`.

  - ### 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<SimpleBloomFilter>`
    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<SimpleBloomFilter>`
    Returns:
      `true` if no bits are enabled, `false` otherwise.

  - ### merge

    public boolean merge(BitMapExtractor bitMapExtractor)
    Description copied from interface: `BloomFilter`
    Merges the specified hasher into this Bloom filter. Specifically all bit indexes that are identified by the `bitMapExtractor` 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 `bitMapExtractor`. This state may occur in complex Bloom filter implementations like counting Bloom filters.

    Specified by:
      `merge` in interface `BloomFilter<SimpleBloomFilter>`
    Parameters:
      `bitMapExtractor` - The BitMapExtractor 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<SimpleBloomFilter>`
    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<SimpleBloomFilter>`
    Parameters:
      `hasher` - The hasher to merge.
    Returns:
      true if the merge was successful

  - ### merge

    public boolean merge(IndexExtractor indexExtractor)
    Description copied from interface: `BloomFilter`
    Merges the specified IndexExtractor into this Bloom filter. Specifically all bit indexes that are identified by the `indexExtractor` 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 `indexExtractor`. This state may occur in complex Bloom filter implementations like counting Bloom filters.

    Specified by:
      `merge` in interface `BloomFilter<SimpleBloomFilter>`
    Parameters:
      `indexExtractor` - The IndexExtractor to merge.
    Returns:
      true if the merge was successful

  - ### processBitMapPairs

    public boolean processBitMapPairs(BitMapExtractor other, LongBiPredicate func)
    Description copied from interface: `BitMapExtractor`
    Applies the `func` to each bit map pair in order. Will apply all of the bit maps from the other BitMapExtractor to this extractor. If this extractor does not have as many bit maps it will provide 0 (zero) for all excess calls to the LongBiPredicate.

    The default implementation of this method uses `asBitMapArray()`. It is recommended that implementations of BitMapExtractor that have local arrays reimplement this method.

    Specified by:
      `processBitMapPairs` in interface `BitMapExtractor`
    Parameters:
      `other` - The other BitMapExtractor that provides the y values in the (x,y) pair.
      `func` - The function to apply.
    Returns:
      A LongPredicate that tests this BitMapExtractor's bitmap values in order.

  - ### processBitMaps

    public boolean processBitMaps(LongPredicate consumer)
    Description copied from interface: `BitMapExtractor`
    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 extractor is empty this method will return true.

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

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

  - ### processIndices

    public boolean processIndices(IntPredicate consumer)
    Description copied from interface: `IndexExtractor`
    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:
      `processIndices` in interface `IndexExtractor`
    Parameters:
      `consumer` - the action to be performed for each non-zero bit index.
    Returns:
      `true` if all indexes return true from consumer, `false` otherwise.