Class UnsignedInts
 java.lang.Object

 com.google.common.primitives.UnsignedInts

@Beta @GwtCompatible public final class UnsignedInts extends Object
Static utility methods pertaining toint
primitives that interpret values as unsigned (that is, any negative valuex
is treated as the positive value2^32 + x
). The methods for which signedness is not an issue are inInts
, 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 aString
and aString
to anint
that treat theint
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 theUnsignedInteger
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
 Author:
 Louis Wasserman


Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static int
checkedCast(long value)
Returns theint
value that, when treated as unsigned, is equal tovalue
, if possible.static int
compare(int a, int b)
Compares the two specifiedint
values, treating them as unsigned values between0
and2^32  1
inclusive.static int
decode(String stringValue)
Returns the unsignedint
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 32bit quantities.static String
join(String separator, int... array)
Returns a string containing the supplied unsignedint
values separated byseparator
.static Comparator<int[]>
lexicographicalComparator()
Returns a comparator that compares two arrays of unsignedint
values lexicographically.static int
max(int... array)
Returns the greatest value present inarray
, treating values as unsigned.static int
min(int... array)
Returns the least value present inarray
, treating values as unsigned.static int
parseUnsignedInt(String s)
Returns the unsignedint
value represented by the given decimal string.static int
parseUnsignedInt(String string, int radix)
Returns the unsignedint
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 32bit quantities.static int
saturatedCast(long value)
Returns theint
value that, when treated as unsigned, is nearest in value tovalue
.static void
sort(int[] array)
Sorts the array, treating its elements as unsigned 32bit integers.static void
sort(int[] array, int fromIndex, int toIndex)
Sorts the array betweenfromIndex
inclusive andtoIndex
exclusive, treating its elements as unsigned 32bit integers.static void
sortDescending(int[] array)
Sorts the elements ofarray
in descending order, interpreting them as unsigned 32bit integers.static void
sortDescending(int[] array, int fromIndex, int toIndex)
Sorts the elements ofarray
betweenfromIndex
inclusive andtoIndex
exclusive in descending order, interpreting them as unsigned 32bit integers.static long
toLong(int value)
Returns the value of the givenint
as along
, when treated as unsigned.static String
toString(int x)
Returns a string representation of x, where x is treated as unsigned.static String
toString(int x, int radix)
Returns a string representation ofx
for the given radix, wherex
is treated as unsigned.



Method Detail

compare
public static int compare(int a, int b)
Compares the two specifiedint
values, treating them as unsigned values between0
and2^32  1
inclusive.Java 8 users: use
Integer.compareUnsigned(int, int)
instead. Parameters:
a
 the first unsignedint
to compareb
 the second unsignedint
to compare Returns:
 a negative value if
a
is less thanb
; a positive value ifa
is greater thanb
; or zero if they are equal

toLong
public static long toLong(int value)
Returns the value of the givenint
as along
, when treated as unsigned.Java 8 users: use
Integer.toUnsignedLong(int)
instead.

checkedCast
public static int checkedCast(long value)
Returns theint
value that, when treated as unsigned, is equal tovalue
, if possible. Parameters:
value
 a value between 0 and 2^{32}1 inclusive Returns:
 the
int
value that, when treated as unsigned, equalsvalue
 Throws:
IllegalArgumentException
 ifvalue
is negative or greater than or equal to 2^{32} Since:
 21.0

saturatedCast
public static int saturatedCast(long value)
Returns theint
value that, when treated as unsigned, is nearest in value tovalue
. Parameters:
value
 anylong
value Returns:
2^32  1
ifvalue >= 2^32
,0
ifvalue <= 0
, andvalue
cast toint
otherwise Since:
 21.0

min
public static int min(int... array)
Returns the least value present inarray
, treating values as unsigned. Parameters:
array
 a nonempty array of unsignedint
values Returns:
 the value present in
array
that is less than or equal to every other value in the array according tocompare(int, int)
 Throws:
IllegalArgumentException
 ifarray
is empty

max
public static int max(int... array)
Returns the greatest value present inarray
, treating values as unsigned. Parameters:
array
 a nonempty array of unsignedint
