UnsignedInts
Date: 2016-05-24

com.google.common.primitives

## Class UnsignedInts

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

-     @Beta
      @GwtCompatible
      public final class UnsignedInts
      extends java.lang.Object

  Static utility methods pertaining to `int` primitives that interpret values as unsigned (that is, any negative value `x` is treated as the positive value `2^32 + x`). The methods for which signedness is not an issue are in `Ints`, as well as signed versions of methods for which signedness is an issue.

  In addition, this class provides several static methods for converting an `int` to a `String` and a `String` to an `int` that treat the `int` as an unsigned number.

  Users of these utilities must be extremely careful not to mix up signed and unsigned `int` values. When possible, it is recommended that the `UnsignedInteger` wrapper class be used, at a small efficiency penalty, to enforce the distinction in the type system.

  See the Guava User Guide article on unsigned primitive utilities.

  Since:
    11.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `compare(int a, int b)` Compares the two specified `int` values, treating them as unsigned values between `0` and `2^32 - 1` inclusive.
    `static int` | `decode(java.lang.String stringValue)` Returns the unsigned `int` value represented by the given string.
    `static int` | `divide(int dividend, int divisor)` Returns dividend / divisor, where the dividend and divisor are treated as unsigned 32-bit quantities.
    `static java.lang.String` | `join(java.lang.String separator, int... array)` Returns a string containing the supplied unsigned `int` values separated by `separator`.
    `static java.util.Comparator<int[]>` | `lexicographicalComparator()` Returns a comparator that compares two arrays of unsigned `int` values lexicographically.
    `static int` | `max(int... array)` Returns the greatest value present in `array`, treating values as unsigned.
    `static int` | `min(int... array)` Returns the least value present in `array`, treating values as unsigned.
    `static int` | `parseUnsignedInt(java.lang.String s)` Returns the unsigned `int` value represented by the given decimal string.
    `static int` | `parseUnsignedInt(java.lang.String string, int radix)` Returns the unsigned `int` value represented by a string with the given radix.
    `static int` | `remainder(int dividend, int divisor)` Returns dividend % divisor, where the dividend and divisor are treated as unsigned 32-bit quantities.
    `static long` | `toLong(int value)` Returns the value of the given `int` as a `long`, when treated as unsigned.
    `static java.lang.String` | `toString(int x)` Returns a string representation of x, where x is treated as unsigned.
    `static java.lang.String` | `toString(int 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`

- - ### Method Detail

    - #### compare

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

      Compares the two specified `int` values, treating them as unsigned values between `0` and `2^32 - 1` inclusive.
      Parameters:
        `a` - the first unsigned `int` to compare
        `b` - the second unsigned `int` 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

    - #### toLong

          @CheckReturnValue
          public static long toLong(int value)

      Returns the value of the given `int` as a `long`, when treated as unsigned.

    - #### min

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

      Returns the least value present in `array`, treating values as unsigned.
      Parameters:
        `array` - a nonempty array of unsigned `int` values
      Returns:
        the value present in `array` that is less than or equal to every other value in the array according to `compare(int, int)`
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is empty

    - #### max

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

      Returns the greatest value present in `array`, treating values as unsigned.
      Parameters:
        `array` - a nonempty array of unsigned `int` values
      Returns:
        the value present in `array` that is greater than or equal to every other value in the array according to `compare(int, int)`
      Throws:
        `java.lang.IllegalArgumentException` - if `array` is empty

    - #### join

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

      Returns a string containing the supplied unsigned `int` values separated by `separator`. For example, `join("-", 1, 2, 3)` returns the string `"1-2-3"`.
      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 unsigned `int` values, possibly empty

    - #### lexicographicalComparator

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

      Returns a comparator that compares two arrays of unsigned `int` values lexicographically. That is, it compares, using `compare(int, int)`), 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, `[] < [1] < [1, 2] < [2] < [1 << 31]`.

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

      See Also:
        Lexicographical order article at Wikipedia

    - #### divide

          @CheckReturnValue
          public static int divide(int dividend,
                                    int divisor)

      Returns dividend / divisor, where the dividend and divisor are treated as unsigned 32-bit quantities.
      Parameters:
        `dividend` - the dividend (numerator)
        `divisor` - the divisor (denominator)
      Throws:
        `java.lang.ArithmeticException` - if divisor is 0

    - #### remainder

          @CheckReturnValue
          public static int remainder(int dividend,
                                       int divisor)

      Returns dividend % divisor, where the dividend and divisor are treated as unsigned 32-bit quantities.
      Parameters:
        `dividend` - the dividend (numerator)
        `divisor` - the divisor (denominator)
      Throws:
        `java.lang.ArithmeticException` - if divisor is 0

    - #### decode

          public static int decode(java.lang.String stringValue)

      Returns the unsigned `int` value represented by the given string. Accepts a decimal, hexadecimal, or octal number given by specifying the following prefix:
      - `0x`HexDigits
      - `0X`HexDigits
      - `#`HexDigits
      - `0`OctalDigits
      Throws:
        `java.lang.NumberFormatException` - if the string does not contain a valid unsigned `int` value
      Since:
        13.0

    - #### parseUnsignedInt

          public static int parseUnsignedInt(java.lang.String s)

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

    - #### parseUnsignedInt

          public static int parseUnsignedInt(java.lang.String string,
                             int radix)

      Returns the unsigned `int` value represented by a string with the given radix.
      Parameters:
        `string` - the string containing the unsigned integer representation to be parsed.
        `radix` - the radix to use while parsing `s`; must be between `Character.MIN_RADIX` and `Character.MAX_RADIX`.
      Throws:
        `java.lang.NumberFormatException` - if the string does not contain a valid unsigned `int`, or if supplied radix is invalid.
        `java.lang.NullPointerException` - if `s` is null (in contrast to `Integer.parseInt(String)`)

    - #### toString

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

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

    - #### toString

          @CheckReturnValue
          public static java.lang.String toString(int 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`.