Top Description Inners Fields Constructors Methods
com.google.common.primitives

public final Class UnsignedBytes

extends Object
Class Inheritance
Annotations
@J2ktIncompatible
@GwtIncompatible
@ElementTypesAreNonnullByDefault
Static Imports
com.google.common.base.Preconditions.checkArgument, .Preconditions.checkNotNull, .Preconditions.checkPositionIndexes, java.util.Objects.requireNonNull

Static utility methods pertaining to byte primitives that interpret values as unsigned (that is, any negative value b is treated as the positive value 256 + b). The corresponding methods that treat the values as signed are found in SignedBytes, and the methods for which signedness is not an issue are in Bytes.

See the Guava User Guide article on primitive utilities.

Authors
Kevin Bourrillion, Martin Buchholz, Hiroshi Yamauchi, Louis Wasserman
Since
1.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
UnsignedBytes.LexicographicalComparatorHolder

Provides a lexicographical comparator implementation; either a Java implementation or a faster implementation based on Unsafe.

Field Summary

Modifier and TypeField and Description
public static final byte
MAX_POWER_OF_TWO

The largest power of two that can be represented as an unsigned byte.

public static final byte
MAX_VALUE

The largest value that fits into an unsigned byte.

private static final int

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static byte

Returns:

the byte value that, when treated as unsigned, equals value
checkedCast
(long
a value between 0 and 255 inclusive
value
)

Returns the byte value that, when treated as unsigned, is equal to value, if possible.

public static int

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
compare
(byte
the first byte to compare
a
,
byte
the second byte to compare
b
)

Compares the two specified byte values, treating them as unsigned values between 0 and 255 inclusive.

private static byte
flip(byte b)

public static String
join(String
the text that should appear between consecutive values in the resulting string (but not at the start or end)
separator
,
byte...
an array of byte values, possibly empty
array
)

Returns a string containing the supplied byte values separated by separator.

public static Comparator<byte[]>
lexicographicalComparator()

Returns a comparator that compares two byte arrays lexicographically.

pack-priv static Comparator<byte[]>
public static byte

Returns:

the value present in array that is greater than or equal to every other value in the array according to compare
max
(byte...
a nonempty array of byte values
array
)

Returns the greatest value present in array, treating values as unsigned.

public static byte

Returns:

the value present in array that is less than or equal to every other value in the array according to compare
min
(byte...
a nonempty array of byte values
array
)

Returns the least value present in array, treating values as unsigned.

public static byte
parseUnsignedByte(String string)

Returns the unsigned byte value represented by the given decimal string.

public static byte
parseUnsignedByte(String
the string containing the unsigned byte representation to be parsed.
string
,
int
the radix to use while parsing string
radix
)

Returns the unsigned byte value represented by a string with the given radix.

public static byte

Returns:

(byte) 255 if value >= 255, (byte) 0 if value <= 0, and value cast to byte otherwise
saturatedCast
(long
any long value
value
)

Returns the byte value that, when treated as unsigned, is nearest in value to value.

public static void
sort(byte[] array)

Sorts the array, treating its elements as unsigned bytes.

public static void
sort(byte[] array, int fromIndex, int toIndex)

Sorts the array between fromIndex inclusive and toIndex exclusive, treating its elements as unsigned bytes.

public static void
sortDescending(byte[] array)

Sorts the elements of array in descending order, interpreting them as unsigned 8-bit integers.

public static void
sortDescending(byte[] array, int fromIndex, int toIndex)

Sorts the elements of array between fromIndex inclusive and toIndex exclusive in descending order, interpreting them as unsigned 8-bit integers.

public static int
toInt(byte value)

Returns the value of the given byte as an integer, when treated as unsigned.

public static String
toString(byte x)

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

public static String
toString(byte
the value to convert to a string.
x
,
int
the radix to use while working with x
radix
)

Returns a string representation of x for the given radix, where x is treated as unsigned.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

