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

Copyright © 2014. All Rights Reserved.