NumericUtils (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, class: NumericUtils

Package org.apache.lucene.util

# Class NumericUtils

java.lang.Object
org.apache.lucene.util.NumericUtils

public final class NumericUtils extends Object
Helper APIs to encode numeric values as sortable bytes and vice-versa.

To also index floating point numbers, this class supplies two methods to convert them to integer values by changing their bit layout: `doubleToSortableLong(double)`, `floatToSortableInt(float)`. You will have no precision loss by converting floating point numbers to integers and back (only that the integer form is not usable). Other data types like dates can easily converted to longs or ints (e.g. date to long: `Date.getTime()`).

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `add(int bytesPerDim, int dim, byte[] a, byte[] b, byte[] result)`
  Result = a + b, where a and b are unsigned.
  `static void`
  `bigIntToSortableBytes(BigInteger bigInt, int bigIntSize, byte[] result, int offset)`
  Encodes a BigInteger `value` such that unsigned byte order comparison is consistent with `BigInteger.compareTo(BigInteger)`.
  `static long`
  `doubleToSortableLong(double value)`
  Converts a `double` value to a sortable signed `long`.
  `static int`
  `floatToSortableInt(float value)`
  Converts a `float` value to a sortable signed `int`.
  `static void`
  `intToSortableBytes(int value, byte[] result, int offset)`
  Encodes an integer `value` such that unsigned byte order comparison is consistent with `Integer.compare(int, int)`
  `static void`
  `longToSortableBytes(long value, byte[] result, int offset)`
  Encodes an long `value` such that unsigned byte order comparison is consistent with `Long.compare(long, long)`
  `static BigInteger`
  `sortableBytesToBigInt(byte[] encoded, int offset, int length)`
  Decodes a BigInteger value previously written with `bigIntToSortableBytes(java.math.BigInteger, int, byte[], int)`
  `static int`
  `sortableBytesToInt(byte[] encoded, int offset)`
  Decodes an integer value previously written with `intToSortableBytes(int, byte[], int)`
  `static long`
  `sortableBytesToLong(byte[] encoded, int offset)`
  Decodes a long value previously written with `longToSortableBytes(long, byte[], int)`
  `static long`
  `sortableDoubleBits(long bits)`
  Converts IEEE 754 representation of a double to sortable order (or back to the original)
  `static int`
  `sortableFloatBits(int bits)`
  Converts IEEE 754 representation of a float to sortable order (or back to the original)
  `static float`
  `sortableIntToFloat(int encoded)`
  Converts a sortable `int` back to a `float`.
  `static double`
  `sortableLongToDouble(long encoded)`
  Converts a sortable `long` back to a `double`.
  `static void`
  `subtract(int bytesPerDim, int dim, byte[] a, byte[] b, byte[] result)`
  Result = a - b, where a >= b, else `IllegalArgumentException` is thrown.

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

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

- ## Method Details

  - ### doubleToSortableLong

    public static long doubleToSortableLong(double value)
    Converts a `double` value to a sortable signed `long`. The value is converted by getting their IEEE 754 floating-point "double format" bit layout and then some bits are swapped, to be able to compare the result as long. By this the precision is not reduced, but the value can easily used as a long. The sort order (including `Double.NaN`) is defined by `Double.compareTo(java.lang.Double)`; `NaN` is greater than positive infinity.
    See Also:
      - `sortableLongToDouble(long)`

  - ### sortableLongToDouble

    public static double sortableLongToDouble(long encoded)
    Converts a sortable `long` back to a `double`.
    See Also:
      - `doubleToSortableLong(double)`

  - ### floatToSortableInt

    public static int floatToSortableInt(float value)
    Converts a `float` value to a sortable signed `int`. The value is converted by getting their IEEE 754 floating-point "float format" bit layout and then some bits are swapped, to be able to compare the result as int. By this the precision is not reduced, but the value can easily used as an int. The sort order (including `Float.NaN`) is defined by `Float.compareTo(java.lang.Float)`; `NaN` is greater than positive infinity.
    See Also:
      - `sortableIntToFloat(int)`

  - ### sortableIntToFloat

    public static float sortableIntToFloat(int encoded)
    Converts a sortable `int` back to a `float`.
    See Also:
      - `floatToSortableInt(float)`

  - ### sortableDoubleBits

    public static long sortableDoubleBits(long bits)
    Converts IEEE 754 representation of a double to sortable order (or back to the original)

  - ### sortableFloatBits

    public static int sortableFloatBits(int bits)
    Converts IEEE 754 representation of a float to sortable order (or back to the original)

  - ### subtract

    public static void subtract(int bytesPerDim, int dim, byte[] a, byte[] b, byte[] result)
    Result = a - b, where a >= b, else `IllegalArgumentException` is thrown.

  - ### add

    public static void add(int bytesPerDim, int dim, byte[] a, byte[] b, byte[] result)
    Result = a + b, where a and b are unsigned. If there is an overflow, `IllegalArgumentException` is thrown.

  - ### intToSortableBytes

    public static void intToSortableBytes(int value, byte[] result, int offset)
    Encodes an integer `value` such that unsigned byte order comparison is consistent with `Integer.compare(int, int)`
    See Also:
      - `sortableBytesToInt(byte[], int)`

  - ### sortableBytesToInt

    public static int sortableBytesToInt(byte[] encoded, int offset)
    Decodes an integer value previously written with `intToSortableBytes(int, byte[], int)`
    See Also:
      - `intToSortableBytes(int, byte[], int)`

  - ### longToSortableBytes

    public static void longToSortableBytes(long value, byte[] result, int offset)
    Encodes an long `value` such that unsigned byte order comparison is consistent with `Long.compare(long, long)`
    See Also:
      - `sortableBytesToLong(byte[], int)`

  - ### sortableBytesToLong

    public static long sortableBytesToLong(byte[] encoded, int offset)
    Decodes a long value previously written with `longToSortableBytes(long, byte[], int)`
    See Also:
      - `longToSortableBytes(long, byte[], int)`

  - ### bigIntToSortableBytes

    public static void bigIntToSortableBytes(BigInteger bigInt, int bigIntSize, byte[] result, int offset)
    Encodes a BigInteger `value` such that unsigned byte order comparison is consistent with `BigInteger.compareTo(BigInteger)`. This also sign-extends the value to `bigIntSize` bytes if necessary: useful to create a fixed-width size.
    See Also:
      - `sortableBytesToBigInt(byte[], int, int)`

  - ### sortableBytesToBigInt

    public static BigInteger sortableBytesToBigInt(byte[] encoded, int offset, int length)
    Decodes a BigInteger value previously written with `bigIntToSortableBytes(java.math.BigInteger, int, byte[], int)`
    See Also:
      - `bigIntToSortableBytes(BigInteger, int, byte[], int)`