MAX_POWER_OF_TWOback to summary
public static final byte MAX_POWER_OF_TWO

The largest power of two that can be represented as an unsigned byte.

Since
10.0
MAX_VALUEback to summary
public static final byte MAX_VALUE

The largest value that fits into an unsigned byte.

Since
13.0
UNSIGNED_MASKback to summary
private static final int UNSIGNED_MASK

Constructor Detail

UnsignedBytesback to summary
private UnsignedBytes()

Method Detail

checkedCastback to summary
public static byte checkedCast(long value)

Returns the byte value that, when treated as unsigned, is equal to value, if possible.

Parameters
value:long

a value between 0 and 255 inclusive

Returns:byte

the byte value that, when treated as unsigned, equals value

Annotations
@CanIgnoreReturnValue
Exceptions
IllegalArgumentException:
if value is negative or greater than 255
compareback to summary
public static int compare(byte a, byte b)

Compares the two specified byte values, treating them as unsigned values between 0 and 255 inclusive. For example, (byte) -127 is considered greater than (byte) 127 because it is seen as having the value of positive 129.

Parameters
a:byte

the first byte to compare

b:byte

the second byte to compare

Returns:int

a negative value if a is less than b; a positive value if a is greater than b; or zero if they are equal

flipback to summary
private static byte flip(byte b)
joinback to summary
public static String join(String separator, byte... array)

Returns a string containing the supplied byte values separated by separator. For example, join(":", (byte) 1, (byte) 2, (byte) 255) returns the string "1:2:255".

Parameters
separator:String

the text that should appear between consecutive values in the resulting string (but not at the start or end)

array:byte[]

an array of byte values, possibly empty

lexicographicalComparatorback to summary
public static 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, 0x7F] < [0x01, 0x80] < [0x02]. Values are treated as unsigned.

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

Since
2.0
lexicographicalComparatorJavaImplback to summary
pack-priv static Comparator<byte[]> lexicographicalComparatorJavaImpl()
Annotations
@VisibleForTesting
maxback to summary
public static byte max(byte... array)

Returns the greatest value present in array, treating values as unsigned.

Parameters
array:byte[]

a nonempty array of byte values

Returns:byte

the value present in array that is greater than or equal to every other value in the array according to compare

Exceptions
IllegalArgumentException:
if array is empty
minback to summary
public static byte min(byte... array)

Returns the least value present in array, treating values as unsigned.

Parameters
array:byte[]

a nonempty array of byte values

Returns:byte

the value present in array that is less than or equal to every other value in the array according to compare

Exceptions
IllegalArgumentException:
if array is empty
parseUnsignedByteback to summary
public static byte parseUnsignedByte(String string)

Returns the unsigned byte value represented by the given decimal string.

