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. - 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
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.boolean
equals(java.lang.Object object)
Returnstrue
ifobject
is anImmutableIntArray
containing the same values as this one, in the same 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.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.
-
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)
.
-
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.
-
-