com.google.common.primitives

## Class Ints

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

-     @CheckReturnValue
      @GwtCompatible(emulated=true)
      public final class Ints
      extends java.lang.Object

  Static utility methods pertaining to `int` primitives, that are not already found in either `Integer` or `Arrays`.

  See the Guava User Guide article on primitive utilities.

  Since:
    1.0

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BYTES` The number of bytes required to represent a primitive `int` value.
    `static int` | `MAX_POWER_OF_TWO` The largest power of two that can be represented as an `int`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.util.List<java.lang.Integer>` | `asList(int... backingArray)` Returns a fixed-size list backed by the specified array, similar to `Arrays.asList(Object[])`.
    `static int` | `checkedCast(long value)` Returns the `int` value that is equal to `value`, if possible.
    `static int` | `compare(int a, int b)` Compares the two specified `int` values.
    `static int[]` | `concat(int[]... arrays)` Returns the values from each provided array combined into a single array.
    `static boolean` | `contains(int[] array, int target)` Returns `true` if `target` is present as an element anywhere in `array`.
    `static int[]` | `ensureCapacity(int[] array, int minLength, int padding)` Returns an array containing the same values as `array`, but guaranteed to be of a specified minimum length.
    `static int` | `fromByteArray(byte[] bytes)` Returns the `int` value whose big-endian representation is stored in the first 4 bytes of `bytes`; equivalent to `ByteBuffer.wrap(bytes).getInt()`.
    `static int` | `fromBytes(byte b1, byte b2, byte b3, byte b4)` Returns the `int` value whose byte representation is the given 4 bytes, in big-endian order; equivalent to `Ints.fromByteArray(new byte[] {b1, b2, b3, b4})`.
    `static int` | `hashCode(int value)` Returns a hash code for `value`; equal to the result of invoking `((Integer) value).hashCode()`.
    `static int` | `indexOf(int[] array, int target)` Returns the index of the first appearance of the value `target` in `array`.
    `static int` | `indexOf(int[] array, int[] target)` Returns the start position of the first occurrence of the specified `target` within `array`, or `-1` if there is no such occurrence.
    `static java.lang.String` | `join(java.lang.String separator, int... array)` Returns a string containing the supplied `int` values separated by `separator`.
    `static int` | `lastIndexOf(int[] array, int target)` Returns the index of the last appearance of the value `target` in `array`.
    `static java.util.Comparator<int[]>` | `lexicographicalComparator()` Returns a comparator that compares two `int` arrays lexicographically.
    `static int` | `max(int... array)` Returns the greatest value present in `array`.
    `static int` | `min(int... array)` Returns the least value present in `array`.
    `static int` | `saturatedCast(long value)` Returns the `int` nearest in value to `value`.
    `static Converter<java.lang.String,java.lang.Integer>` | `stringConverter()` Returns a serializable converter object that converts between strings and integers using `Integer.decode(java.lang.String)` and `Integer.toString()`.
    `static int[]` | `toArray(java.util.Collection<? extends java.lang.Number> collection)` Returns an array containing each value of `collection`, converted to a `int` value in the manner of `Number.intValue()`.
    `static byte[]` | `toByteArray(int value)` Returns a big-endian representation of `value` in a 4-element byte array; equivalent to `ByteBuffer.allocate(4).putInt(value).array()`.
    `static java.lang.Integer` | `tryParse(java.lang.String string)` Parses the specified string as a signed decimal integer value.
    `static java.lang.Integer` | `tryParse(java.lang.String string, int radix)` Parses the specified string as a signed integer value using the specified radix.

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

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

