Package com.google.common.primitives
Class UnsignedLongs
java.lang.Object
com.google.common.primitives.UnsignedLongs
Static utility methods pertaining to
long
primitives that interpret values as
unsigned (that is, any negative value x
is treated as the positive value
2^64 + x
). The methods for which signedness is not an issue are in Longs
, as well
as signed versions of methods for which signedness is an issue.
In addition, this class provides several static methods for converting a long
to a
String
and a String
to a long
that treat the long
as an unsigned
number.
Users of these utilities must be extremely careful not to mix up signed and unsigned
long
values. When possible, it is recommended that the UnsignedLong
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:
- 10.0
-
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionstatic int
compare
(long a, long b) Compares the two specifiedlong
values, treating them as unsigned values between0
and2^64 - 1
inclusive.static long
Returns the unsignedlong
value represented by the given string.static long
divide
(long dividend, long divisor) Returns dividend / divisor, where the dividend and divisor are treated as unsigned 64-bit quantities.static String
Returns a string containing the supplied unsignedlong
values separated byseparator
.static Comparator
<long[]> Returns a comparator that compares two arrays of unsignedlong
values lexicographically.static long
max
(long... array) Returns the greatest value present inarray
, treating values as unsigned.static long
min
(long... array) Returns the least value present inarray
, treating values as unsigned.static long
parseUnsignedLong
(String string) Returns the unsignedlong
value represented by the given decimal string.static long
parseUnsignedLong
(String string, int radix) Returns the unsignedlong
value represented by a string with the given radix.static long
remainder
(long dividend, long divisor) Returns dividend % divisor, where the dividend and divisor are treated as unsigned 64-bit quantities.static String
toString
(long x) Returns a string representation of x, where x is treated as unsigned.static String
toString
(long x, int radix) Returns a string representation ofx
for the given radix, wherex
is treated as unsigned.
-
Field Details
-
MAX_VALUE
public static final long MAX_VALUE- See Also:
-
-
Method Details
-
compare
public static int compare(long a, long b) Compares the two specifiedlong
values, treating them as unsigned values between0
and2^64 - 1
inclusive.- Parameters:
a
- the first unsignedlong
to compareb
- the second unsignedlong
to compare- Returns:
- a negative value if
a
is less thanb
; a positive value ifa
is greater thanb
; or zero if they are equal
-
min
public static long min(long... array) Returns the least value present inarray
, treating values as unsigned.- Parameters:
array
- a nonempty array of unsignedlong
values- Returns:
- the value present in
array
that is less than or equal to every other value in the array according tocompare(long, long)
- Throws:
IllegalArgumentException
- ifarray
is empty
-
max
public static long max(long... array) Returns the greatest value present inarray
, treating values as unsigned.- Parameters:
array
- a nonempty array of unsignedlong
values- Returns:
- the value present in
array
that is greater than or equal to every other value in the array according tocompare(long, long)
- Throws:
IllegalArgumentException
- ifarray
is empty
-
join
Returns a string containing the supplied unsignedlong
values separated byseparator
. 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 unsignedlong
values, possibly empty
-
lexicographicalComparator
Returns a comparator that compares two arrays of unsignedlong
values lexicographically. That is, it compares, usingcompare(long, long)
), 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,[] < [1L] < [1L, 2L] < [2L] < [1L << 63]
.The returned comparator is inconsistent with
Object.equals(Object)
(since arrays support only identity equality), but it is consistent withArrays.equals(long[], long[])
. -
divide
public static long divide(long dividend, long divisor) Returns dividend / divisor, where the dividend and divisor are treated as unsigned 64-bit quantities.- Parameters:
dividend
- the dividend (numerator)divisor
- the divisor (denominator)- Throws:
ArithmeticException
- if divisor is 0
-
remainder
public static long remainder(long dividend, long divisor) Returns dividend % divisor, where the dividend and divisor are treated as unsigned 64-bit quantities.- Parameters:
dividend
- the dividend (numerator)divisor
- the divisor (denominator)- Throws:
ArithmeticException
- if divisor is 0- Since:
- 11.0
-
parseUnsignedLong
Returns the unsignedlong
value represented by the given decimal string.- Throws:
NumberFormatException
- if the string does not contain a valid unsignedlong
valueNullPointerException
- ifstring
is null (in contrast toLong.parseLong(String)
)
-
decode
Returns the unsignedlong
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 unsignedlong
value- Since:
- 13.0
-
parseUnsignedLong
Returns the unsignedlong
value represented by a string with the given radix.- Parameters:
radix
- the radix to use while parsingstring
s
- the string containing the unsignedlong
representation to be parsed.- Throws:
NumberFormatException
- if the string does not contain a valid unsignedlong
with the given radix, or ifradix
is not betweenCharacter.MIN_RADIX
andCharacter.MAX_RADIX
.NullPointerException
- ifstring
is null (in contrast toLong.parseLong(String)
)
-
toString
Returns a string representation of x, where x is treated as unsigned. -
toString
Returns a string representation ofx
for the given radix, wherex
is treated as unsigned.- 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
.
-