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 and Description
    --- | ---
    `static Calendar` | `DEFAULT_CAL` The Java platform default `Calendar` with UTC & ROOT Locale.
    `static DateRangePrefixTree` | `INSTANCE` Deprecated.
    `static 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 and 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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 Detail

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

    - #### INSTANCE

          @Deprecated
          public static final DateRangePrefixTree INSTANCE

      Deprecated.
      An instanced based on `Calendar.getInstance(TimeZone, Locale)` with UTC and Locale.Root. This will (always?) be a `GregorianCalendar` with a so-called "Gregorian Change Date" of 1582.

  - ### Constructor Detail

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

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

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.