Class ImmutableLongArray

java.lang.Object

com.google.common.primitives.ImmutableLongArray

All Implemented Interfaces:

Serializable

@GwtCompatible
@Immutable
public final class ImmutableLongArray
extends Object
implements Serializable

An immutable array of long values, with an API resembling List.

Advantages compared to long[]:

• 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(), and toString() behavior you expect.
• Offers useful operations beyond just get and length, so you don't have to hunt through classes like Arrays and Longs 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.getBarLongs().stream()....
• Access to all collection-based utilities via asList() (though at the cost of allocating garbage).

Disadvantages compared to long[]:

• 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 long[] (though the most common utilities do have replacements here).
• Dependency on com.google.common / Guava.

Advantages compared to ImmutableList <Long>:

• Improved memory compactness and locality.
• Can be queried without allocating garbage.
• Access to LongStream features (like LongStream.sum()) using stream() instead of the awkward stream().mapToLong(v -> v).

Disadvantages compared to ImmutableList<Long>:

• Can't be passed directly to methods that expect Iterable, Collection, or List (though the most common utilities do have replacements here, and there is a lazy asList() view).

Since:

22.0

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	ImmutableLongArray.Builder	A builder for ImmutableLongArray instances; obtained using builder(int).

Method Summary

Modifier and Type	Method	Description
List<Long>	asList()	Returns an immutable view of this array's values as a List; note that long values are boxed into Long instances on demand, which can be very expensive.
static ImmutableLongArray.Builder	builder()	Returns a new, empty builder for ImmutableLongArray instances, with a default initial capacity.
static ImmutableLongArray.Builder	builder(int initialCapacity)	Returns a new, empty builder for ImmutableLongArray instances, sized to hold up to initialCapacity values without resizing.
boolean	contains(long target)	Returns true if target is present at any index in this array.
static ImmutableLongArray	copyOf(long[] values)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	copyOf(Iterable<Long> values)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	copyOf(Collection<Long> values)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	copyOf(LongStream stream)	Returns an immutable array containing all the values from stream, in order.
boolean	equals(@Nullable Object object)	Returns true if object is an ImmutableLongArray containing the same values as this one, in the same order.
void	forEach(LongConsumer consumer)	Invokes consumer for each value contained in this array, in order.
long	get(int index)	Returns the long value present at the given index.
int	hashCode()	Returns an unspecified hash code for the contents of this immutable array.
int	indexOf(long target)	Returns the smallest index for which get(int) returns target, or -1 if no such index exists.
boolean	isEmpty()	Returns true if there are no values in this array (length() is zero).
int	lastIndexOf(long target)	Returns the largest index for which get(int) returns target, or -1 if no such index exists.
int	length()	Returns the number of values in this array.
static ImmutableLongArray	of()	Returns the empty array.
static ImmutableLongArray	of(long e0)	Returns an immutable array containing a single value.
static ImmutableLongArray	of(long e0, long e1)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	of(long first, long... rest)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	of(long e0, long e1, long e2)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	of(long e0, long e1, long e2, long e3)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	of(long e0, long e1, long e2, long e3, long e4)	Returns an immutable array containing the given values, in order.
static ImmutableLongArray	of(long e0, long e1, long e2, long e3, long e4, long e5)	Returns an immutable array containing the given values, in order.
LongStream	stream()	Returns a stream over the values in this array, in order.
ImmutableLongArray	subArray(int startIndex, int endIndex)	Returns a new immutable array containing the values in the specified range.
long[]	toArray()	Returns a new, mutable copy of this array's values, as a primitive long[].
String	toString()	Returns a string representation of this array in the same form as Arrays.toString(long[]), for example "[1, 2, 3]".
ImmutableLongArray	trimmed()	Returns an immutable array containing the same values as this array.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details

of

public static ImmutableLongArray of()

Returns the empty array.

of

public static ImmutableLongArray of(long e0)

Returns an immutable array containing a single value.

of

public static ImmutableLongArray of(long e0,
 long e1)

Returns an immutable array containing the given values, in order.

of