values Returns:
 the value present in
array
that is greater than or equal to every other value in the array according tocompare(int, int)
 Throws:
IllegalArgumentException
 ifarray
is empty

join
public static String join(String separator, int... array)
Returns a string containing the supplied unsignedint
values separated byseparator
. For example,join("", 1, 2, 3)
returns the string"123"
. 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 unsignedint
values, possibly empty

lexicographicalComparator
public static Comparator<int[]> lexicographicalComparator()
Returns a comparator that compares two arrays of unsignedint
values lexicographically. That is, it compares, usingcompare(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 withArrays.equals(int[], int[])
.

sort
public static void sort(int[] array)
Sorts the array, treating its elements as unsigned 32bit integers. Since:
 23.1

sort
public static void sort(int[] array, int fromIndex, int toIndex)
Sorts the array betweenfromIndex
inclusive andtoIndex
exclusive, treating its elements as unsigned 32bit integers. Since:
 23.1

sortDescending
public static void sortDescending(int[] array)
Sorts the elements ofarray
in descending order, interpreting them as unsigned 32bit integers. Since:
 23.1

sortDescending
public static void sortDescending(int[] array, int fromIndex, int toIndex)
Sorts the elements ofarray
betweenfromIndex
inclusive andtoIndex
exclusive in descending order, interpreting them as unsigned 32bit integers. Since:
 23.1

divide
public static int divide(int dividend, int divisor)
Returns dividend / divisor, where the dividend and divisor are treated as unsigned 32bit quantities.Java 8 users: use
Integer.divideUnsigned(int, int)
instead. Parameters:
dividend
 the dividend (numerator)divisor
 the divisor (denominator) Throws:
ArithmeticException
 if divisor is 0

remainder
public static int remainder(int dividend, int divisor)
Returns dividend % divisor, where the dividend and divisor are treated as unsigned 32bit quantities.Java 8 users: use
Integer.remainderUnsigned(int, int)
instead. Parameters:
dividend
 the dividend (numerator)divisor
 the divisor (denominator) Throws:
ArithmeticException
 if divisor is 0

decode
@CanIgnoreReturnValue public static int decode(String stringValue)
Returns the unsignedint
value represented by the given string.Accepts a decimal, hexadecimal, or octal number given by specifying the following prefix:
0x
HexDigits0X
HexDigits#
HexDigits0
OctalDigits
 Throws:
NumberFormatException
 if the string does not contain a valid unsignedint
value Since:
 13.0

parseUnsignedInt
@CanIgnoreReturnValue public static int parseUnsignedInt(String s)
Returns the unsignedint
value represented by the given decimal string.Java 8 users: use
Integer.parseUnsignedInt(String)
instead. Throws:
NumberFormatException
 if the string does not contain a valid unsignedint
valueNullPointerException
 ifs
is null (in contrast toInteger.parseInt(String)
)

parseUnsignedInt
@CanIgnoreReturnValue public static int parseUnsignedInt(String string, int radix)
Returns the unsignedint
value represented by a string with the given radix.Java 8 users: use
Integer.parseUnsignedInt(String, int)
instead. Parameters:
string
 the string containing the unsigned integer representation to be parsed.radix
 the radix to use while parsings
; must be betweenCharacter.MIN_RADIX
andCharacter.MAX_RADIX
. Throws:
NumberFormatException
 if the string does not contain a valid unsignedint
, or if supplied radix is invalid.NullPointerException
 ifs
is null (in contrast toInteger.parseInt(String)
)

toString
public static String toString(int x)
Returns a string representation of x, where x is treated as unsigned.Java 8 users: use
Integer.toUnsignedString(int)
instead.

toString
public static String toString(int x, int radix)
Returns a string representation ofx
for the given radix, wherex
is treated as unsigned.Java 8 users: use
Integer.toUnsignedString(int, int)
instead. Parameters:
x
 the value to convert to a string.radix
 the radix to use while working withx
 Throws:
IllegalArgumentException
 ifradix
is not betweenCharacter.MIN_RADIX
andCharacter.MAX_RADIX
.

