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