- - ### Field Detail

    - #### BYTES

          public static final int BYTES

      The number of bytes required to represent a primitive `int` value.
      See Also:
        Constant Field Values

    - #### MAX_POWER_OF_TWO

          public static final int MAX_POWER_OF_TWO

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

  - ### Method Detail

    - #### hashCode

          public static int hashCode(int value)

      Returns a hash code for `value`; equal to the result of invoking `((Integer) value).hashCode()`.
      Parameters:
        `value` - a primitive `int` value
      Returns:
        a hash code for the value

    - #### checkedCast

          public static int checkedCast(long value)

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

    - #### saturatedCast

          public static int saturatedCast(long value)

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

    - #### compare

          public static int compare(int a,
                    int b)

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

      Note for Java 7 and later: this method should be treated as deprecated; use the equivalent `Integer.compare(int, int)` method instead.

      Parameters:
        `a` - the first `int` to compare
        `b` - the second `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

    - #### contains

          public static boolean contains(int[] array,
                         int target)

      Returns `true` if `target` is present as an element anywhere in `array`.
      Parameters:
        `array` - an array of `int` values, possibly empty
        `target` - a primitive `int` value
      Returns:
        `true` if `array[i] == target` for some value of `i`

    - #### indexOf

          public static int indexOf(int[] array,
                    int target)

      Returns the index of the first appearance of the value `target` in `array`.
      Parameters:
        `array` - an array of `int` values, possibly empty
        `target` - a primitive `int` value
      Returns:
        the least index `i` for which `array[i] == target`, or `-1` if no such index exists.

    - #### indexOf

          public static int indexOf(int[] array,
                    int[] target)

      Returns the start position of the first occurrence of the specified `target` within `array`, or `-1` if there is no such occurrence.

      More formally, returns the lowest index `i` such that `java.util.Arrays.copyOfRange(array, i, i + target.length)` contains exactly the same elements as `target`.

      Parameters:
        `array` - the array to search for the sequence `target`
        `target` - the array to search for as a sub-sequence of `array`

    - #### lastIndexOf

          public static int lastIndexOf(int[] array,
                        int target)

      Returns the index of the last appearance of the value `target` in `array`.
      Parameters:
        `array` - an array of `int` values, possibly empty
        `target` - a primitive `int` value
      Returns:
        the greatest index `i` for which `array[i] == target`, or `-1` if no such index exists.

    - #### min

          public static int min(int... array)

      Returns the least value present in `array`.
      Parameters:
        `array` - a nonempty array of `int` 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 int max(int... array)

      Returns the greatest value present in `array`.
      Parameters:
        `array` - a nonempty array of `int` 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

    - #### concat

          public static int[] concat(int[]... arrays)

      Returns the values from each provided array combined into a single array. For example, `concat(new int[] {a, b}, new int[] {}, new int[] {c}` returns the array `{a, b, c}`.
      Parameters:
        `arrays` - zero or more `int` arrays
      Returns:
        a single array containing all the values from the source arrays, in order

    - #### toByteArray

          @GwtIncompatible(value="doesn\'t work")
          public static byte[] toByteArray(int value)

      Returns a big-endian representation of `value` in a 4-element byte array; equivalent to `ByteBuffer.allocate(4).putInt(value).array()`. For example, the input value `0x12131415` would yield the byte array `{0x12, 0x13, 0x14, 0x15}`.

      If you need to convert and concatenate several values (possibly even of different types), use a shared `ByteBuffer` instance, or use `ByteStreams.newDataOutput()` to get a growable buffer.

    - #### fromByteArray

          @GwtIncompatible(value="doesn\'t work")
          public static int fromByteArray(byte[] bytes)

      Returns the `int` value whose big-endian representation is stored in the first 4 bytes of `bytes`; equivalent to `ByteBuffer.wrap(bytes).getInt()`. For example, the input byte array `{0x12, 0x13, 0x14, 0x15, 0x33}` would yield the `int` value `0x12131415`.

      Arguably, it's preferable to use `ByteBuffer`; that library exposes much more flexibility at little cost in readability.

      Throws:
        `java.lang.IllegalArgumentException` - if `bytes` has fewer than 4 elements

    - #### fromBytes

          @GwtIncompatible(value="doesn\'t work")
          public static int fromBytes(byte b1,
                                           byte b2,
                                           byte b3,
                                           byte b4)

      Returns the `int` value whose byte representation is the given 4 bytes, in big-endian order; equivalent to `Ints.fromByteArray(new byte[] {b1, b2, b3, b4})`.
      Since:
        7.0

    - #### stringConverter

          @Beta
          public static Converter<java.lang.String,java.lang.Integer> stringConverter()

      Returns a serializable converter object that converts between strings and integers using `Integer.decode(java.lang.String)` and `Integer.toString()`.
      Since:
        16.0

    - #### ensureCapacity

          public static int[] ensureCapacity(int[] array,
                             int minLength,
                             int padding)

      Returns an array containing the same values as `array`, but guaranteed to be of a specified minimum length. If `array` already has a length of at least `minLength`, it is returned directly. Otherwise, a new array of size `minLength + padding` is returned, containing the values of `array`, and zeroes in the remaining places.
      Parameters:
        `array` - the source array
        `minLength` - the minimum length the returned array must guarantee
        `padding` - an extra amount to "grow" the array by if growth is necessary
      Returns:
        an array containing the values of `array`, with guaranteed minimum length `minLength`
      Throws:
        `java.lang.IllegalArgumentException` - if `minLength` or `padding` is negative

    - #### join

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

      Returns a string containing the supplied `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 `int` values, possibly empty

    - #### lexicographicalComparator

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

      Returns a comparator that compares two `int` arrays 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]`.

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

      Since:
        2.0
      See Also:
        Lexicographical order article at Wikipedia

    - #### toArray

          public static int[] toArray(java.util.Collection<? extends java.lang.Number> collection)

      Returns an array containing each value of `collection`, converted to a `int` value in the manner of `Number.intValue()`.

      Elements are copied from the argument collection as if by `collection.toArray()`. Calling this method is as thread-safe as calling that method.

      Parameters:
        `collection` - a collection of `Number` instances
      Returns:
        an array containing the same values as `collection`, in the same order, converted to primitives
      Throws:
        `java.lang.NullPointerException` - if `collection` or any of its elements is null
      Since:
        1.0 (parameter was `Collection<Integer>` before 12.0)

    - #### asList

          public static java.util.List<java.lang.Integer> asList(int... backingArray)

      Returns a fixed-size list backed by the specified array, similar to `Arrays.asList(Object[])`. The list supports `List.set(int, Object)`, but any attempt to set a value to `null` will result in a `NullPointerException`.

      The returned list maintains the values, but not the identities, of `Integer` objects written to or read from it. For example, whether `list.get(0) == list.get(0)` is true for the returned list is unspecified.

      Parameters:
        `backingArray` - the array to back the list
      Returns:
        a list view of the array

    - #### tryParse

          @Beta
          @Nullable
          @CheckForNull
          public static java.lang.Integer tryParse(java.lang.String string)

      Parses the specified string as a signed decimal integer value. The ASCII character `'-'` (`'\u002D'`) is recognized as the minus sign.

      Unlike `Integer.parseInt(String)`, this method returns `null` instead of throwing an exception if parsing fails. Additionally, this method only accepts ASCII digits, and returns `null` if non-ASCII digits are present in the string.

      Note that strings prefixed with ASCII `'+'` are rejected, even under JDK 7, despite the change to `Integer.parseInt(String)` for that version.

      Parameters:
        `string` - the string representation of an integer value
      Returns:
        the integer value represented by `string`, or `null` if `string` has a length of zero or cannot be parsed as an integer value
      Since:
        11.0

    - #### tryParse

          @Beta
          @Nullable
          @CheckForNull
          public static java.lang.Integer tryParse(java.lang.String string,
                                                              int radix)

      Parses the specified string as a signed integer value using the specified radix. The ASCII character `'-'` (`'\u002D'`) is recognized as the minus sign.

      Unlike `Integer.parseInt(String, int)`, this method returns `null` instead of throwing an exception if parsing fails. Additionally, this method only accepts ASCII digits, and returns `null` if non-ASCII digits are present in the string.

      Note that strings prefixed with ASCII `'+'` are rejected, even under JDK 7, despite the change to `Integer.parseInt(String, int)` for that version.

      Parameters:
        `string` - the string representation of an integer value
        `radix` - the radix to use when parsing
      Returns:
        the integer value represented by `string` using `radix`, or `null` if `string` has a length of zero or cannot be parsed as an integer value
      Throws:
        `java.lang.IllegalArgumentException` - if `radix < Character.MIN_RADIX` or `radix > Character.MAX_RADIX`
      Since:
        19.0