SignedBytes
Date: 2016-05-24

com.google.common.primitives

## Class SignedBytes

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

-     @CheckReturnValue
      @GwtCompatible
      public final class SignedBytes
      extends java.lang.Object

  Static utility methods pertaining to `byte` primitives that interpret values as signed. The corresponding methods that treat the values as unsigned are found in `UnsignedBytes`, 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 a signed `byte`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static byte` | `checkedCast(long value)` Returns the `byte` value that is equal to `value`, if possible.
    `static int` | `compare(byte a, byte b)` Compares the two specified `byte` values.
    `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` | `saturatedCast(long value)` Returns the `byte` nearest in value to `value`.

    - ### 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 a signed `byte`.
      Since:
        10.0
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### checkedCast

          public static byte checkedCast(long value)

      Returns the `byte` value that is equal to `value`, if possible.
      Parameters:
        `value` - any value in the range of the `byte` type
      Returns:
        the `byte` value that equals `value`
      Throws:
        `java.lang.IllegalArgumentException` - if `value` is greater than `Byte.MAX_VALUE` or less than `Byte.MIN_VALUE`

    - #### saturatedCast

          public static byte saturatedCast(long value)

      Returns the `byte` nearest in value to `value`.
      Parameters:
        `value` - any `long` value
      Returns:
        the same value cast to `byte` if it is in the range of the `byte` type, `Byte.MAX_VALUE` if it is too large, or `Byte.MIN_VALUE` if it is too small

    - #### compare

          public static int compare(byte a,
                    byte b)

      Compares the two specified `byte` values. The sign of the value returned is the same as that of `((Byte) a).compareTo(b)`.

      Note: this method behaves identically to the JDK 7 method `Byte.compare(byte, byte)`.

      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

          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

          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

    - #### join

          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(":", 0x01, 0x02, -0x01)` returns the string `"1:2:-1"`.
      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

          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, 0x80] < [0x01, 0x7F] < [0x02]`. Values are treated as signed.

      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