Package org.apache.commons.collections4.bloomfilter

# Interface CellExtractor

All Superinterfaces:
  `IndexExtractor`

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 CellExtractor extends IndexExtractor
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 extractor except that it produces cells.

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

Implementations must guarantee that:

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

Since:
  4.5.0-M2

- ## Nested Class Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static CellExtractor`
  `from(IndexExtractor indexExtractor)`
  Creates a CellExtractor from an IndexExtractor.
  `boolean`
  `processCells(CellExtractor.CellPredicate consumer)`
  Performs the given action for each `cell` where the cell count is non-zero.
  `default boolean`
  `processIndices(IntPredicate predicate)`
  The default implementation returns distinct and ordered indices for all cells with a non-zero count.
  `default IndexExtractor`
  `uniqueIndices()`
  Creates an IndexExtractor comprising the unique indices for this extractor.

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

  `asIndexArray`

- ## Method Details

  - ### from

    static CellExtractor from(IndexExtractor indexExtractor)
    Creates a CellExtractor from an IndexExtractor.

    Note the following properties:

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

    A CellExtractor 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:
      `indexExtractor` - An index indexExtractor.
    Returns:
      A CellExtractor with the same indices as the IndexExtractor.

  - ### processCells

    boolean processCells(CellExtractor.CellPredicate 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

  - ### processIndices

    default boolean processIndices(IntPredicate predicate)
    The default implementation returns distinct and ordered indices for all cells with a non-zero count.
    Specified by:
      `processIndices` in interface `IndexExtractor`
    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 IndexExtractor uniqueIndices()
    Description copied from interface: `IndexExtractor`
    Creates an IndexExtractor comprising the unique indices for this extractor.

    By default creates a new extractor with some overhead to remove duplicates. IndexExtractors 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 `IndexExtractor`
    Returns:
      The IndexExtractor of unique values.