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