Advantages compared to {@code long[]}: * *
Disadvantages compared to {@code long[]}: * *
Advantages compared to {@link com.google.common.collect.ImmutableList ImmutableList}{@code
* Disadvantages compared to {@code ImmutableList The array {@code rest} must not be longer than {@code Integer.MAX_VALUE - 1}.
*/
// Use (first, rest) so that `of(someLongArray)` won't compile (they should use copyOf), which is
// okay since we have to copy the just-created array anyway.
public static ImmutableLongArray of(long first, long... rest) {
checkArgument(
rest.length <= Integer.MAX_VALUE - 1, "the total number of elements must fit in an int");
long[] array = new long[rest.length + 1];
array[0] = first;
System.arraycopy(rest, 0, array, 1, rest.length);
return new ImmutableLongArray(array);
}
/** Returns an immutable array containing the given values, in order. */
public static ImmutableLongArray copyOf(long[] values) {
return values.length == 0
? EMPTY
: new ImmutableLongArray(Arrays.copyOf(values, values.length));
}
/** Returns an immutable array containing the given values, in order. */
public static ImmutableLongArray copyOf(Collection Performance note: this method delegates to {@link #copyOf(Collection)} if {@code
* values} is a {@link Collection}. Otherwise it creates a {@link #builder} and uses {@link
* Builder#addAll(Iterable)}, with all the performance implications associated with that.
*/
public static ImmutableLongArray copyOf(Iterable Performance note: When feasible, {@code 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 {@link
* ImmutableLongArray} that is built will very likely occupy more memory than strictly necessary;
* to trim memory usage, build using {@code builder.build().trimmed()}.
*/
public static Builder builder(int initialCapacity) {
checkArgument(initialCapacity >= 0, "Invalid initialCapacity: %s", initialCapacity);
return new Builder(initialCapacity);
}
/**
* Returns a new, empty builder for {@link ImmutableLongArray} instances, with a default initial
* capacity. The returned builder is not thread-safe.
*
* Performance note: The {@link ImmutableLongArray} that is built will very likely
* occupy more memory than necessary; to trim memory usage, build using {@code
* builder.build().trimmed()}.
*/
public static Builder builder() {
return new Builder(10);
}
/**
* A builder for {@link ImmutableLongArray} instances; obtained using {@link
* ImmutableLongArray#builder}.
*/
@CanIgnoreReturnValue
public static final class Builder {
private long[] array;
private int count = 0; // <= array.length
Builder(int initialCapacity) {
array = new long[initialCapacity];
}
/**
* Appends {@code value} to the end of the values the built {@link ImmutableLongArray} will
* contain.
*/
public Builder add(long value) {
ensureRoomFor(1);
array[count] = value;
count += 1;
return this;
}
/**
* Appends {@code values}, in order, to the end of the values the built {@link
* ImmutableLongArray} will contain.
*/
public Builder addAll(long[] values) {
ensureRoomFor(values.length);
System.arraycopy(values, 0, array, count, values.length);
count += values.length;
return this;
}
/**
* Appends {@code values}, in order, to the end of the values the built {@link
* ImmutableLongArray} will contain.
*/
public Builder addAll(Iterable Performance note: the returned array is backed by the same array as the builder, so
* no data is copied as part of this step, but this may occupy more memory than strictly
* necessary. To copy the data to a right-sized backing array, use {@code .build().trimmed()}.
*/
@CheckReturnValue
public ImmutableLongArray build() {
return count == 0 ? EMPTY : new ImmutableLongArray(array, 0, count);
}
}
// Instance stuff here
// The array is never mutated after storing in this field and the construction strategies ensure
// it doesn't escape this class
@SuppressWarnings("Immutable")
private final long[] array;
/*
* TODO(kevinb): evaluate the trade-offs of going bimorphic to save these two fields from most
* instances. Note that the instances that would get smaller are the right set to care about
* optimizing, because the rest have the option of calling `trimmed`.
*/
private final transient int start; // it happens that we only serialize instances where this is 0
private final int end; // exclusive
private ImmutableLongArray(long[] array) {
this(array, 0, array.length);
}
private ImmutableLongArray(long[] array, int start, int end) {
this.array = array;
this.start = start;
this.end = end;
}
/** Returns the number of values in this array. */
public int length() {
return end - start;
}
/** Returns {@code true} if there are no values in this array ({@link #length} is zero). */
public boolean isEmpty() {
return end == start;
}
/**
* Returns the {@code long} value present at the given index.
*
* @throws IndexOutOfBoundsException if {@code index} is negative, or greater than or equal to
* {@link #length}
*/
public long get(int index) {
Preconditions.checkElementIndex(index, length());
return array[start + index];
}
/**
* Returns the smallest index for which {@link #get} returns {@code target}, or {@code -1} if no
* such index exists. Equivalent to {@code asList().indexOf(target)}.
*/
public int indexOf(long target) {
for (int i = start; i < end; i++) {
if (array[i] == target) {
return i - start;
}
}
return -1;
}
/**
* Returns the largest index for which {@link #get} returns {@code target}, or {@code -1} if no
* such index exists. Equivalent to {@code asList().lastIndexOf(target)}.
*/
public int lastIndexOf(long target) {
for (int i = end - 1; i >= start; i--) {
if (array[i] == target) {
return i - start;
}
}
return -1;
}
/**
* Returns {@code true} if {@code target} is present at any index in this array. Equivalent to
* {@code asList().contains(target)}.
*/
public boolean contains(long target) {
return indexOf(target) >= 0;
}
/** Invokes {@code consumer} for each value contained in this array, in order. */
public void forEach(LongConsumer consumer) {
checkNotNull(consumer);
for (int i = start; i < end; i++) {
consumer.accept(array[i]);
}
}
/** Returns a stream over the values in this array, in order. */
public LongStream stream() {
return Arrays.stream(array, start, end);
}
/** Returns a new, mutable copy of this array's values, as a primitive {@code long[]}. */
public long[] toArray() {
return Arrays.copyOfRange(array, start, end);
}
/**
* 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 {@code subArray(start,
* end).trimmed()}.
*/
public ImmutableLongArray subArray(int startIndex, int endIndex) {
Preconditions.checkPositionIndexes(startIndex, endIndex, length());
return startIndex == endIndex
? EMPTY
: new ImmutableLongArray(array, start + startIndex, start + endIndex);
}
private Spliterator.OfLong spliterator() {
return Spliterators.spliterator(array, start, end, Spliterator.IMMUTABLE | Spliterator.ORDERED);
}
/**
* Returns an immutable view of this array's values as a {@code List}; note that {@code
* long} values are boxed into {@link 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 {@link com.google.common.collect.ImmutableList#copyOf(Collection) ImmutableList.copyOf}
* and use that list instead.
*/
public List
*
*
*
*
*
* @since 22.0
*/
@Beta
@GwtCompatible
@Immutable
@ElementTypesAreNonnullByDefault
public final class ImmutableLongArray implements Serializable {
private static final ImmutableLongArray EMPTY = new ImmutableLongArray(new long[0]);
/** Returns the empty array. */
public static ImmutableLongArray of() {
return EMPTY;
}
/** Returns an immutable array containing a single value. */
public static ImmutableLongArray of(long e0) {
return new ImmutableLongArray(new long[] {e0});
}
/** Returns an immutable array containing the given values, in order. */
public static ImmutableLongArray of(long e0, long e1) {
return new ImmutableLongArray(new long[] {e0, e1});
}
/** Returns an immutable array containing the given values, in order. */
public static ImmutableLongArray of(long e0, long e1, long e2) {
return new ImmutableLongArray(new long[] {e0, e1, e2});
}
/** Returns an immutable array containing the given values, in order. */
public static ImmutableLongArray of(long e0, long e1, long e2, long e3) {
return new ImmutableLongArray(new long[] {e0, e1, e2, e3});
}
/** Returns an immutable array containing the given values, in order. */
public static ImmutableLongArray of(long e0, long e1, long e2, long e3, long e4) {
return new ImmutableLongArray(new long[] {e0, e1, e2, e3, e4});
}
/** Returns an immutable array containing the given values, in order. */
public static ImmutableLongArray of(long e0, long e1, long e2, long e3, long e4, long e5) {
return new ImmutableLongArray(new long[] {e0, e1, e2, e3, e4, e5});
}
// TODO(kevinb): go up to 11?
/**
* Returns an immutable array containing the given values, in order.
*
*