org.apache.lucene.util

## Class LegacyNumericUtils

- java.lang.Object
- - org.apache.lucene.util.LegacyNumericUtils

- Deprecated.
  Please use `PointValues` instead.

      @Deprecated
      public final class LegacyNumericUtils
      extends Object

  This is a helper class to generate prefix-encoded representations for numerical values and supplies converters to represent float/double values as sortable integers/longs.

  To quickly execute range queries in Apache Lucene, a range is divided recursively into multiple intervals for searching: The center of the range is searched only with the lowest possible precision in the trie, while the boundaries are matched more exactly. This reduces the number of terms dramatically.

  This class generates terms to achieve this: First the numerical integer values need to be converted to bytes. For that integer values (32 bit or 64 bit) are made unsigned and the bits are converted to ASCII chars with each 7 bit. The resulting byte[] is sortable like the original integer value (even using UTF-8 sort order). Each value is also prefixed (in the first char) by the `shift` value (number of bits removed) used during encoding.

  For easy usage, the trie algorithm is implemented for indexing inside `LegacyNumericTokenStream` that can index `int`, `long`, `float`, and `double`. For querying, `LegacyNumericRangeQuery` implements the query part for the same data types.

  Since:
    2.9, API changed non backwards-compliant in 4.0
  NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `LegacyNumericUtils.IntRangeBuilder` Deprecated. Callback for `splitIntRange(org.apache.lucene.util.LegacyNumericUtils.IntRangeBuilder, int, int, int)`.
    `static class` | `LegacyNumericUtils.LongRangeBuilder` Deprecated. Callback for `splitLongRange(org.apache.lucene.util.LegacyNumericUtils.LongRangeBuilder, int, long, long)`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BUF_SIZE_INT` Deprecated. The maximum term length (used for `byte[]` buffer size) for encoding `int` values.
    `static int` | `BUF_SIZE_LONG` Deprecated. The maximum term length (used for `byte[]` buffer size) for encoding `long` values.
    `static int` | `PRECISION_STEP_DEFAULT` Deprecated. The default precision step used by `LegacyLongField`, `LegacyDoubleField`, `LegacyNumericTokenStream`, `LegacyNumericRangeQuery`.
    `static int` | `PRECISION_STEP_DEFAULT_32` Deprecated. The default precision step used by `LegacyIntField` and `LegacyFloatField`.
    `static byte` | `SHIFT_START_INT` Deprecated. Integers are stored at lower precision by shifting off lower bits.
    `static byte` | `SHIFT_START_LONG` Deprecated. Longs are stored at lower precision by shifting off lower bits.

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TermsEnum` | `filterPrefixCodedInts(TermsEnum termsEnum)` Deprecated. Filters the given `TermsEnum` by accepting only prefix coded 32 bit terms with a shift value of `0`.
    `static TermsEnum` | `filterPrefixCodedLongs(TermsEnum termsEnum)` Deprecated. Filters the given `TermsEnum` by accepting only prefix coded 64 bit terms with a shift value of `0`.
    `static Integer` | `getMaxInt(Terms terms)` Deprecated. Returns the maximum int value indexed into this numeric field or null if no terms exist.
    `static Long` | `getMaxLong(Terms terms)` Deprecated. Returns the maximum long value indexed into this numeric field or null if no terms exist.
    `static Integer` | `getMinInt(Terms terms)` Deprecated. Returns the minimum int value indexed into this numeric field or null if no terms exist.
    `static Long` | `getMinLong(Terms terms)` Deprecated. Returns the minimum long value indexed into this numeric field or null if no terms exist.
    `static int` | `getPrefixCodedIntShift(BytesRef val)` Deprecated. Returns the shift value from a prefix encoded `int`.
    `static int` | `getPrefixCodedLongShift(BytesRef val)` Deprecated. Returns the shift value from a prefix encoded `long`.
    `static void` | `intToPrefixCoded(int val, int shift, BytesRefBuilder bytes)` Deprecated. Returns prefix coded bits after reducing the precision by `shift` bits.
    `static void` | `longToPrefixCoded(long val, int shift, BytesRefBuilder bytes)` Deprecated. Returns prefix coded bits after reducing the precision by `shift` bits.
    `static int` | `prefixCodedToInt(BytesRef val)` Deprecated. Returns an int from prefixCoded bytes.
    `static long` | `prefixCodedToLong(BytesRef val)` Deprecated. Returns a long from prefixCoded bytes.
    `static void` | `splitIntRange(LegacyNumericUtils.IntRangeBuilder builder, int precisionStep, int minBound, int maxBound)` Deprecated. Splits an int range recursively.
    `static void` | `splitLongRange(LegacyNumericUtils.LongRangeBuilder builder, int precisionStep, long minBound, long maxBound)` Deprecated. Splits a long range recursively.

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

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

