com.h3c.util

Class PrimitiveUtils

java.lang.Object

com.h3c.util.PrimitiveUtils

public final class PrimitiveUtils
extends Object

Provides useful methods regarding primitives.

Some protocols deal with unsigned values; for example, u8 (or uint8_t in C/C++) refers to an unsigned 8-bit value. Java does not provide unsigned primitives, so some care needs to be taken when dealing with such values in Java.

As an example, consider the following 8-bit value:

     10010011
 

Interpreted as an unsigned value (u8) this represents 147. A Java byte can hold an 8-bit value, but Java bytes are signed (the most significant bit is the sign-bit) so this same collection of bits, stored in a byte, represents -109.

To interpret a u8 value correctly, it needs to be stored in the "next size up" primitve (short) so that all 8 bits are unsigned:

     0000000010010011
     ^
     sign bit
 

This short value represents 147.

The fromU*() methods in this class treat their parameter as an unsigned number and return the equivalent unsigned value in the "next size up" primitive. The toU* methods in this class treat their parameter as an unsigned number and return the equivalent value "encoded" in the "next size down" primitive.

Method Summary

Methods

Modifier and Type	Method and Description
static int	fromU16(short s) Convert the short equivalent of an unsigned 16-bit field to an int.
static long	fromU32(int i) Convert the int equivalent of an unsigned 32-bit field to a long.
static BigInteger	fromU64(long l) Convert the long equivalent of an unsigned 64-bit field to a BigInteger.
static short	fromU8(byte b) Convert the byte equivalent of an unsigned 8-bit field to a short.
static short	toU16(int uv) Convert the given value to the short equivalent of an unsigned 16-bit field.
static int	toU32(long uv) Convert the given value to the int equivalent of an unsigned 32-bit field.
static long	toU64(BigInteger uv) Convert the given value to the long equivalent of an unsigned 64-bit field.
static byte	toU8(int uv) Convert the given value to the byte equivalent of an unsigned 8-bit field.
static byte	toU8(short uv) Convert the given value to the byte equivalent of an unsigned 8-bit field.
static void	verifyU16(int uv) Verifies that the given value will fit in an unsigned 16-bit field.
static void	verifyU32(long uv) Verifies that the given value will fit in an unsigned 32-bit field.
static void	verifyU64(BigInteger uv) Verifies that the given value will fit in an unsigned 64-bit field.
static void	verifyU8(int uv) Verifies that the given value will fit in an unsigned 8-bit field.
static void	verifyU8(short uv) Verifies that the given value will fit in an unsigned 8-bit field.

Methods inherited from class java.lang.Object

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

Method Detail

fromU8

public static short fromU8(byte b)

Convert the byte equivalent of an unsigned 8-bit field to a short.

Parameters:

b - a byte

Returns:

unsigned value

verifyU8

public static void verifyU8(short uv)

Verifies that the given value will fit in an unsigned 8-bit field. If it will, this method silently returns; if not, an exception is thrown.

Parameters:

uv - unsigned value

Throws:

IllegalArgumentException - if uv is not 0..2^8-1

toU8

public static byte toU8(short uv)

Convert the given value to the byte equivalent of an unsigned 8-bit field.

Parameters:

uv - unsigned value

Returns:

encoded byte

Throws:

IllegalArgumentException - if uv is not 0..2^8-1

verifyU8

public static void verifyU8(int uv)

Verifies that the given value will fit in an unsigned 8-bit field. If it will, this method silently returns; if not, an exception is thrown.

Parameters:

uv - unsigned value

Throws:

IllegalArgumentException - if uv is not 0..2^8-1

toU8

public static byte toU8(int uv)

Convert the given value to the byte equivalent of an unsigned 8-bit field.

Parameters:

uv - unsigned value

Returns:

encoded byte

Throws:

IllegalArgumentException - if uv is not 0..2^8-1

fromU16

public static int fromU16(short s)

Convert the short equivalent of an unsigned 16-bit field to an int.

Parameters:

s - a short

Returns:

unsigned value

verifyU16

public static void verifyU16(int uv)

Verifies that the given value will fit in an unsigned 16-bit field. If it will, this method silently returns; if not, an exception is thrown.

Parameters:

uv - unsigned value

Throws:

IllegalArgumentException - if uv is not 0..2^16-1

toU16

public static short toU16(int uv)

Convert the given value to the short equivalent of an unsigned 16-bit field.

Parameters:

uv - unsigned value

Returns:

encoded short

Throws:

IllegalArgumentException - if uv is not 0..2^16-1

fromU32

public static long fromU32(int i)

Convert the int equivalent of an unsigned 32-bit field to a long.

Parameters:

i - an int

Returns:

unsigned value

verifyU32

public static void verifyU32(long uv)

Verifies that the given value will fit in an unsigned 32-bit field. If it will, this method silently returns; if not, an exception is thrown.

Parameters:

uv - unsigned value

Throws:

IllegalArgumentException - if uv is not 0..2^32-1

toU32

public static int toU32(long uv)

Convert the given value to the int equivalent of an unsigned 32-bit field.

Parameters:

uv - unsigned value

Returns:

encoded int

Throws:

IllegalArgumentException - if uv is not 0..2^32-1

fromU64

public static BigInteger fromU64(long l)

Convert the long equivalent of an unsigned 64-bit field to a BigInteger.

Parameters:

l - a long

Returns:

unsigned value

verifyU64

public static void verifyU64(BigInteger uv)

Verifies that the given value will fit in an unsigned 64-bit field. If it will, this method silently returns; if not, an exception is thrown.

Parameters:

uv - unsigned value

Throws:

IllegalArgumentException - if uv is not 0..2^64-1

toU64

public static long toU64(BigInteger uv)

Convert the given value to the long equivalent of an unsigned 64-bit field.

Parameters:

uv - unsigned value

Returns:

encoded long

Throws:

IllegalArgumentException - if uv is not 0..2^64-1