UnsignedBytes
Date: 2016-05-24

com.google.common.primitives

## Class UnsignedBytes

- java.lang.Object
- - com.google.common.primitives.UnsignedBytes

-     public final class UnsignedBytes
      extends java.lang.Object

  Static utility methods pertaining to `byte` primitives that interpret values as unsigned (that is, any negative value `b` is treated as the positive value `256 + b`). The corresponding methods that treat the values as signed are found in `SignedBytes`, and the methods for which signedness is not an issue are in `Bytes`.

  See the Guava User Guide article on primitive utilities.

  Since:
    1.0

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte` | `MAX_POWER_OF_TWO` The largest power of two that can be represented as an unsigned `byte`.
    `static byte` | `MAX_VALUE` The largest value that fits into an unsigned byte.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static byte` | `checkedCast(long value)` Returns the `byte` value that, when treated as unsigned, is equal to `value`, if possible.
    `static int` | `compare(byte a, byte b)` Compares the two specified `byte` values, treating them as unsigned values between 0 and 255 inclusive.
    `static java.lang.String` | `join(java.lang.String separator, byte... array)` Returns a string containing the supplied `byte` values separated by `separator`.
    `static java.util.Comparator<byte[]>` | `lexicographicalComparator()` Returns a comparator that compares two `byte` arrays lexicographically.
    `static byte` | `max(byte... array)` Returns the greatest value present in `array`.
    `static byte` | `min(byte... array)` Returns the least value present in `array`.
    `static byte` | `parseUnsignedByte(java.lang.String string)` Returns the unsigned `byte` value represented by the given decimal string.
    `static byte` | `parseUnsignedByte(java.lang.String string, int radix)` Returns the unsigned `byte` value represented by a string with the given radix.
    `static byte` | `saturatedCast(long value)` Returns the `byte` value that, when treated as unsigned, is nearest in value to `value`.
    `static int` | `toInt(byte value)` Returns the value of the given byte as an integer, when treated as unsigned.
    `static java.lang.String` | `toString(byte x)` Returns a string representation of x, where x is treated as unsigned.
    `static java.lang.String` | `toString(byte x, int radix)` Returns a string representation of `x` for the given radix, where `x` is treated as unsigned.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### MAX_POWER_OF_TWO

          public static final byte MAX_POWER_OF_TWO

      The largest power of two that can be represented as an unsigned `byte`.
      Since:
        10.0
      See Also:
        Constant Field Values

    - #### MAX_VALUE

          public static final byte MAX_VALUE

      The largest value that fits into an unsigned byte.
      Since:
        13.0
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### toInt

          @CheckReturnValue
          public static int toInt(byte value)

      Returns the value of the given byte as an integer, when treated as unsigned. That is, returns `value + 256` if `value` is negative; `value` itself otherwise.
      Since:
        6.0

    - #### checkedCast

          public static byte checkedCast(long value)

      Returns the `byte` value that, when treated as unsigned, is equal to `value`, if possible.
      Parameters:
        `value` - a value between 0 and 255 inclusive
      Returns:
        the `byte` value that, when treated as unsigned, equals `value`
      Throws:
        `java.lang.IllegalArgumentException` - if `value` is negative or greater than 255

    - #### saturatedCast

          public static byte saturatedCast(long value)

      Returns the `byte` value that, when treated as unsigned, is nearest in value to `value`.
      Parameters:
        `value` - any `long` value
      Returns:
        `(byte) 255` if `value >= 255`, `(byte) 0` if `value <= 0`, and `value` cast to `byte` otherwise

    - #### compare

          @CheckReturnValue
          public static int compare(byte a,
                                     byte b)

      Compares the two specified `byte` values, treating them as unsigned values between 0 and 255 inclusive. For example, `(byte) -127` is considered greater than `(byte) 127` because it is seen as having the value of positive `129`.
      Parameters:
        `a` - the first `byte` to compare
        `b` - the second `byte` to compare
      Returns:
        a negative value if `a` is less than `b`; a positive value if `a` is greater than `b`; or zero if they are equal

    - #### min

          @CheckReturnValue
          public static byte min(byte... array)

      Returns the least value present in `array`.
      Parameters:
        `array` - a nonempty array of `byte` values
      Returns:
        the value present in `array` that is less than or equal to every other value in the array
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is empty

    - #### max

          @CheckReturnValue
          public static byte max(byte... array)

      Returns the greatest value present in `array`.
      Parameters:
        `array` - a nonempty array of `byte` values
      Returns:
        the value present in `array` that is greater than or equal to every other value in the array
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is empty

    - #### toString

          @Beta
          @CheckReturnValue
          public static java.lang.String toString(byte x)

      Returns a string representation of x, where x is treated as unsigned.
      Since:
        13.0

    - #### toString

          @Beta
          @CheckReturnValue
          public static java.lang.String toString(byte x,
                                                        int radix)

      Returns a string representation of `x` for the given radix, where `x` is treated as unsigned.
      Parameters:
        `x` - the value to convert to a string.
        `radix` - the radix to use while working with `x`
      Throws:
        `java.lang.IllegalArgumentException` - if `radix` is not between `Character.MIN_RADIX` and `Character.MAX_RADIX`.
      Since:
        13.0

    - #### parseUnsignedByte

          @Beta
          public static byte parseUnsignedByte(java.lang.String string)

      Returns the unsigned `byte` value represented by the given decimal string.
      Throws:
        `java.lang.NumberFormatException` - if the string does not contain a valid unsigned `byte` value
        `java.lang.NullPointerException` - if `s` is null (in contrast to `Byte.parseByte(String)`)
      Since:
        13.0

    - #### parseUnsignedByte

          @Beta
          public static byte parseUnsignedByte(java.lang.String string,
                                    int radix)

      Returns the unsigned `byte` value represented by a string with the given radix.
      Parameters:
        `string` - the string containing the unsigned `byte` representation to be parsed.
        `radix` - the radix to use while parsing `string`
      Throws:
        `java.lang.NumberFormatException` - if the string does not contain a valid unsigned `byte` with the given radix, or if `radix` is not between `Character.MIN_RADIX` and `Character.MAX_RADIX`.
        `java.lang.NullPointerException` - if `s` is null (in contrast to `Byte.parseByte(String)`)
      Since:
        13.0

    - #### join

          @CheckReturnValue
          public static java.lang.String join(java.lang.String separator,
                                               byte... array)

      Returns a string containing the supplied `byte` values separated by `separator`. For example, `join(":", (byte) 1, (byte) 2, (byte) 255)` returns the string `"1:2:255"`.
      Parameters:
        `separator` - the text that should appear between consecutive values in the resulting string (but not at the start or end)
        `array` - an array of `byte` values, possibly empty

    - #### lexicographicalComparator

          @CheckReturnValue
          public static java.util.Comparator<byte[]> lexicographicalComparator()

      Returns a comparator that compares two `byte` arrays lexicographically. That is, it compares, using `compare(byte, byte)`), the first pair of values that follow any common prefix, or when one array is a prefix of the other, treats the shorter array as the lesser. For example, `[] < [0x01] < [0x01, 0x7F] < [0x01, 0x80] < [0x02]`. Values are treated as unsigned.

      The returned comparator is inconsistent with `Object.equals(Object)` (since arrays support only identity equality), but it is consistent with `Arrays.equals(byte[], byte[])`.

      Since:
        2.0
      See Also:
        Lexicographical order article at Wikipedia