com.bigdata.btree.keys
Class SuccessorUtil

java.lang.Object
  com.bigdata.btree.keys.SuccessorUtil

public class SuccessorUtil
extends Object

Utility methods for computing the successor of a value for various data types.

Version:

$Id: SuccessorUtil.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

See Also:

BytesUtil#successor(byte[]), which computes the successor of a variable length unsigned byte[].

TODO:

reconcile with the GOM SuccessorUtil., There is no successor method for UUID. This should be treated as a special case of a fixed length field. Handle as two longs. add 1 to the low order bits. on overflow add one to the high order bits. on overflow of the high order bits there is no successor.

Field Summary

static double	DNEG_MAX Largest negative double.
static double	DNEG_MIN Smallest non-zero negative value.
static double	DNEG_ONE Negative one (-1d).
static double	DNEG_ZERO Negative zero (-0d).
static double	DPOS_MAX Largest positive double.
static double	DPOS_MIN Smallest non-zero positive value.
static double	DPOS_ONE Positive one (1d).
static double	DPOS_ZERO Positive zero (+0d).
static float	FNEG_MAX Largest negative float.
static float	FNEG_MIN Smallest non-zero negative value.
static float	FNEG_ONE Negative one (-1f).
static float	FNEG_ZERO Negative zero (-0f).
static float	FPOS_MAX Largest positive float.
static float	FPOS_MIN Smallest non-zero positive value.
static float	FPOS_ONE Positive one (1f).
static float	FPOS_ZERO Positive zero (+0f).

Constructor Summary

SuccessorUtil()

Method Summary

static byte	successor(byte n) Computes the successor of a byte value.
static byte[]	successor(byte[] b) Modifies a byte[] as a side-effect so that it represents its successor when interpreted as a fixed length bit string.
static byte[]	successor(byte[] b, int off, int len) Modifies a byte[] as a side-effect so that it represents its successor when interpreted as a fixed length bit string.
static char	successor(char n) Computes the successor of a char value.
static double	successor(double d) Computes the successor of a double value.
static float	successor(float f) Computes the successor of a float value.
static int	successor(int n) Computes the successor of an int value.
static long	successor(long n) Computes the successor of a long value.
static short	successor(short n) Computes the successor of a short value.
static String	successor(String s) The successor of a string value is formed by appending a nul.

Methods inherited from class java.lang.Object

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

Field Detail

FPOS_ZERO

public static final float FPOS_ZERO

Positive zero (+0f).

Note: +0f and -0f will compare as _equal_ in the language. This means that you can not write tests that directly distinguish positive and negative zero using >, <, or ==.

FNEG_ZERO

public static final float FNEG_ZERO

Negative zero (-0f).

Note: +0f and -0f will compare as _equal_ in the language. This means that you can not write tests that directly distinguish positive and negative zero using >, <, or ==.

FPOS_MIN

public static final float FPOS_MIN

Smallest non-zero positive value.

FNEG_MIN

public static final float FNEG_MIN

Smallest non-zero negative value.

FPOS_ONE

public static final float FPOS_ONE

Positive one (1f).

See Also:

Constant Field Values

FNEG_ONE

public static final float FNEG_ONE

Negative one (-1f).

See Also:

Constant Field Values

FPOS_MAX

public static final float FPOS_MAX

Largest positive float.

See Also:

Constant Field Values

FNEG_MAX

public static final float FNEG_MAX

Largest negative float.

DPOS_ZERO

public static final double DPOS_ZERO

Positive zero (+0d).

Note: +0d and -0d will compare as _equal_ in the language. This means that you can not write tests that directly distinguish positive and negative zero using >, <, or ==.

DNEG_ZERO

public static final double DNEG_ZERO

Negative zero (-0d).

Note: +0d and -0d will compare as _equal_ in the language. This means that you can not write tests that directly distinguish positive and negative zero using >, <, or ==.

DPOS_MIN

public static final double DPOS_MIN

Smallest non-zero positive value.

DNEG_MIN

public static final double DNEG_MIN

Smallest non-zero negative value.

DPOS_ONE

public static final double DPOS_ONE

Positive one (1d).

See Also:

Constant Field Values