public static ImmutableLongArray of(long e0,
 long e1,
 long e2)

Returns an immutable array containing the given values, in order.

of

public static ImmutableLongArray of(long e0,
 long e1,
 long e2,
 long e3)

Returns an immutable array containing the given values, in order.

of

public static ImmutableLongArray of(long e0,
 long e1,
 long e2,
 long e3,
 long e4)

Returns an immutable array containing the given values, in order.

of

public static ImmutableLongArray of(long e0,
 long e1,
 long e2,
 long e3,
 long e4,
 long e5)

Returns an immutable array containing the given values, in order.

of

public static ImmutableLongArray of(long first,
 long... rest)

Returns an immutable array containing the given values, in order.

The array rest must not be longer than Integer.MAX_VALUE - 1.

copyOf

public static ImmutableLongArray copyOf(long[] values)

Returns an immutable array containing the given values, in order.

copyOf

public static ImmutableLongArray copyOf(Collection<Long> values)

Returns an immutable array containing the given values, in order.

copyOf

public static ImmutableLongArray copyOf(Iterable<Long> values)

Returns an immutable array containing the given values, in order.

Performance note: this method delegates to copyOf(Collection) if values is a Collection. Otherwise it creates a builder(int) and uses ImmutableLongArray.Builder.addAll(Iterable), with all the performance implications associated with that.

copyOf

public static ImmutableLongArray copyOf(LongStream stream)

Returns an immutable array containing all the values from stream, in order.

Since:

33.4.0 (but since 22.0 in the JRE flavor)

builder

public static ImmutableLongArray.Builder builder(int initialCapacity)

Returns a new, empty builder for ImmutableLongArray instances, sized to hold up to initialCapacity 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, the ImmutableLongArray that is built will very likely occupy more memory than strictly necessary; to trim memory usage, build using builder.build().trimmed().

builder

public static ImmutableLongArray.Builder builder()

Returns a new, empty builder for ImmutableLongArray instances, with a default initial capacity. The returned builder is not thread-safe.

Performance note: The ImmutableLongArray that is built will very likely occupy more memory than necessary; to trim memory usage, build using builder.build().trimmed().

length

public int length()

Returns the number of values in this array.

isEmpty

public boolean isEmpty()

Returns true if there are no values in this array (length() is zero).

get

public long get(int index)

Returns the long value present at the given index.

Throws:

IndexOutOfBoundsException - if index is negative, or greater than or equal to length()

indexOf

public int indexOf(long target)

Returns the smallest index for which get(int) returns target, or -1 if no such index exists. Equivalent to asList().indexOf(target).

lastIndexOf

public int lastIndexOf(long target)

Returns the largest index for which get(int) returns target, or -1 if no such index exists. Equivalent to asList().lastIndexOf(target).

contains

public boolean contains(long target)

Returns true if target is present at any index in this array. Equivalent to asList().contains(target).

forEach

public void forEach(LongConsumer consumer)

Invokes consumer for each value contained in this array, in order.

Since:

33.4.0 (but since 22.0 in the JRE flavor)

stream

public LongStream stream()

Returns a stream over the values in this array, in order.

Since:

33.4.0 (but since 22.0 in the JRE flavor)

toArray

public long[] toArray()

Returns a new, mutable copy of this array's values, as a primitive long[].

subArray

public ImmutableLongArray 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 List<Long> asList()

Returns an immutable view of this array's values as a List; note that long values are boxed into Long 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 to ImmutableList.copyOf and use that list instead.

equals

public boolean equals(@Nullable Object object)

Returns true if object is an ImmutableLongArray containing the same values as this one, in the same order.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns an unspecified hash code for the contents of this immutable array.

Overrides:

hashCode in class Object

toString

public String toString()

Returns a string representation of this array in the same form as Arrays.toString(long[]), for example "[1, 2, 3]".

Overrides:

toString in class Object

trimmed

public ImmutableLongArray trimmed()

Returns an immutable array containing the same values as this array. This is logically a no-op, and in some circumstances this itself is returned. However, if this instance is a subArray(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.