- - ### Field Detail

    - #### PRECISION_STEP_DEFAULT

          public static final int PRECISION_STEP_DEFAULT

      Deprecated.
      The default precision step used by `LegacyLongField`, `LegacyDoubleField`, `LegacyNumericTokenStream`, `LegacyNumericRangeQuery`.
      See Also:
        Constant Field Values

    - #### PRECISION_STEP_DEFAULT_32

          public static final int PRECISION_STEP_DEFAULT_32

      Deprecated.
      The default precision step used by `LegacyIntField` and `LegacyFloatField`.
      See Also:
        Constant Field Values

    - #### SHIFT_START_LONG

          public static final byte SHIFT_START_LONG

      Deprecated.
      Longs are stored at lower precision by shifting off lower bits. The shift count is stored as `SHIFT_START_LONG+shift` in the first byte
      See Also:
        Constant Field Values

    - #### BUF_SIZE_LONG

          public static final int BUF_SIZE_LONG

      Deprecated.
      The maximum term length (used for `byte[]` buffer size) for encoding `long` values.
      See Also:
        `longToPrefixCoded(long, int, org.apache.lucene.util.BytesRefBuilder)`, Constant Field Values

    - #### SHIFT_START_INT

          public static final byte SHIFT_START_INT

      Deprecated.
      Integers are stored at lower precision by shifting off lower bits. The shift count is stored as `SHIFT_START_INT+shift` in the first byte
      See Also:
        Constant Field Values

    - #### BUF_SIZE_INT

          public static final int BUF_SIZE_INT

      Deprecated.
      The maximum term length (used for `byte[]` buffer size) for encoding `int` values.
      See Also:
        `intToPrefixCoded(int, int, org.apache.lucene.util.BytesRefBuilder)`, Constant Field Values

  - ### Method Detail

    - #### longToPrefixCoded

          public static void longToPrefixCoded(long val,
                                               int shift,
                                               BytesRefBuilder bytes)

      Deprecated.
      Returns prefix coded bits after reducing the precision by `shift` bits. This is method is used by `LegacyNumericTokenStream`. After encoding, `bytes.offset` will always be 0.
      Parameters:
        `val` - the numeric value
        `shift` - how many bits to strip from the right
        `bytes` - will contain the encoded value

    - #### intToPrefixCoded

          public static void intToPrefixCoded(int val,
                                              int shift,
                                              BytesRefBuilder bytes)

      Deprecated.
      Returns prefix coded bits after reducing the precision by `shift` bits. This is method is used by `LegacyNumericTokenStream`. After encoding, `bytes.offset` will always be 0.
      Parameters:
        `val` - the numeric value
        `shift` - how many bits to strip from the right
        `bytes` - will contain the encoded value

    - #### getPrefixCodedLongShift

          public static int getPrefixCodedLongShift(BytesRef val)

      Deprecated.
      Returns the shift value from a prefix encoded `long`.
      Throws:
        `NumberFormatException` - if the supplied `BytesRef` is not correctly prefix encoded.

    - #### getPrefixCodedIntShift

          public static int getPrefixCodedIntShift(BytesRef val)

      Deprecated.
      Returns the shift value from a prefix encoded `int`.
      Throws:
        `NumberFormatException` - if the supplied `BytesRef` is not correctly prefix encoded.

    - #### prefixCodedToLong

          public static long prefixCodedToLong(BytesRef val)

      Deprecated.
      Returns a long from prefixCoded bytes. Rightmost bits will be zero for lower precision codes. This method can be used to decode a term's value.
      Throws:
        `NumberFormatException` - if the supplied `BytesRef` is not correctly prefix encoded.
      See Also:
        `longToPrefixCoded(long, int, org.apache.lucene.util.BytesRefBuilder)`

    - #### prefixCodedToInt

          public static int prefixCodedToInt(BytesRef val)

      Deprecated.
      Returns an int from prefixCoded bytes. Rightmost bits will be zero for lower precision codes. This method can be used to decode a term's value.
      Throws:
        `NumberFormatException` - if the supplied `BytesRef` is not correctly prefix encoded.
      See Also:
        `intToPrefixCoded(int, int, org.apache.lucene.util.BytesRefBuilder)`

    - #### splitLongRange

          public static void splitLongRange(LegacyNumericUtils.LongRangeBuilder builder,
                                            int precisionStep,
                                            long minBound,
                                            long maxBound)

      Deprecated.
      Splits a long range recursively. You may implement a builder that adds clauses to a `BooleanQuery` for each call to its `LegacyNumericUtils.LongRangeBuilder.addRange(BytesRef,BytesRef)` method.

      This method is used by `LegacyNumericRangeQuery`.

    - #### splitIntRange

          public static void splitIntRange(LegacyNumericUtils.IntRangeBuilder builder,
                                           int precisionStep,
                                           int minBound,
                                           int maxBound)

      Deprecated.
      Splits an int range recursively. You may implement a builder that adds clauses to a `BooleanQuery` for each call to its `LegacyNumericUtils.IntRangeBuilder.addRange(BytesRef,BytesRef)` method.

      This method is used by `LegacyNumericRangeQuery`.

    - #### filterPrefixCodedLongs

          public static TermsEnum filterPrefixCodedLongs(TermsEnum termsEnum)

      Deprecated.
      Filters the given `TermsEnum` by accepting only prefix coded 64 bit terms with a shift value of `0`.
      Parameters:
        `termsEnum` - the terms enum to filter
      Returns:
        a filtered `TermsEnum` that only returns prefix coded 64 bit terms with a shift value of `0`.

    - #### filterPrefixCodedInts

          public static TermsEnum filterPrefixCodedInts(TermsEnum termsEnum)

      Deprecated.
      Filters the given `TermsEnum` by accepting only prefix coded 32 bit terms with a shift value of `0`.
      Parameters:
        `termsEnum` - the terms enum to filter
      Returns:
        a filtered `TermsEnum` that only returns prefix coded 32 bit terms with a shift value of `0`.

    - #### getMinInt

          public static Integer getMinInt(Terms terms)
                                   throws IOException

      Deprecated.
      Returns the minimum int value indexed into this numeric field or null if no terms exist.
      Throws:
        `IOException`

    - #### getMaxInt

          public static Integer getMaxInt(Terms terms)
                                   throws IOException

      Deprecated.
      Returns the maximum int value indexed into this numeric field or null if no terms exist.
      Throws:
        `IOException`

    - #### getMinLong

          public static Long getMinLong(Terms terms)
                                 throws IOException

      Deprecated.
      Returns the minimum long value indexed into this numeric field or null if no terms exist.
      Throws:
        `IOException`

    - #### getMaxLong

          public static Long getMaxLong(Terms terms)
                                 throws IOException

      Deprecated.
      Returns the maximum long value indexed into this numeric field or null if no terms exist.
      Throws:
        `IOException`

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