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

## Class NumberRangePrefixTree

- java.lang.Object
- - org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree
  - - org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree

- Direct Known Subclasses:
    `DateRangePrefixTree`

      public abstract class NumberRangePrefixTree
      extends SpatialPrefixTree

  A SpatialPrefixTree for single-dimensional numbers and number ranges of fixed precision values (not floating point). Despite its name, the indexed values (and queries) need not actually be ranges, they can be unit instance/values.

  Why might you use this instead of Lucene's built-in integer/long support? Here are some reasons with features based on code in this class, or are possible based on this class but require a subclass to fully realize it.

  - Index ranges, not just unit instances. This is especially useful when the requirement calls for a multi-valued range.
  - Instead of a fixed "precisionStep", this prefixTree can have a customizable number of child values for any prefix (up to 32768). This allows exact alignment of the prefix-tree with typical/expected values, which results in better performance. For example in a Date implementation, every month can get its own dedicated prefix, every day, etc., even though months vary in duration.
  - Arbitrary precision, like `BigDecimal`.
  - Standard Lucene integer/long indexing always indexes the full precision of those data types but this one is customizable.
  Unlike "normal" spatial components in this module, this special-purpose one only works with `Shape`s created by the methods on this class, not from any `SpatialContext`.
  See Also:
    `NumberRangePrefixTreeStrategy`, LUCENE-5648
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected class` | `NumberRangePrefixTree.NRCell` | Most of the PrefixTree implementation is in this one class, which is both the Cell, the CellIterator, and the Shape to reduce object allocation.
    `static interface` | `NumberRangePrefixTree.NRShape` | Base interface for `Shape`s this prefix tree supports.
    `class` | `NumberRangePrefixTree.SpanUnitsNRShape` | A range Shape; based on a pair of `NumberRangePrefixTree.UnitNRShape`.
    `static interface` | `NumberRangePrefixTree.UnitNRShape` | A unit value Shape implemented as a stack of numbers, one for each level in the prefix tree.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected int[]` | `levelByTermLen` |
    `protected int[]` | `maxSubCellsByLevel` |
    `protected int` | `maxTermLen` |
    `protected int[]` | `termLenByLevel` |

    - ### Fields inherited from class org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

      `ctx, maxLevels`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `NumberRangePrefixTree​(int[] maxSubCellsByLevel)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected static int` | `comparePrefix​(NumberRangePrefixTree.UnitNRShape a, NumberRangePrefixTree.UnitNRShape b)` | Compares a to b, returning less than 0, 0, or greater than 0, if a is less than, equal to, or greater than b, respectively, up to their common prefix (i.e.
    `double` | `getDistanceForLevel​(int level)` | Given a cell having the specified level, returns the distance from opposite corners.
    `int` | `getLevelForDistance​(double dist)` | Returns the level of the largest grid in which its longest side is less than or equal to the provided distance (in degrees).
    `int` | `getNumSubCells​(NumberRangePrefixTree.UnitNRShape lv)` | Returns the number of sub-cells beneath the given UnitNRShape.
    `Cell` | `getWorldCell()` | Returns the level 0 cell which encompasses all spatial data.
    `protected NumberRangePrefixTree.NRCell[]` | `newCellStack​(int levels)` |
    `NumberRangePrefixTree.NRShape` | `parseShape​(String str)` | Detects a range pattern and parses it, otherwise it's parsed as one shape via `parseUnitShape(String)`.
    `protected abstract NumberRangePrefixTree.UnitNRShape` | `parseUnitShape​(String str)` | Parse a String to a UnitNRShape.
    `Cell` | `readCell​(BytesRef term, Cell scratch)` | This creates a new Cell (or re-using `scratch` if provided), initialized to the state as read by the bytes.
    `abstract Object` | `toObject​(NumberRangePrefixTree.UnitNRShape shape)` | Converts a UnitNRShape shape to the corresponding type supported by this class, such as a Calendar/BigDecimal.
    `NumberRangePrefixTree.NRShape` | `toRangeShape​(NumberRangePrefixTree.UnitNRShape startUnit, NumberRangePrefixTree.UnitNRShape endUnit)` | Returns a shape that represents the continuous range between `start` and `end`.
    `protected NumberRangePrefixTree.UnitNRShape` | `toShape​(int[] valStack, int len)` |
    `String` | `toString()` |
    `protected abstract String` | `toString​(NumberRangePrefixTree.UnitNRShape lv)` | A string representation of the UnitNRShape that is parse-able by `parseUnitShape(String)`.
    `protected static String` | `toStringUnitRaw​(NumberRangePrefixTree.UnitNRShape lv)` |
    `abstract NumberRangePrefixTree.UnitNRShape` | `toUnitShape​(Object value)` | Converts the value to a unit shape.

    - ### Methods inherited from class org.apache.lucene.spatial.prefix.tree.SpatialPrefixTree

      `getMaxLevels, getSpatialContext, getTreeCellIterator`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### maxSubCellsByLevel

          protected final int[] maxSubCellsByLevel

    - #### termLenByLevel

          protected final int[] termLenByLevel

    - #### levelByTermLen

          protected final int[] levelByTermLen

    - #### maxTermLen

          protected final int maxTermLen

  - ### Constructor Detail

    - #### NumberRangePrefixTree

          protected NumberRangePrefixTree​(int[] maxSubCellsByLevel)

  - ### Method Detail

    - #### toUnitShape

          public abstract NumberRangePrefixTree.UnitNRShape toUnitShape​(Object value)

      Converts the value to a unit shape. Doesn't parse strings; see `parseShape(String)` for that. This is the reverse of `toObject(org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree.UnitNRShape)`.

    - #### toRangeShape

          public NumberRangePrefixTree.NRShape toRangeShape​(NumberRangePrefixTree.UnitNRShape startUnit,
                                                            NumberRangePrefixTree.UnitNRShape endUnit)

      Returns a shape that represents the continuous range between `start` and `end`. It will be normalized, and so sometimes a `NumberRangePrefixTree.UnitNRShape` will be returned, other times a `NumberRangePrefixTree.SpanUnitsNRShape` will be.
      Throws:
        `IllegalArgumentException` - if the arguments are in the wrong order, or if either contains the other (yet they aren't equal).

    - #### toObject

          public abstract Object toObject​(NumberRangePrefixTree.UnitNRShape shape)

      Converts a UnitNRShape shape to the corresponding type supported by this class, such as a Calendar/BigDecimal. This is the reverse of `toUnitShape(Object)`.

    - #### toString

          protected abstract String toString​(NumberRangePrefixTree.UnitNRShape lv)

      A string representation of the UnitNRShape that is parse-able by `parseUnitShape(String)`.

    - #### toStringUnitRaw

          protected static String toStringUnitRaw​(NumberRangePrefixTree.UnitNRShape lv)

    - #### parseShape

          public NumberRangePrefixTree.NRShape parseShape​(String str)
                                                   throws ParseException

      Detects a range pattern and parses it, otherwise it's parsed as one shape via `parseUnitShape(String)`. The range pattern looks like this BNF:

             '[' + parseShapeLV + ' TO ' + parseShapeLV + ']'

      It's the same thing as the toString() of the range shape, notwithstanding range optimization.
      Parameters:
        `str` - not null or empty
      Returns:
        not null
      Throws:
        `ParseException` - If there is a problem

    - #### parseUnitShape

          protected abstract NumberRangePrefixTree.UnitNRShape parseUnitShape​(String str)
                                                                       throws ParseException

      Parse a String to a UnitNRShape. "*" should be the full-range (level 0 shape).
      Throws:
        `ParseException`

    - #### comparePrefix

          protected static int comparePrefix​(NumberRangePrefixTree.UnitNRShape a,
                                             NumberRangePrefixTree.UnitNRShape b)

      Compares a to b, returning less than 0, 0, or greater than 0, if a is less than, equal to, or greater than b, respectively, up to their common prefix (i.e. only min(a.levels,b.levels) are compared).
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `SpatialPrefixTree`

    - #### getLevelForDistance

          public int getLevelForDistance​(double dist)

      Description copied from class: `SpatialPrefixTree`
      Returns the level of the largest grid in which its longest side is less than or equal to the provided distance (in degrees). Consequently `dist` acts as an error epsilon declaring the amount of detail needed in the grid, such that you can get a grid with just the right amount of precision.
      Specified by:
        `getLevelForDistance` in class `SpatialPrefixTree`
      Parameters:
        `dist` - `>= 0`
      Returns:
        level [1 to maxLevels]

    - #### getDistanceForLevel

          public double getDistanceForLevel​(int level)

      Description copied from class: `SpatialPrefixTree`
      Given a cell having the specified level, returns the distance from opposite corners. Since this might vary depending on where the cell is, this method may over-estimate.
      Specified by:
        `getDistanceForLevel` in class `SpatialPrefixTree`
      Parameters:
        `level` - [1 to maxLevels]
      Returns:
        `> 0`

    - #### toShape

          protected NumberRangePrefixTree.UnitNRShape toShape​(int[] valStack,
                                                              int len)

    - #### getWorldCell

          public Cell getWorldCell()

      Description copied from class: `SpatialPrefixTree`
      Returns the level 0 cell which encompasses all spatial data. Equivalent to `SpatialPrefixTree.readCell(BytesRef,Cell)` with no bytes.
      Specified by:
        `getWorldCell` in class `SpatialPrefixTree`

    - #### newCellStack

          protected NumberRangePrefixTree.NRCell[] newCellStack​(int levels)

    - #### readCell

          public Cell readCell​(BytesRef term,
                               Cell scratch)

      Description copied from class: `SpatialPrefixTree`
      This creates a new Cell (or re-using `scratch` if provided), initialized to the state as read by the bytes. Warning: An implementation may refer to the same byte array (no copy). If `Cell.setLeaf()` is subsequently called, it would then modify these bytes.
      Specified by:
        `readCell` in class `SpatialPrefixTree`

    - #### getNumSubCells

          public int getNumSubCells​(NumberRangePrefixTree.UnitNRShape lv)

      Returns the number of sub-cells beneath the given UnitNRShape.