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

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

# Class DateRangePrefixTree

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

public class DateRangePrefixTree extends NumberRangePrefixTree
A PrefixTree for date ranges in which the levels of the tree occur at natural periods of time (e.g. years, months, ...). You pass in `Calendar` objects with the desired fields set and the unspecified fields unset, which conveys the precision. The implementation makes some optimization assumptions about a `GregorianCalendar`; others could probably be supported easily.

Warning: If you construct a Calendar and then get something from the object like a field (e.g. year) or milliseconds, then every field is fully set by side-effect. So after setting the fields, pass it to this API first.

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

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree

  `NumberRangePrefixTree.NRCell, NumberRangePrefixTree.NRShape, NumberRangePrefixTree.SpanUnitsNRShape, NumberRangePrefixTree.UnitNRShape`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Calendar`
  `DEFAULT_CAL`
  The Java platform default `Calendar` with UTC & ROOT Locale.
  `static final Calendar`
  `JAVA_UTIL_TIME_COMPAT_CAL`
  A Calendar instance compatible with `ZonedDateTime` as seen from `GregorianCalendar.from(ZonedDateTime)`.

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

  `levelByTermLen, maxSubCellsByLevel, maxTermLen, termLenByLevel`

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

  `ctx, maxLevels`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DateRangePrefixTree(Calendar templateCal)`
  Constructs with the specified calendar used as a template to be cloned whenever a new Calendar needs to be created.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearFieldsAfter(Calendar cal, int field)`
  Calendar utility method: Calls `Calendar.clear(int)` for every field after `field`.
  `int`
  `getCalPrecisionField(Calendar cal)`
  Calendar utility method: Gets the Calendar field code of the last field that is set prior to an unset field.
  `int`
  `getNumSubCells(NumberRangePrefixTree.UnitNRShape lv)`
  Returns the number of sub-cells beneath the given UnitNRShape.
  `int`
  `getTreeLevelForCalendarField(int calField)`
  Calendar utility method: Returns the spatial prefix tree level for the corresponding `Calendar` field, such as `Calendar.YEAR`.
  `Calendar`
  `newCal()`
  Calendar utility method: Returns a clone of the `Calendar` passed to the constructor with all fields cleared.
  `Calendar`
  `parseCalendar(String str)`
  Calendar utility method: The reverse of `toString(java.util.Calendar)`.
  `protected NumberRangePrefixTree.UnitNRShape`
  `parseUnitShape(String str)`
  Parse a String to a UnitNRShape.
  `Calendar`
  `toCalendar(NumberRangePrefixTree.UnitNRShape lv)`
  Converts the `NumberRangePrefixTree.UnitNRShape` shape to a corresponding Calendar that is cleared below its level.
  `Object`
  `toObject(NumberRangePrefixTree.UnitNRShape shape)`
  Calls `toCalendar(org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree.UnitNRShape)`.
  `NumberRangePrefixTree.UnitNRShape`
  `toShape(Calendar cal)`
  Converts the Calendar into a Shape.
  `String`
  `toString(Calendar cal)`
  Calendar utility method consistent with `DateTimeFormatter.ISO_INSTANT` except has no trailing 'Z', and will be truncated to the units given according to `Calendar.isSet(int)`.
  `protected String`
  `toString(NumberRangePrefixTree.UnitNRShape lv)`
  A string representation of the UnitNRShape that is parse-able by `NumberRangePrefixTree.parseUnitShape(String)`.
  `NumberRangePrefixTree.UnitNRShape`
  `toUnitShape(Object value)`
  Converts `value` from a `Calendar` or `Date` to a `Shape`.

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

  `comparePrefix, getDistanceForLevel, getLevelForDistance, getWorldCell, newCellStack, parseShape, readCell, toRangeShape, toShape, toString, toStringUnitRaw`

  ### 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 Details

  - ### DEFAULT_CAL

    public static final Calendar DEFAULT_CAL
    The Java platform default `Calendar` with UTC & ROOT Locale. Generally a `GregorianCalendar`. Do not modify this!

  - ### JAVA_UTIL_TIME_COMPAT_CAL

    public static final Calendar JAVA_UTIL_TIME_COMPAT_CAL
    A Calendar instance compatible with `ZonedDateTime` as seen from `GregorianCalendar.from(ZonedDateTime)`. Do not modify this!

- ## Constructor Details

  - ### DateRangePrefixTree

    public DateRangePrefixTree(Calendar templateCal)
    Constructs with the specified calendar used as a template to be cloned whenever a new Calendar needs to be created. See `DEFAULT_CAL` and `JAVA_UTIL_TIME_COMPAT_CAL`.

- ## Method Details

  - ### getNumSubCells

    public int getNumSubCells(NumberRangePrefixTree.UnitNRShape lv)
    Description copied from class: `NumberRangePrefixTree`
    Returns the number of sub-cells beneath the given UnitNRShape.
    Overrides:
      `getNumSubCells` in class `NumberRangePrefixTree`

  - ### newCal

    public Calendar newCal()
    Calendar utility method: Returns a clone of the `Calendar` passed to the constructor with all fields cleared.

  - ### getTreeLevelForCalendarField

    public int getTreeLevelForCalendarField(int calField)
    Calendar utility method: Returns the spatial prefix tree level for the corresponding `Calendar` field, such as `Calendar.YEAR`. If there's no match, the next greatest level is returned as a negative value.

  - ### getCalPrecisionField

    public int getCalPrecisionField(Calendar cal)
    Calendar utility method: Gets the Calendar field code of the last field that is set prior to an unset field. It only examines fields relevant to the prefix tree. If no fields are set, it returns -1.

  - ### clearFieldsAfter

    public void clearFieldsAfter(Calendar cal, int field)
    Calendar utility method: Calls `Calendar.clear(int)` for every field after `field`. Beware of Calendar underflow.

  - ### toUnitShape

    public NumberRangePrefixTree.UnitNRShape toUnitShape(Object value)
    Converts `value` from a `Calendar` or `Date` to a `Shape`. Other arguments result in a `IllegalArgumentException`. If a Calendar is passed in, there might be problems if it is not created via `newCal()`.
    Specified by:
      `toUnitShape` in class `NumberRangePrefixTree`

  - ### toShape

    public NumberRangePrefixTree.UnitNRShape toShape(Calendar cal)
    Converts the Calendar into a Shape. The isSet() state of the Calendar is re-instated when done. If a Calendar is passed in, there might be problems if it is not created via `newCal()`.

  - ### toObject

    public Object toObject(NumberRangePrefixTree.UnitNRShape shape)
    Calls `toCalendar(org.apache.lucene.spatial.prefix.tree.NumberRangePrefixTree.UnitNRShape)`.
    Specified by:
      `toObject` in class `NumberRangePrefixTree`

  - ### toCalendar

    public Calendar toCalendar(NumberRangePrefixTree.UnitNRShape lv)
    Converts the `NumberRangePrefixTree.UnitNRShape` shape to a corresponding Calendar that is cleared below its level.

  - ### toString

    protected String toString(NumberRangePrefixTree.UnitNRShape lv)
    Description copied from class: `NumberRangePrefixTree`
    A string representation of the UnitNRShape that is parse-able by `NumberRangePrefixTree.parseUnitShape(String)`.
    Specified by:
      `toString` in class `NumberRangePrefixTree`

  - ### toString

    public String toString(Calendar cal)
    Calendar utility method consistent with `DateTimeFormatter.ISO_INSTANT` except has no trailing 'Z', and will be truncated to the units given according to `Calendar.isSet(int)`. A fully cleared calendar will yield the string "*". The isSet() state of the Calendar is re-instated when done.

  - ### parseUnitShape

    protected NumberRangePrefixTree.UnitNRShape parseUnitShape(String str) throws ParseException
    Description copied from class: `NumberRangePrefixTree`
    Parse a String to a UnitNRShape. "*" should be the full-range (level 0 shape).
    Specified by:
      `parseUnitShape` in class `NumberRangePrefixTree`
    Throws:
      `ParseException`

  - ### parseCalendar

    public Calendar parseCalendar(String str) throws ParseException
    Calendar utility method: The reverse of `toString(java.util.Calendar)`. It will only set the fields found, leaving the remainder in an un-set state. A leading '-' or '+' is optional (positive assumed), and a trailing 'Z' is also optional.
    Parameters:
      `str` - not null and not empty
    Returns:
      not null
    Throws:
      `ParseException`