DNEG_ONE

public static final double DNEG_ONE

Negative one (-1d).

See Also:

Constant Field Values

DPOS_MAX

public static final double DPOS_MAX

Largest positive double.

See Also:

Constant Field Values

DNEG_MAX

public static final double DNEG_MAX

Largest negative double.

Constructor Detail

SuccessorUtil

public SuccessorUtil()

Method Detail

successor

public static byte successor(byte n)
                      throws NoSuccessorException

Computes the successor of a byte value.

Parameters:

n - A value

Returns:

The successor of that value.

Throws:

NoSuccessorException - if there is no successor for that value.

successor

public static char successor(char n)
                      throws NoSuccessorException

Computes the successor of a char value.

Parameters:

n - A value

Returns:

The successor of that value.

Throws:

NoSuccessorException - if there is no successor for that value.

successor

public static short successor(short n)
                       throws NoSuccessorException

Computes the successor of a short value.

Parameters:

n - A value

Returns:

The successor of that value.

Throws:

NoSuccessorException - if there is no successor for that value.

successor

public static int successor(int n)
                     throws NoSuccessorException

Computes the successor of an int value.

Parameters:

n - A value

Returns:

The successor of that value.

Throws:

NoSuccessorException - if there is no successor for that value.

successor

public static long successor(long n)
                      throws NoSuccessorException

Computes the successor of a long value.

Parameters:

n - A value

Returns:

The successor of that value.

Throws:

NoSuccessorException - if there is no successor for that value.

successor

public static float successor(float f)
                       throws NoSuccessorException

Computes the successor of a float value.

The IEEE floating point standard provides a means for computing the next larger or smaller floating point value using a bit manipulation trick. See Comparing floating point numbers by Bruce Dawson. The Java Float and Double clases provide the static methods required to convert a float or double into its IEEE 754 floating point bit layout, which can be treated as an int (for floats) or a long (for doubles). By testing for the sign, you can just add (or subtract) one (1) to get the bit pattern of the successor (see the above referenced article). Special exceptions must be made for NaNs, negative infinity and positive infinity.

Parameters:

f - The float value.

Returns:

The next value in the value space for float.

Throws:

NoSuccessorException - if there is no next value in the value space.

successor

public static double successor(double d)
                        throws NoSuccessorException

Computes the successor of a double value.

The IEEE floating point standard provides a means for computing the next larger or smaller floating point value using a bit manipulation trick. See Comparing floating point numbers by Bruce Dawson. The Java Float and Double clases provide the static methods required to convert a float or double into its IEEE 754 floating point bit layout, which can be treated as an int (for floats) or a long (for doubles). By testing for the sign, you can just add (or subtract) one (1) to get the bit pattern of the successor (see the above referenced article). Special exceptions must be made for NaNs, negative infinity and positive infinity.

Parameters:

d - The double value.

Returns:

The next value in the value space for double.

Throws:

NoSuccessorException - if there is no next value in the value space.

successor

public static String successor(String s)

The successor of a string value is formed by appending a nul. The successor of a null string reference is an empty string. The successor of a string value is defined unless the string is too long.

Parameters:

s - The string reference or null.

Returns:

The successor and never null

successor

public static byte[] successor(byte[] b)

Modifies a byte[] as a side-effect so that it represents its successor when interpreted as a fixed length bit string. The successor is formed by adding ONE (1) to the low byte and handling overflow.

Parameters:

b -

Returns:

b, which has been modified as a side-effect.

Throws:

NoSuccessorException - If all bytes overflow.

NoSuccessorException - If the byte[] has zero length.

successor

public static byte[] successor(byte[] b,
                               int off,
                               int len)

Modifies a byte[] as a side-effect so that it represents its successor when interpreted as a fixed length bit string. The successor is formed by adding ONE (1) to the low byte and handling overflow.

Parameters:

b - The byte[].

off - The offset of the start of the bitstring in the byte[].

len - The #of bytes in the bit string within the byte[].

Returns:

b, which has been modified as a side-effect.

Throws:

NoSuccessorException - If all bytes overflow.

NoSuccessorException - If the byte[] has zero length.

TODO:

unit tests when offset is non-zero.