Cell (Lucene 10.5.0 spatial-extras API)
Description: declaration: package: org.apache.lucene.spatial.prefix.tree, interface: Cell

Package org.apache.lucene.spatial.prefix.tree

# Interface Cell

All Known Subinterfaces:
  `CellCanPrune`

All Known Implementing Classes:
  `LegacyCell`, `NumberRangePrefixTree.NRCell`, `PackedQuadPrefixTree.PackedQuadCell`, `QuadPrefixTree.QuadCell`

public interface Cell
Represents a grid cell. Cell instances are generally very transient and may be re-used internally. To get an instance, you could start with `SpatialPrefixTree.getWorldCell()`. And from there you could either traverse down the tree with `getNextLevelCells(org.locationtech.spatial4j.shape.Shape)`, or you could read an indexed term via `SpatialPrefixTree.readCell(org.apache.lucene.util.BytesRef,Cell)`. When a cell is read from a term, it is comprised of just the base bytes plus optionally a leaf flag.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `compareToNoLeaf(Cell fromCell)`
  Equivalent to `this.getTokenBytesNoLeaf(null).compareTo(fromCell.getTokenBytesNoLeaf(null))`.
  `int`
  `getLevel()`
  Level 0 is the world (and has no parent), from then on a higher level means a smaller cell than the level before it.
  `CellIterator`
  `getNextLevelCells(org.locationtech.spatial4j.shape.Shape shapeFilter)`
  Gets the cells at the next grid cell level underneath this one, optionally filtered by `shapeFilter`.
  `org.locationtech.spatial4j.shape.Shape`
  `getShape()`
  Gets the shape for this cell; typically a Rectangle.
  `org.locationtech.spatial4j.shape.SpatialRelation`
  `getShapeRel()`
  Gets the relationship this cell has with the shape from which it was filtered from, assuming it came from a `CellIterator`.
  `BytesRef`
  `getTokenBytesNoLeaf(BytesRef result)`
  Returns the bytes for this cell, without a leaf set.
  `BytesRef`
  `getTokenBytesWithLeaf(BytesRef result)`
  Returns the bytes for this cell, with a leaf byte if this is a leaf cell.
  `boolean`
  `isLeaf()`
  Some cells are flagged as leaves, which are indexed as such.
  `boolean`
  `isPrefixOf(Cell c)`
  Returns if the target term is within/underneath this cell; not necessarily a direct descendant.
  `void`
  `setLeaf()`
  Set this cell to be a leaf.
  `void`
  `setShapeRel(org.locationtech.spatial4j.shape.SpatialRelation rel)`
  See `getShapeRel()`.

- ## Method Details

  - ### getShapeRel

    org.locationtech.spatial4j.shape.SpatialRelation getShapeRel()
    Gets the relationship this cell has with the shape from which it was filtered from, assuming it came from a `CellIterator`. Arguably it belongs there but it's very convenient here.

  - ### setShapeRel

    void setShapeRel(org.locationtech.spatial4j.shape.SpatialRelation rel)
    See `getShapeRel()`.
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### isLeaf

    boolean isLeaf()
    Some cells are flagged as leaves, which are indexed as such. A leaf cell is either within some shape or it both intersects and the cell is at an accuracy threshold such that no smaller cells for the shape will be represented.

  - ### setLeaf

    void setLeaf()
    Set this cell to be a leaf. Warning: never call on a cell initialized to reference the same bytes from termsEnum, which should be treated as immutable. Note: not supported at level 0.
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### getTokenBytesWithLeaf

    BytesRef getTokenBytesWithLeaf(BytesRef result)
    Returns the bytes for this cell, with a leaf byte if this is a leaf cell. The result param is used to save object allocation, though its bytes aren't used.
    Parameters:
      `result` - where the result goes, or null to create new

  - ### getTokenBytesNoLeaf

    BytesRef getTokenBytesNoLeaf(BytesRef result)
    Returns the bytes for this cell, without a leaf set. The bytes should sort before `getTokenBytesWithLeaf(org.apache.lucene.util.BytesRef)`. The result param is used to save object allocation, though its bytes aren't used.
    Parameters:
      `result` - where the result goes, or null to create new

  - ### getLevel

    int getLevel()
    Level 0 is the world (and has no parent), from then on a higher level means a smaller cell than the level before it.

  - ### getNextLevelCells

    CellIterator getNextLevelCells(org.locationtech.spatial4j.shape.Shape shapeFilter)
    Gets the cells at the next grid cell level underneath this one, optionally filtered by `shapeFilter`. The returned cells should have `getShapeRel()` set to their relation with `shapeFilter`. In addition, for non-points `isLeaf()` must be true when that relation is WITHIN.

    IMPORTANT: Cells returned from this iterator can be shared, as well as the bytes.

    Precondition: Never called when getLevel() == maxLevel.

    Parameters:
      `shapeFilter` - an optional filter for the returned cells.
    Returns:
      A set of cells (no dups), sorted. Not Modifiable.

  - ### getShape

    org.locationtech.spatial4j.shape.Shape getShape()
    Gets the shape for this cell; typically a Rectangle.

  - ### isPrefixOf

    boolean isPrefixOf(Cell c)
    Returns if the target term is within/underneath this cell; not necessarily a direct descendant.
    Parameters:
      `c` - the term

  - ### compareToNoLeaf

    int compareToNoLeaf(Cell fromCell)
    Equivalent to `this.getTokenBytesNoLeaf(null).compareTo(fromCell.getTokenBytesNoLeaf(null))`.