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 DateRangePrefixTree` | `INSTANCE`

    - ### 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
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DateRangePrefixTree()`

  - ### Method Summary

    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 new `Calendar` in UTC TimeZone, ROOT Locale, 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: Formats the calendar to ISO-8601 format, to include proper BC handling (1BC is "0000", 2BC is "-0001", etc.); and WITHOUT a trailing 'Z'.
    `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

    - #### INSTANCE

          public static final DateRangePrefixTree INSTANCE

  - ### Constructor Detail

    - #### DateRangePrefixTree

          protected DateRangePrefixTree()

  - ### 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 new `Calendar` in UTC TimeZone, ROOT Locale, 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`.
      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.

    - #### 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: Formats the calendar to ISO-8601 format, to include proper BC handling (1BC is "0000", 2BC is "-0001", etc.); and WITHOUT a trailing 'Z'. 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-2017 Apache Software Foundation. All Rights Reserved.