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
`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
`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
`protected` `NumberRangePrefixTree(int[] maxSubCellsByLevel)`

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
`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.