Skip to content

PrimitivesExplained

Jump to bottom
cpovirk edited this page Sep 18, 2026 · 13 revisions

Primitives

Overview

The primitive types of Java are the basic types:

  • byte
  • short
  • int
  • long
  • float
  • double
  • char
  • boolean

Before searching Guava for a method, you should check if it is in Arrays or the corresponding JDK wrapper type, e.g. Integer.

These types cannot be used as objects or as type parameters to generic types, which means that many general-purpose utilities cannot be applied to them. Guava provides a number of these general-purpose utilities, ways of interfacing between primitive arrays and collection APIs, conversion from types to byte array representations, and support for unsigned behaviors on certain types.

Primitive Type Guava Utilities (all in com.google.common.primitives)
byte Bytes, SignedBytes, UnsignedBytes
short Shorts
int Ints, UnsignedInteger, UnsignedInts
long Longs, UnsignedLong, UnsignedLongs
float Floats
double Doubles
char Chars
boolean Booleans

Methods that differ in behavior for signed and unsigned bytes are completely skipped in Bytes, but only present in the SignedBytes and UnsignedBytes utilities, since the signedness of bytes is somewhat more ambiguous than the signedness of other types.

Unsigned variants of methods on int and long are provided in the UnsignedInts and UnsignedLongs classes, but since most uses of those types are signed, the Ints and Longs classes treat their inputs as signed.

Additionally, Guava provides "wrapper types" for unsigned int and long values, UnsignedInteger and UnsignedLong, to help you use the type system to enforce distinctions between signed and unsigned values, in exchange for a small performance cost. These classes directly support simple arithmetic operations in the style of BigInteger.

All method signatures use Wrapper to refer to the corresponding JDK wrapper type, and prim to refer to the primitive type. (Prims, where applicable, refers to the corresponding Guava utilities class.)

Primitive array utilities

Primitive arrays are the most efficient way (in both memory and performance) to work with primitive types in aggregate. Guava provides a variety of utilities to work with these methods.

Signature Description Collection analogue Availability
`List Wraps a primitive array Arrays.asList Sign-independent*
: asList(prim... : as a List of the : : :
: backingArray)` : corresponding wrapper : : :
: : type. : : :
`prim[] Copies a collection Collection.toArray() Sign-independent
: toArray(Collection : into a new prim[]. : : :
: collection)` : This method is as : : :
: : thread-safe as : : :
: : collection.toArray(). : : :
`prim[] concat(prim[]... Concatenate several Iterables.concat Sign-independent
: arrays)` : primitive arrays. : : :
`boolean contains(prim[] Determines if the Collection.contains Sign-independent
: array, prim target)` : specified element is in : : :
: : the specified array. : : :
`int indexOf(prim[] array, Finds the index of the List.indexOf Sign-independent
: prim target)` : first appearance of the : : :
: : value target in : : :
: : array, or returns : : :
: : -1 if no such value : : :
: : exists. : : :
`int lastIndexOf(prim[] Finds the index of the List.lastIndexOf Sign-independent
: array, prim target)` : last appearance of the : : :
: : value target in : : :
: : array, or returns : : :
: : -1 if no such value : : :
: : exists. : : :
prim min(prim... array) Returns the minimum Collections.min Sign-dependent**
: : element of the array. : : :
prim max(prim... array) Returns the maximum Collections.max Sign-dependent
: : element of the array. : : :
`String join(String Constructs a string Joiner.on(separator).join Sign-dependent
: separator, prim... array)` : containing the elements : : :
: : of array, separated : : :
: : by separator. : : :
`Comparator A comparator which Ordering.natural().lexicographical() Sign-dependent
: lexicographicalComparator()` : compares primitive : : :
: : arrays : : :
: : lexicographically. : : :

* Sign-independent methods are present in: Bytes, Shorts, Ints, Longs, Floats, Doubles, Chars, Booleans. Not UnsignedInts, UnsignedLongs, SignedBytes, or UnsignedBytes.

** Sign-dependent methods are present in: SignedBytes, UnsignedBytes, Shorts, Ints, Longs, Floats, Doubles, Chars, Booleans, UnsignedInts, UnsignedLongs. Not Bytes.

General utility methods

Guava provides a number of basic utilities which were not part of JDK 6. Some of these methods, however, have since become available in the JDK.

