Package org.apache.commons.collections4.bloomfilter

# Interface CellProducer

All Superinterfaces:
  `IndexProducer`

All Known Subinterfaces:
  `CountingBloomFilter`

All Known Implementing Classes:
  `ArrayCountingBloomFilter`

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 CellProducer extends IndexProducer
Some Bloom filter implementations use a count rather than a bit flag. The term `Cell` is used to refer to these counts and their associated index. This class is the equivalent of the index producer except that it produces cells.

Note that a CellProducer must not return duplicate indices and must be ordered.

Implementations must guarantee that:

- The IndexProducer implementation returns unique ordered indices.
- The cells are produced in IndexProducer order.
- For every value produced by the IndexProducer there will be only one matching cell produced by the CellProducer.
- The CellProducer will not generate cells with indices that are not output by the IndexProducer.
- The IndexProducer will not generate indices that have a zero count for the cell.

Since:
  4.5

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `CellProducer.CellConsumer`
  Represents an operation that accepts an `<index, count>` pair.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `forEachCell(CellProducer.CellConsumer consumer)`
  Performs the given action for each `cell` where the cell count is non-zero.
  `default boolean`
  `forEachIndex(IntPredicate predicate)`
  The default implementation returns distinct and ordered indices for all cells with a non-zero count.
  `static CellProducer`
  `from(IndexProducer producer)`
  Creates a CellProducer from an IndexProducer.
  `default IndexProducer`
  `uniqueIndices()`
  Creates an IndexProducer comprising the unique indices for this producer.

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

  `asIndexArray`

- ## Method Details

  - ### from

    static CellProducer from(IndexProducer producer)
    Creates a CellProducer from an IndexProducer.

    Note the following properties:

    - Each index returned from the IndexProducer is assumed to have a cell value of 1.
    - The CellProducer aggregates duplicate indices from the IndexProducer.

    A CellProducer that outputs the mapping [(1,2),(2,3),(3,1)] can be created from many combinations of indices including:

         [1, 1, 2, 2, 2, 3]
         [1, 3, 1, 2, 2, 2]
         [3, 2, 1, 2, 1, 2]
         ...

    Parameters:
      `producer` - An index producer.
    Returns:
      A CellProducer with the same indices as the IndexProducer.

  - ### forEachCell

    boolean forEachCell(CellProducer.CellConsumer consumer)
    Performs the given action for each `cell` where the cell count is non-zero.

    Some Bloom filter implementations use a count rather than a bit flag. The term `Cell` is used to refer to these counts.

    Any exceptions thrown by the action are relayed to the caller. The consumer is applied to each cell. If the consumer returns `false` the execution is stopped, `false` is returned, and no further pairs are processed.

    Parameters:
      `consumer` - the action to be performed for each non-zero cell.
    Returns:
      `true` if all cells return true from consumer, `false` otherwise.
    Throws:
      `NullPointerException` - if the specified consumer is null

  - ### forEachIndex

    default boolean forEachIndex(IntPredicate predicate)
    The default implementation returns distinct and ordered indices for all cells with a non-zero count.
    Specified by:
      `forEachIndex` in interface `IndexProducer`
    Parameters:
      `predicate` - the action to be performed for each non-zero bit index.
    Returns:
      `true` if all indexes return true from consumer, `false` otherwise.

  - ### uniqueIndices

    default IndexProducer uniqueIndices()
    Description copied from interface: `IndexProducer`
    Creates an IndexProducer comprising the unique indices for this producer.

    By default creates a new producer with some overhead to remove duplicates. IndexProducers that return unique indices by default should override this to return `this`.

    The default implementation will filter the indices from this instance and return them in ascending order.

    Specified by:
      `uniqueIndices` in interface `IndexProducer`
    Returns:
      the IndexProducer of unique values.