Annotations
@CanIgnoreReturnValue
Exceptions
NumberFormatException:
if the string does not contain a valid unsigned byte value
NullPointerException:
if string is null (in contrast to Byte#parseByte(String))
Since
13.0
parseUnsignedByteback to summary
public static byte parseUnsignedByte(String string, int radix)

Returns the unsigned byte value represented by a string with the given radix.

Parameters
string:String

the string containing the unsigned byte representation to be parsed.

radix:int

the radix to use while parsing string

Annotations
@CanIgnoreReturnValue
Exceptions
NumberFormatException:
if the string does not contain a valid unsigned byte with the given radix, or if radix is not between Character#MIN_RADIX and Character#MAX_RADIX.
NullPointerException:
if string is null (in contrast to Byte#parseByte(String))
Since
13.0
saturatedCastback to summary
public static byte saturatedCast(long value)

Returns the byte value that, when treated as unsigned, is nearest in value to value.

Parameters
value:long

any long value

Returns:byte

(byte) 255 if value >= 255, (byte) 0 if value <= 0, and value cast to byte otherwise

sortback to summary
public static void sort(byte[] array)

Sorts the array, treating its elements as unsigned bytes.

Since
23.1
sortback to summary
public static void sort(byte[] array, int fromIndex, int toIndex)

Sorts the array between fromIndex inclusive and toIndex exclusive, treating its elements as unsigned bytes.

Since
23.1
sortDescendingback to summary
public static void sortDescending(byte[] array)

Sorts the elements of array in descending order, interpreting them as unsigned 8-bit integers.

Since
23.1
sortDescendingback to summary
public static void sortDescending(byte[] array, int fromIndex, int toIndex)

Sorts the elements of array between fromIndex inclusive and toIndex exclusive in descending order, interpreting them as unsigned 8-bit integers.

Since
23.1
toIntback to summary
public static int toInt(byte value)

Returns the value of the given byte as an integer, when treated as unsigned. That is, returns value + 256 if value is negative; value itself otherwise.

Java 8+ users: use Byte#toUnsignedInt(byte) instead.

Since
6.0
toStringback to summary
public static String toString(byte x)

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

Since
13.0
toStringback to summary
public static String toString(byte x, int radix)

Returns a string representation of x for the given radix, where x is treated as unsigned.

Parameters
x:byte

the value to convert to a string.

radix:int

the radix to use while working with x

Exceptions
IllegalArgumentException:
if radix is not between Character#MIN_RADIX and Character#MAX_RADIX.
Since
13.0
com.google.common.primitives back to summary

pack-priv Class UnsignedBytes.LexicographicalComparatorHolder

extends Object
Class Inheritance
  • java.lang.Object
  • com.google.common.primitives.UnsignedBytes.LexicographicalComparatorHolder
Annotations
@VisibleForTesting

Provides a lexicographical comparator implementation; either a Java implementation or a faster implementation based on Unsafe.

Uses reflection to gracefully fall back to the Java implementation if Unsafe isn't available.

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static enum
pack-priv static enum

Field Summary

Modifier and TypeField and Description
pack-priv static final Comparator<byte[]>
pack-priv static final String

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
pack-priv static Comparator<byte[]>
getBestComparator()

Returns the Unsafe-using Comparator, or falls back to the pure-Java implementation if unable to do so.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

BEST_COMPARATORback to summary
pack-priv static final Comparator<byte[]> BEST_COMPARATOR
UNSAFE_COMPARATOR_NAMEback to summary
pack-priv static final String UNSAFE_COMPARATOR_NAME

Constructor Detail

LexicographicalComparatorHolderback to summary
pack-priv LexicographicalComparatorHolder()

Method Detail

getBestComparatorback to summary
pack-priv static Comparator<byte[]> getBestComparator()

Returns the Unsafe-using Comparator, or falls back to the pure-Java implementation if unable to do so.

com.google.common.primitives back to summary

pack-priv final Enum UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator

extends Enum<UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator>
implements Comparator<byte[]>
Class Inheritance
All Implemented Interfaces
java.util.Comparator

Field Summary

Modifier and TypeField and Description
public static final UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public int
compare(byte[]
the first object to be compared.
left
,
byte[]
the second object to be compared.
right
)

Implements java.util.Comparator.compare.

Compares its two arguments for order.
public String
toString()

Overrides java.lang.Enum.toString.

Returns the name of this enum constant, as contained in the declaration.
public static UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator
public static UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinalvalueOf

Field Detail

INSTANCEback to summary
public static final UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator INSTANCE

Constructor Detail

PureJavaComparatorback to summary
private PureJavaComparator()

Method Detail

compareback to summary
public int compare(byte[] left, byte[] right)

Implements java.util.Comparator.compare.

Doc from java.util.Comparator.compare.

Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

The implementor must ensure that signum(compare(x, y)) == -signum(compare(y, x)) for all x and y. (This implies that compare(x, y) must throw an exception if and only if compare(y, x) throws an exception.)

The implementor must also ensure that the relation is transitive: ((compare(x, y)>0) && (compare(y, z)>0)) implies compare(x, z)>0.

Finally, the implementor must ensure that compare(x, y)==0 implies that signum(compare(x, z))==signum(compare(y, z)) for all z.

Parameters
left:byte[]

the first object to be compared.

right:byte[]

the second object to be compared.

Returns:int

a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Enum.toString.

Doc from java.lang.Enum.toString.

Returns the name of this enum constant, as contained in the declaration. This method may be overridden, though it typically isn't necessary or desirable. An enum class should override this method when a more "programmer-friendly" string form exists.

Returns:String

the name of this enum constant

Annotations
@Override
valueOfback to summary
public static UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator valueOf(String name)
valuesback to summary
public static UnsignedBytes.LexicographicalComparatorHolder.PureJavaComparator[] values()
com.google.common.primitives back to summary

pack-priv final Enum UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator

extends Enum<UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator>
implements Comparator<byte[]>
Class Inheritance
All Implemented Interfaces
java.util.Comparator
Annotations
@VisibleForTesting

Field Summary

Modifier and TypeField and Description
pack-priv static final boolean
pack-priv static final int
BYTE_ARRAY_BASE_OFFSET

The offset to the first element in a byte array.

public static final UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator
pack-priv static final Unsafe

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public int
compare(byte[]
the first object to be compared.
left
,
byte[]
the second object to be compared.
right
)

Implements java.util.Comparator.compare.

Compares its two arguments for order.
private static Unsafe

Returns:

a sun.misc.Unsafe
getUnsafe
()

Returns a sun.misc.Unsafe.

public String
toString()

Overrides java.lang.Enum.toString.

Returns the name of this enum constant, as contained in the declaration.
public static UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator
public static UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinalvalueOf

Field Detail

BIG_ENDIANback to summary
pack-priv static final boolean BIG_ENDIAN
BYTE_ARRAY_BASE_OFFSETback to summary
pack-priv static final int BYTE_ARRAY_BASE_OFFSET

The offset to the first element in a byte array.

INSTANCEback to summary
public static final UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator INSTANCE
theUnsafeback to summary
pack-priv static final Unsafe theUnsafe

Constructor Detail

UnsafeComparatorback to summary
private UnsafeComparator()

Method Detail

compareback to summary
public int compare(byte[] left, byte[] right)

Implements java.util.Comparator.compare.

Doc from java.util.Comparator.compare.

Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

The implementor must ensure that signum(compare(x, y)) == -signum(compare(y, x)) for all x and y. (This implies that compare(x, y) must throw an exception if and only if compare(y, x) throws an exception.)

The implementor must also ensure that the relation is transitive: ((compare(x, y)>0) && (compare(y, z)>0)) implies compare(x, z)>0.

Finally, the implementor must ensure that compare(x, y)==0 implies that signum(compare(x, z))==signum(compare(y, z)) for all z.

Parameters
left:byte[]

the first object to be compared.

right:byte[]

the second object to be compared.

Returns:int

a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

Annotations
@Override
getUnsafeback to summary
private static Unsafe getUnsafe()

Returns a sun.misc.Unsafe. Suitable for use in a 3rd party package. Replace with a simple call to Unsafe.getUnsafe when integrating into a jdk.

Returns:Unsafe

a sun.misc.Unsafe

Annotations
@SuppressWarnings:removal
toStringback to summary
public String toString()

Overrides java.lang.Enum.toString.

Doc from java.lang.Enum.toString.

Returns the name of this enum constant, as contained in the declaration. This method may be overridden, though it typically isn't necessary or desirable. An enum class should override this method when a more "programmer-friendly" string form exists.

Returns:String

the name of this enum constant

Annotations
@Override
valueOfback to summary
public static UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator valueOf(String name)
valuesback to summary
public static UnsignedBytes.LexicographicalComparatorHolder.UnsafeComparator[] values()