Signature Description Availability
`int compare(prim a, A traditional Sign-dependent
: prim b) :Comparator.compare` : :
: : method, but on the : :
: : primitive types. *Provided : :
: : in the JDK wrapper classes : :
: : as of JDK 7.* : :
`prim checkedCast(long Casts the specified value Sign-dependent for
: value) : toprim, *unless* the : integral types only*` :
: : specified value does not : :
: : fit into a prim, in : :
: : which case an : :
: : IllegalArgumentException : :
: : is thrown. : :
`prim Casts the specified value Sign-dependent for
: saturatedCast(long : to prim, unless the : integral types only :
: value)` : specified value does not : :
: : fit into a prim, in : :
: : which case the closest : :
: : prim value is used. : :

*Here, integral types include byte, short, int, long. Integral types do not include char, boolean, float, or double.

Note: Rounding from double is provided in com.google.common.math.DoubleMath, and supports a variety of rounding modes. See the article for details.

Byte conversion methods

Guava provides methods to convert primitive types to and from byte array representations in big-endian order. All methods are sign-independent, except that Booleans provides none of these methods.

Signature Description
int BYTES Constant representing the number of
: : bytes needed to represent a prim :
: : value. :
prim fromByteArray(byte[] bytes) Returns the prim value whose
: : big-endian representation is the first :
: : Prims.BYTES bytes in the array :
: : bytes. Throws an :
: : IllegalArgumentException if :
: : bytes.length <= Prims.BYTES. :
`prim fromBytes(byte b1, ..., byte Takes Prims.BYTES byte arguments.
: bk) : Returns theprim` value whose byte :
: : representation is the specified bytes :
: : in big-endian order. :
byte[] toByteArray(prim value) Returns an array containing the
: : big-endian byte representation of :
: : value. :

Unsigned support

The UnsignedInts and UnsignedLongs utility classes provide some of the generic utilities that Java provides for signed types in their wrapper classes. UnsignedInts and UnsignedLongs deal with the primitive type directly: it is up to you to make sure that only unsigned values are passed to these utilities.

Additionally, for int and long, Guava provides "unsigned" wrapper types (UnsignedInteger and UnsignedLong to help you enforce distinctions between unsigned and signed values in the type system, in exchange for a small performance penalty.

Generic utilities

These methods' signed analogues are provided in the wrapper classes in the JDK.

Signature Explanation
[`int Parses an unsigned
: UnsignedInts.parseUnsignedInt(String)]
[long : value from a string in :
: UnsignedLongs.parseUnsignedLong(String)`] : base 10. :
[`int UnsignedInts.parseUnsignedInt(String string, Parses an unsigned
: int radix)]
[long : value from a string in :
: UnsignedLongs.parseUnsignedLong(String string, int : the specified base. :
: radix)`] : :
String UnsignedInts.toString(int)
[`String		 Returns a string
: UnsignedLongs.toString(long)`] : representation of the :
: : unsigned value in :
: : base 10. :
[`String UnsignedInts.toString(int value, int Returns a string
: radix)]
[String UnsignedLongs.toString(long : representation of the :
: value, int radix)`] : unsigned value in the :
: : specified base. :

Wrapper

The provided unsigned wrapper types include a number of methods to make their use and conversion easier.

Signature Explanation
UnsignedPrim plus(UnsignedPrim), Simple arithmetic operations.
: minus, times, dividedBy, mod : :
UnsignedPrim valueOf(BigInteger) Returns the value from a BigInteger
: : as an UnsignedPrim, or throw an :
: : IAE if the specified BigInteger :
: : is negative or does not fit. :
UnsignedPrim valueOf(long) Returns the value from the long as
: : an UnsignedPrim, or throw an IAE :
: : if the specified long is negative :
: : or does not fit. :
`UnsignedPrim fromPrimBits(prim View the given value as unsigned. For
: value)` : example, :
: : `UnsignedInteger.fromIntBits(1 << :
: : 31)` has the value 231, :
: : even though 1 << 31 is negative as :
: : an int. :
BigInteger bigIntegerValue() Get the value of this UnsignedPrim
: : as a BigInteger. :
toString(), toString(int radix) Returns a string representation of
: : this unsigned value. :

Clone this wiki locally