Class ImmutableDoubleArray

  • All Implemented Interfaces:
    java.io.Serializable

    @GwtCompatible
    @Immutable
    public final class ImmutableDoubleArray
    extends java.lang.Object
    implements java.io.Serializable
    An immutable array of double values, with an API resembling List.

    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(), 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 Doubles 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 (like DoubleStream.sum()) using stream() instead of the awkward stream().mapToDouble(v -> v).

    Disadvantages compared to ImmutableList<Double>:

    • 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
    • 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 a List; note that double values are boxed into Double instances on demand, which can be very expensive.
      static ImmutableDoubleArray.Builder builder()
      Returns a new, empty builder for ImmutableDoubleArray instances, with a default initial capacity.
      static ImmutableDoubleArray.Builder builder​(int initialCapacity)
      Returns a new, empty builder for ImmutableDoubleArray instances, sized to hold up to initialCapacity values without resizing.
      boolean contains​(double target)
      Returns true if target 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 from stream, in order.
      boolean equals​(java.lang.Object object)
      Returns true if object is an ImmutableDoubleArray containing the same values as this one, in the same order.
      void forEach​(java.util.function.DoubleConsumer consumer)
      Invokes consumer for each value contained in this array, in order.
      double get​(int index)
      Returns the double value present at the given index.
      int hashCode()
      Returns an unspecified hash code for the contents of this immutable array.
      int indexOf​(double 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​(double 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 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 primitive double[].
      java.lang.String toString()
      Returns a string representation of this array in the same form as Arrays.toString(double[]), for example "[1, 2, 3]".
      ImmutableDoubleArray 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 Detail

      • 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 than Integer.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.util.stream.DoubleStream stream)
        Returns an immutable array containing all the values from stream, 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 for ImmutableDoubleArray 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 ImmutableDoubleArray that is built will very likely occupy more memory than strictly 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 double get​(int index)
        Returns the double value present at the given index.
        Throws:
        java.lang.IndexOutOfBoundsException - if index is negative, or greater than or equal to length()
      • indexOf

        public int indexOf​(double target)
        Returns the smallest index for which get(int) returns target, or -1 if no such index exists. Values are compared as if by Double.equals(java.lang.Object). Equivalent to asList().indexOf(target).
      • lastIndexOf

        public int lastIndexOf​(double target)
        Returns the largest index for which get(int) returns target, or -1 if no such index exists. Values are compared as if by Double.equals(java.lang.Object). Equivalent to asList().lastIndexOf(target).
      • contains

        public boolean contains​(double target)
        Returns true if target is present at any index in this array. Values are compared as if by Double.equals(java.lang.Object). Equivalent to asList().contains(target).
      • forEach

        public void forEach​(java.util.function.DoubleConsumer consumer)
        Invokes consumer 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 primitive double[].
      • 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 a List; note that double values are boxed into Double 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​(@CheckForNull
                              java.lang.Object object)
        Returns true if object is an ImmutableDoubleArray containing the same values as this one, in the same order. Values are compared as if by Double.equals(java.lang.Object).
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Returns an unspecified hash code for the contents of this immutable array.
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Returns a string representation of this array in the same form as Arrays.toString(double[]), for example "[1, 2, 3]".
        Overrides:
        toString in class java.lang.Object
      • trimmed

        public ImmutableDoubleArray 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.