Package org.apache.commons.collections4.bloomfilter

# Interface BitMapProducer

All Known Subinterfaces:
  `BloomFilter`, `CountingBloomFilter`

All Known Implementing Classes:
  `ArrayCountingBloomFilter`, `LayeredBloomFilter`, `SimpleBloomFilter`, `SparseBloomFilter`, `WrappedBloomFilter`

Functional Interface:
  This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface public interface BitMapProducer
Produces bit map longs for a Bloom filter. Each bit map is a little-endian long value representing a block of bits of in a filter.

The returned array will have length `ceil(m / 64)` where `m` is the number of bits in the filter and `ceil` is the ceiling function. Bits 0-63 are in the first long. A value of 1 at a bit position indicates the bit index is enabled.

The default implementations of the `makePredicate()` and `asBitMapArray` methods are slow and should be reimplemented in the implementing classes where possible.

Since:
  4.5

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default long[]`
  `asBitMapArray()`
  Return a copy of the BitMapProducer data as a bit map array.
  `boolean`
  `forEachBitMap(LongPredicate predicate)`
  Each bit map is passed to the predicate in order.
  `default boolean`
  `forEachBitMapPair(BitMapProducer other, LongBiPredicate func)`
  Applies the `func` to each bit map pair in order.
  `static BitMapProducer`
  `fromBitMapArray(long... bitMaps)`
  Creates a BitMapProducer from an array of Long.
  `static BitMapProducer`
  `fromIndexProducer(IndexProducer producer, int numberOfBits)`
  Creates a BitMapProducer from an IndexProducer.

- ## Method Details

  - ### fromBitMapArray

    static BitMapProducer fromBitMapArray(long... bitMaps)
    Creates a BitMapProducer from an array of Long.
    Parameters:
      `bitMaps` - the bit maps to return.
    Returns:
      a BitMapProducer.

  - ### fromIndexProducer

    static BitMapProducer fromIndexProducer(IndexProducer producer, int numberOfBits)
    Creates a BitMapProducer from an IndexProducer.
    Parameters:
      `producer` - the IndexProducer that specifies the indexes of the bits to enable.
      `numberOfBits` - the number of bits in the Bloom filter.
    Returns:
      A BitMapProducer that produces the bit maps equivalent of the Indices from the producer.

  - ### asBitMapArray

    default long[] asBitMapArray()
    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.

    Returns:
      An array of bit map data.

  - ### forEachBitMap

    boolean forEachBitMap(LongPredicate predicate)
    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.

    Parameters:
      `predicate` - the function to execute
    Returns:
      `true` if all bit maps returned `true`, `false` otherwise.
    Throws:
      `NullPointerException` - if the specified consumer is null

  - ### forEachBitMapPair

    default boolean forEachBitMapPair(BitMapProducer other, LongBiPredicate func)
    Applies the `func` to each bit map pair in order. Will apply all of the bit maps from the other BitMapProducer to this producer. If this producer 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 BitMapProducer that have local arrays reimplement this method.

    Parameters:
      `other` - The other BitMapProducer that provides the y values in the (x,y) pair.
      `func` - The function to apply.
    Returns:
      A LongPredicate that tests this BitMapProducers bitmap values in order.