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

    All Methods Static Methods Concrete Methods
    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 boolean` | `nextDown​(byte[] bytes)` | Modify in-place the given bytes to the previous value of the same length that compares less than the current value.
    `static boolean` | `nextUp​(byte[] bytes)` | Modify in-place the given bytes to the next value of the same length that compares greater than the current value.
    `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 Detail

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

    - #### nextUp

          public static boolean nextUp​(byte[] bytes)

      Modify in-place the given bytes to the next value of the same length that compares greater than the current value. This returns false if, and only if, the value is currently equal to the maximum possible value.

    - #### nextDown

          public static boolean nextDown​(byte[] bytes)

      Modify in-place the given bytes to the previous value of the same length that compares less than the current value. This returns false if, and only if, the value is currently equal to the minimum possible value.

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