Class ImmutableIntArray
- java.lang.Object
-
- com.google.common.primitives.ImmutableIntArray
-
- All Implemented Interfaces:
java.io.Serializable
@GwtCompatible @Immutable public final class ImmutableIntArray extends java.lang.Object implements java.io.Serializable
An immutable array ofint
values, with an API resemblingList
.Advantages compared to
int[]
:- All the many well-known advantages of immutability (read Effective Java, third edition, Item 17).
- Has the value-based (not identity-based)
equals(java.lang.Object)
,hashCode()
, andtoString()
behavior you expect. - Offers useful operations beyond just
get
andlength
, so you don't have to hunt through classes likeArrays
andInts
for them. - Supports a copy-free
subArray(int, int)
view, so methods that accept this type don't need to add overloads that accept start and end indexes. - Can be streamed without "breaking the chain":
foo.getBarInts().stream()...
. - Access to all collection-based utilities via
asList()
(though at the cost of allocating garbage).
Disadvantages compared to
int[]
:- Memory footprint has a fixed overhead (about 24 bytes per instance).
- Some construction use cases force the data to be copied (though several construction APIs are offered that don't).
- Can't be passed directly to methods that expect
int[]
(though the most common utilities do have replacements here). - Dependency on
com.google.common
/ Guava.
Advantages compared to
ImmutableList
<Integer>
:- Improved memory compactness and locality.
- Can be queried without allocating garbage.
- Access to
IntStream
features (likeIntStream.sum()
) usingstream()
instead of the awkwardstream().mapToInt(v -> v)
.
Disadvantages compared to
ImmutableList<Integer>
:- Can't be passed directly to methods that expect
Iterable
,Collection
, orList
(though the most common utilities do have replacements here, and there is a lazyasList()
view).
- Since:
- 22.0
- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
ImmutableIntArray.Builder
A builder forImmutableIntArray
instances; obtained usingbuilder(int)
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.List<java.lang.Integer>
asList()
Returns an immutable view of this array's values as aList
; note thatint
values are boxed intoInteger
instances on demand, which can be very expensive.static ImmutableIntArray.Builder
builder()
Returns a new, empty builder forImmutableIntArray
instances, with a default initial capacity.static ImmutableIntArray.Builder
builder(int initialCapacity)
Returns a new, empty builder forImmutableIntArray
instances, sized to hold up toinitialCapacity
values without resizing.boolean
contains(int target)
Returnstrue
iftarget
is present at any index in this array.static ImmutableIntArray
copyOf(int[] values)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
copyOf(java.lang.Iterable<java.lang.Integer> values)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
copyOf(java.util.Collection<java.lang.Integer> values)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
copyOf(java.util.stream.IntStream stream)
Returns an immutable array containing all the values fromstream
, in order.boolean
equals(java.lang.Object object)
Returnstrue
ifobject
is anImmutableIntArray
containing the same values as this one, in the same order.void
forEach(java.util.function.IntConsumer consumer)
Invokesconsumer
for each value contained in this array, in order.int
get(int index)
Returns theint
value present at the given index.int
hashCode()
Returns an unspecified hash code for the contents of this immutable array.int
indexOf(int target)
boolean
isEmpty()
Returnstrue
if there are no values in this array (length()
is zero).int
lastIndexOf(int target)
int
length()
Returns the number of values in this array.static ImmutableIntArray
of()
Returns the empty array.static ImmutableIntArray
of(int e0)
Returns an immutable array containing a single value.static ImmutableIntArray
of(int e0, int e1)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
of(int first, int... rest)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
of(int e0, int e1, int e2)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
of(int e0, int e1, int e2, int e3)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
of(int e0, int e1, int e2, int e3, int e4)
Returns an immutable array containing the given values, in order.static ImmutableIntArray
of(int e0, int e1, int e2, int e3, int e4, int e5)
Returns an immutable array containing the given values, in order.java.util.stream.IntStream
stream()
Returns a stream over the values in this array, in order.ImmutableIntArray
subArray(int startIndex, int endIndex)
Returns a new immutable array containing the values in the specified range.int[]
toArray()
Returns a new, mutable copy of this array's values, as a primitiveint[]
.java.lang.String
toString()
Returns a string representation of this array in the same form asArrays.toString(int[])
, for example"[1, 2, 3]"
.ImmutableIntArray
trimmed()
Returns an immutable array containing the same values asthis
array.
-
-
-
Method Detail
-
of
public static ImmutableIntArray of()
Returns the empty array.
-
of
public static ImmutableIntArray of(int e0)
Returns an immutable array containing a single value.
-
of
public static ImmutableIntArray of(int e0, int e1)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableIntArray of(int e0, int e1, int e2)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableIntArray of(int e0, int e1, int e2, int e3)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableIntArray of(int e0, int e1, int e2, int e3, int e4)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableIntArray of(int e0, int e1, int e2, int e3, int e4, int e5)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableIntArray of(int first, int... rest)
Returns an immutable array containing the given values, in order.The array
rest
must not be longer thanInteger.MAX_VALUE - 1
.
-
copyOf
public static ImmutableIntArray copyOf(int[] values)
Returns an immutable array containing the given values, in order.
-
copyOf
public static ImmutableIntArray copyOf(java.util.Collection<java.lang.Integer> values)
Returns an immutable array containing the given values, in order.
-
copyOf
public static ImmutableIntArray copyOf(java.lang.Iterable<java.lang.Integer> values)
Returns an immutable array containing the given values, in order.Performance note: this method delegates to
copyOf(Collection)
ifvalues
is aCollection
. Otherwise it creates abuilder(int)
and usesImmutableIntArray.Builder.addAll(Iterable)
, with all the performance implications associated with that.
-
copyOf
public static ImmutableIntArray copyOf(java.util.stream.IntStream stream)
Returns an immutable array containing all the values fromstream
, in order.
-
builder
public static ImmutableIntArray.Builder builder(int initialCapacity)
Returns a new, empty builder forImmutableIntArray
instances, sized to hold up toinitialCapacity
values without resizing. The returned builder is not thread-safe.Performance note: When feasible,
initialCapacity
should be the exact number of values that will be added, if that knowledge is readily available. It is better to guess a value slightly too high than slightly too low. If the value is not exact, theImmutableIntArray
that is built will very likely occupy more memory than strictly necessary; to trim memory usage, build usingbuilder.build().trimmed()
.
-
builder
public static ImmutableIntArray.Builder builder()
Returns a new, empty builder forImmutableIntArray
instances, with a default initial capacity. The returned builder is not thread-safe.Performance note: The
ImmutableIntArray
that is built will very likely occupy more memory than necessary; to trim memory usage, build usingbuilder.build().trimmed()
.
-
length
public int length()
Returns the number of values in this array.
-
isEmpty
public boolean isEmpty()
Returnstrue
if there are no values in this array (length()
is zero).
-
get
public int get(int index)
Returns theint
value present at the given index.- Throws:
java.lang.IndexOutOfBoundsException
- ifindex
is negative, or greater than or equal tolength()
-
indexOf
public int indexOf(int target)
Returns the smallest index for whichget(int)
returnstarget
, or-1
if no such index exists. Equivalent toasList().indexOf(target)
.
-
lastIndexOf
public int lastIndexOf(int target)
Returns the largest index for whichget(int)
returnstarget
, or-1
if no such index exists. Equivalent toasList().lastIndexOf(target)
.
-
contains
public boolean contains(int target)
Returnstrue
iftarget
is present at any index in this array. Equivalent toasList().contains(target)
.
-
forEach
public void forEach(java.util.function.IntConsumer consumer)
Invokesconsumer
for each value contained in this array, in order.
-
stream
public java.util.stream.IntStream stream()
Returns a stream over the values in this array, in order.
-
toArray
public int[] toArray()
Returns a new, mutable copy of this array's values, as a primitiveint[]
.
-
subArray
public ImmutableIntArray subArray(int startIndex, int endIndex)
Returns a new immutable array containing the values in the specified range.Performance note: The returned array has the same full memory footprint as this one does (no actual copying is performed). To reduce memory usage, use
subArray(start, end).trimmed()
.
-
asList
public java.util.List<java.lang.Integer> asList()
Returns an immutable view of this array's values as aList
; note thatint
values are boxed intoInteger
instances on demand, which can be very expensive. The returned list should be used once and discarded. For any usages beyond that, pass the returned list toImmutableList.copyOf
and use that list instead.
-
equals
public boolean equals(@CheckForNull java.lang.Object object)
Returnstrue
ifobject
is anImmutableIntArray
containing the same values as this one, in the same order.- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
Returns an unspecified hash code for the contents of this immutable array.- Overrides:
hashCode
in classjava.lang.Object
-
toString
public java.lang.String toString()
Returns a string representation of this array in the same form asArrays.toString(int[])
, for example"[1, 2, 3]"
.- Overrides:
toString
in classjava.lang.Object
-
trimmed
public ImmutableIntArray trimmed()
Returns an immutable array containing the same values asthis
array. This is logically a no-op, and in some circumstancesthis
itself is returned. However, if this instance is asubArray(int, int)
view of a larger array, this method will copy only the appropriate range of values, resulting in an equivalent array with a smaller memory footprint.
-
-