Class ImmutableDoubleArray
- java.lang.Object
-
- com.google.common.primitives.ImmutableDoubleArray
-
- All Implemented Interfaces:
java.io.Serializable
@GwtCompatible @Immutable public final class ImmutableDoubleArray extends java.lang.Object implements java.io.Serializable
An immutable array ofdouble
values, with an API resemblingList
.Advantages compared to
double[]
:- 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
andDoubles
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.getBarDoubles().stream()...
. - Access to all collection-based utilities via
asList()
(though at the cost of allocating garbage).
Disadvantages compared to
double[]
:- 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
double[]
(though the most common utilities do have replacements here). - Dependency on
com.google.common
/ Guava.
Advantages compared to
ImmutableList
<Double>
:- Improved memory compactness and locality.
- Can be queried without allocating garbage.
- Access to
DoubleStream
features (likeDoubleStream.sum()
) usingstream()
instead of the awkwardstream().mapToDouble(v -> v)
.
Disadvantages compared to
ImmutableList<Double>
:- 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
ImmutableDoubleArray.Builder
A builder forImmutableDoubleArray
instances; obtained usingbuilder(int)
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.List<java.lang.Double>
asList()
Returns an immutable view of this array's values as aList
; note thatdouble
values are boxed intoDouble
instances on demand, which can be very expensive.static ImmutableDoubleArray.Builder
builder()
Returns a new, empty builder forImmutableDoubleArray
instances, with a default initial capacity.static ImmutableDoubleArray.Builder
builder(int initialCapacity)
Returns a new, empty builder forImmutableDoubleArray
instances, sized to hold up toinitialCapacity
values without resizing.boolean
contains(double target)
Returnstrue
iftarget
is present at any index in this array.static ImmutableDoubleArray
copyOf(double[] values)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
copyOf(java.lang.Iterable<java.lang.Double> values)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
copyOf(java.util.Collection<java.lang.Double> values)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
copyOf(java.util.stream.DoubleStream stream)
Returns an immutable array containing all the values fromstream
, in order.boolean
equals(java.lang.Object object)
Returnstrue
ifobject
is anImmutableDoubleArray
containing the same values as this one, in the same order.void
forEach(java.util.function.DoubleConsumer consumer)
Invokesconsumer
for each value contained in this array, in order.double
get(int index)
Returns thedouble
value present at the given index.int
hashCode()
Returns an unspecified hash code for the contents of this immutable array.int
indexOf(double target)
boolean
isEmpty()
Returnstrue
if there are no values in this array (length()
is zero).int
lastIndexOf(double target)
int
length()
Returns the number of values in this array.static ImmutableDoubleArray
of()
Returns the empty array.static ImmutableDoubleArray
of(double e0)
Returns an immutable array containing a single value.static ImmutableDoubleArray
of(double e0, double e1)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
of(double first, double... rest)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
of(double e0, double e1, double e2)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
of(double e0, double e1, double e2, double e3)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
of(double e0, double e1, double e2, double e3, double e4)
Returns an immutable array containing the given values, in order.static ImmutableDoubleArray
of(double e0, double e1, double e2, double e3, double e4, double e5)
Returns an immutable array containing the given values, in order.java.util.stream.DoubleStream
stream()
Returns a stream over the values in this array, in order.ImmutableDoubleArray
subArray(int startIndex, int endIndex)
Returns a new immutable array containing the values in the specified range.double[]
toArray()
Returns a new, mutable copy of this array's values, as a primitivedouble[]
.java.lang.String
toString()
Returns a string representation of this array in the same form asArrays.toString(double[])
, for example"[1, 2, 3]"
.ImmutableDoubleArray
trimmed()
Returns an immutable array containing the same values asthis
array.
-
-
-
Method Detail
-
of
public static ImmutableDoubleArray of()
Returns the empty array.
-
of
public static ImmutableDoubleArray of(double e0)
Returns an immutable array containing a single value.
-
of
public static ImmutableDoubleArray of(double e0, double e1)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableDoubleArray of(double e0, double e1, double e2)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableDoubleArray of(double e0, double e1, double e2, double e3)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableDoubleArray of(double e0, double e1, double e2, double e3, double e4)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableDoubleArray of(double e0, double e1, double e2, double e3, double e4, double e5)
Returns an immutable array containing the given values, in order.
-
of
public static ImmutableDoubleArray of(double first, double... 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 ImmutableDoubleArray copyOf(double[] values)
Returns an immutable array containing the given values, in order.
-
copyOf
public static ImmutableDoubleArray copyOf(java.util.Collection<java.lang.Double> values)
Returns an immutable array containing the given values, in order.
-
copyOf
public static ImmutableDoubleArray copyOf(java.lang.Iterable<java.lang.Double> 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 usesImmutableDoubleArray.Builder.addAll(Iterable)
, with all the performance implications associated with that.
-
copyOf
public static ImmutableDoubleArray copyOf(java.util.stream.DoubleStream stream)
Returns an immutable array containing all the values fromstream
, in order.- Since:
- NEXT (but since 22.0 in the JRE flavor)
-
builder
public static ImmutableDoubleArray.Builder builder(int initialCapacity)
Returns a new, empty builder forImmutableDoubleArray
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, theImmutableDoubleArray
that is built will very likely occupy more memory than strictly necessary; to trim memory usage, build usingbuilder.build().trimmed()
.
-
builder
public static ImmutableDoubleArray.Builder builder()
Returns a new, empty builder forImmutableDoubleArray
instances, with a default initial capacity. The returned builder is not thread-safe.Performance note: The
ImmutableDoubleArray
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 double get(int index)
Returns thedouble
value present at the given index.- Throws:
java.lang.IndexOutOfBoundsException
- ifindex
is negative, or greater than or equal tolength()
-
indexOf
public int indexOf(double target)
Returns the smallest index for whichget(int)
returnstarget
, or-1
if no such index exists. Values are compared as if byDouble.equals(java.lang.Object)
. Equivalent toasList().indexOf(target)
.
-
lastIndexOf
public int lastIndexOf(double target)
Returns the largest index for whichget(int)
returnstarget
, or-1
if no such index exists. Values are compared as if byDouble.equals(java.lang.Object)
. Equivalent toasList().lastIndexOf(target)
.
-
contains
public boolean contains(double target)
Returnstrue
iftarget
is present at any index in this array. Values are compared as if byDouble.equals(java.lang.Object)
. Equivalent toasList().contains(target)
.
-
forEach
public void forEach(java.util.function.DoubleConsumer consumer)
Invokesconsumer
for each value contained in this array, in order.- Since:
- NEXT (but since 22.0 in the JRE flavor)
-
stream
public java.util.stream.DoubleStream stream()
Returns a stream over the values in this array, in order.- Since:
- NEXT (but since 22.0 in the JRE flavor)
-
toArray
public double[] toArray()
Returns a new, mutable copy of this array's values, as a primitivedouble[]
.
-
subArray
public ImmutableDoubleArray 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.Double> asList()
Returns an immutable view of this array's values as aList
; note thatdouble
values are boxed intoDouble
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 anImmutableDoubleArray
containing the same values as this one, in the same order. Values are compared as if byDouble.equals(java.lang.Object)
.- 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(double[])
, for example"[1, 2, 3]"
.- Overrides:
toString
in classjava.lang.Object
-
trimmed
public ImmutableDoubleArray 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.
-
-