Class LongArray

  • All Implemented Interfaces:
    Matrix, Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean

    public final class LongArray
    extends Object
    implements Matrix, org.joda.beans.ImmutableBean, Serializable
    An immutable array of long values.

    This provides functionality similar to List but for long[].

    In mathematical terms, this is a vector, or one-dimensional matrix.

    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static LongArray EMPTY
      An empty array.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      LongArray combine​(LongArray other, LongBinaryOperator operator)
      Returns an instance where each element is formed by some combination of the matching values in this array and the other array.
      long combineReduce​(LongArray other, LongTernaryOperator operator)
      Combines this array and the other array returning a reduced value.
      LongArray concat​(long... arrayToConcat)
      Returns an array that combines this array and the specified array.
      LongArray concat​(LongArray arrayToConcat)
      Returns an array that combines this array and the specified array.
      boolean contains​(long value)
      Checks if this array contains the specified value.
      void copyInto​(long[] destination, int offset)
      Copies this array into the specified array.
      static LongArray copyOf​(long[] array)
      Obtains an instance from an array of long.
      static LongArray copyOf​(long[] array, int fromIndex)
      Obtains an instance by copying part of an array.
      static LongArray copyOf​(long[] array, int fromIndexInclusive, int toIndexExclusive)
      Obtains an instance by copying part of an array.
      static LongArray copyOf​(Collection<Long> collection)
      Obtains an instance from a collection of Long.
      int dimensions()
      Gets the number of dimensions of this array.
      LongArray dividedBy​(long divisor)
      Returns an instance with each value divided by the specified divisor.
      LongArray dividedBy​(LongArray other)
      Returns an instance where each element is calculated by dividing values in this array by values in the other array.
      boolean equals​(Object obj)  
      static LongArray filled​(int size)
      Obtains an instance with all entries equal to the zero.
      static LongArray filled​(int size, long value)
      Obtains an instance with all entries equal to the same value.
      void forEach​(IntLongConsumer action)
      Applies an action to each value in the array.
      long get​(int index)
      Gets the value at the specified index in this array.
      int hashCode()  
      int indexOf​(long value)
      Find the index of the first occurrence of the specified value.
      boolean isEmpty()
      Checks if this array is empty.
      int lastIndexOf​(long value)
      Find the index of the first occurrence of the specified value.
      LongArray map​(LongUnaryOperator operator)
      Returns an instance with an operation applied to each value in the array.
      LongArray mapWithIndex​(IntLongToLongFunction function)
      Returns an instance with an operation applied to each indexed value in the array.
      long max()
      Returns the minimum value held in the array.
      org.joda.beans.MetaBean metaBean()  
      long min()
      Returns the minimum value held in the array.
      LongArray minus​(long amount)
      Returns an instance with the specified amount subtracted from each value.
      LongArray minus​(LongArray other)
      Returns an instance where each element is equal to the difference between the matching values in this array and the other array.
      LongArray multipliedBy​(long factor)
      Returns an instance with each value multiplied by the specified factor.
      LongArray multipliedBy​(LongArray other)
      Returns an instance where each element is equal to the product of the matching values in this array and the other array.
      static LongArray of()
      Obtains an empty immutable array.
      static LongArray of​(int size, IntToLongFunction valueFunction)
      Obtains an instance with entries filled using a function.
      static LongArray of​(long value)
      Obtains an immutable array with a single value.
      static LongArray of​(long value1, long value2)
      Obtains an immutable array with two values.
      static LongArray of​(long value1, long value2, long value3)
      Obtains an immutable array with three values.
      static LongArray of​(long value1, long value2, long value3, long value4)
      Obtains an immutable array with four values.
      static LongArray of​(long value1, long value2, long value3, long value4, long value5)
      Obtains an immutable array with five values.
      static LongArray of​(long value1, long value2, long value3, long value4, long value5, long value6)
      Obtains an immutable array with six values.
      static LongArray of​(long value1, long value2, long value3, long value4, long value5, long value6, long value7)
      Obtains an immutable array with seven values.
      static LongArray of​(long value1, long value2, long value3, long value4, long value5, long value6, long value7, long value8)
      Obtains an immutable array with eight values.
      static LongArray of​(long value1, long value2, long value3, long value4, long value5, long value6, long value7, long value8, long... otherValues)
      Obtains an immutable array with more than eight values.
      static LongArray of​(LongStream stream)
      Obtains an instance with entries filled from a stream.
      static LongArray ofUnsafe​(long[] array)
      Obtains an instance by wrapping an array.
      LongArray plus​(long amount)
      Returns an instance with the specified amount added to each value.
      LongArray plus​(LongArray other)
      Returns an instance where each element is the sum of the matching values in this array and the other array.
      long reduce​(long identity, LongBinaryOperator operator)
      Reduces this array returning a single value.
      int size()
      Gets the size of this array.
      LongArray sorted()
      Returns a sorted copy of this array.
      LongStream stream()
      Returns a stream over the array values.
      LongArray subArray​(int fromIndexInclusive)
      Returns an array holding the values from the specified index onwards.
      LongArray subArray​(int fromIndexInclusive, int toIndexExclusive)
      Returns an array holding the values between the specified from and to indices.
      long sum()
      Returns the sum of all the values in the array.
      long[] toArray()
      Converts this instance to an independent long[].
      long[] toArrayUnsafe()
      Returns the underlying array.
      List<Long> toList()
      Returns a list equivalent to this array.
      String toString()  
      LongArray with​(int index, long newValue)
      Returns an instance with the value at the specified index changed.
      • Methods inherited from interface org.joda.beans.Bean

        property, propertyNames
    • Field Detail

      • EMPTY

        public static final LongArray EMPTY
        An empty array.
    • Method Detail

      • of

        public static LongArray of()
        Obtains an empty immutable array.
        Returns:
        the empty immutable array
      • of

        public static LongArray of​(long value)
        Obtains an immutable array with a single value.
        Parameters:
        value - the single value
        Returns:
        an array containing the specified value
      • of

        public static LongArray of​(long value1,
                                   long value2)
        Obtains an immutable array with two values.
        Parameters:
        value1 - the first value
        value2 - the second value
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(long value1,
                                   long value2,
                                   long value3)
        Obtains an immutable array with three values.
        Parameters:
        value1 - the first value
        value2 - the second value
        value3 - the third value
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(long value1,
                                   long value2,
                                   long value3,
                                   long value4)
        Obtains an immutable array with four values.
        Parameters:
        value1 - the first value
        value2 - the second value
        value3 - the third value
        value4 - the fourth value
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(long value1,
                                   long value2,
                                   long value3,
                                   long value4,
                                   long value5)
        Obtains an immutable array with five values.
        Parameters:
        value1 - the first value
        value2 - the second value
        value3 - the third value
        value4 - the fourth value
        value5 - the fifth value
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(long value1,
                                   long value2,
                                   long value3,
                                   long value4,
                                   long value5,
                                   long value6)
        Obtains an immutable array with six values.
        Parameters:
        value1 - the first value
        value2 - the second value
        value3 - the third value
        value4 - the fourth value
        value5 - the fifth value
        value6 - the sixth value
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(long value1,
                                   long value2,
                                   long value3,
                                   long value4,
                                   long value5,
                                   long value6,
                                   long value7)
        Obtains an immutable array with seven values.
        Parameters:
        value1 - the first value
        value2 - the second value
        value3 - the third value
        value4 - the fourth value
        value5 - the fifth value
        value6 - the sixth value
        value7 - the seventh value
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(long value1,
                                   long value2,
                                   long value3,
                                   long value4,
                                   long value5,
                                   long value6,
                                   long value7,
                                   long value8)
        Obtains an immutable array with eight values.
        Parameters:
        value1 - the first value
        value2 - the second value
        value3 - the third value
        value4 - the fourth value
        value5 - the fifth value
        value6 - the sixth value
        value7 - the seventh value
        value8 - the eighth value
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(long value1,
                                   long value2,
                                   long value3,
                                   long value4,
                                   long value5,
                                   long value6,
                                   long value7,
                                   long value8,
                                   long... otherValues)
        Obtains an immutable array with more than eight values.
        Parameters:
        value1 - the first value
        value2 - the second value
        value3 - the third value
        value4 - the fourth value
        value5 - the fifth value
        value6 - the sixth value
        value7 - the seventh value
        value8 - the eighth value
        otherValues - the other values
        Returns:
        an array containing the specified values
      • of

        public static LongArray of​(int size,
                                   IntToLongFunction valueFunction)
        Obtains an instance with entries filled using a function.

        The function is passed the array index and returns the value for that index.

        Parameters:
        size - the number of elements
        valueFunction - the function used to populate the value
        Returns:
        an array initialized using the function
      • of

        public static LongArray of​(LongStream stream)
        Obtains an instance with entries filled from a stream.

        The stream is converted to an array using LongStream.toArray().

        Parameters:
        stream - the stream of elements
        Returns:
        an array initialized using the stream
      • ofUnsafe

        public static LongArray ofUnsafe​(long[] array)
        Obtains an instance by wrapping an array.

        This method is inherently unsafe as it relies on good behavior by callers. Callers must never make any changes to the passed in array after calling this method. Doing so would violate the immutability of this class.

        Parameters:
        array - the array to assign
        Returns:
        an array instance wrapping the specified array
      • copyOf

        public static LongArray copyOf​(Collection<Long> collection)
        Obtains an instance from a collection of Long.

        The order of the values in the returned array is the order in which elements are returned from the iterator of the collection.

        Parameters:
        collection - the collection to initialize from
        Returns:
        an array containing the values from the collection in iteration order
      • copyOf

        public static LongArray copyOf​(long[] array)
        Obtains an instance from an array of long.

        The input array is copied and not mutated.

        Parameters:
        array - the array to copy, cloned
        Returns:
        an array containing the specified values
      • copyOf

        public static LongArray copyOf​(long[] array,
                                       int fromIndex)
        Obtains an instance by copying part of an array.

        The input array is copied and not mutated.

        Parameters:
        array - the array to copy
        fromIndex - the offset from the start of the array
        Returns:
        an array containing the specified values
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • copyOf

        public static LongArray copyOf​(long[] array,
                                       int fromIndexInclusive,
                                       int toIndexExclusive)
        Obtains an instance by copying part of an array.

        The input array is copied and not mutated.

        Parameters:
        array - the array to copy
        fromIndexInclusive - the start index of the input array to copy from
        toIndexExclusive - the end index of the input array to copy to
        Returns:
        an array containing the specified values
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • filled

        public static LongArray filled​(int size)
        Obtains an instance with all entries equal to the zero.
        Parameters:
        size - the number of elements
        Returns:
        an array filled with zeroes
      • filled

        public static LongArray filled​(int size,
                                       long value)
        Obtains an instance with all entries equal to the same value.
        Parameters:
        size - the number of elements
        value - the value of all the elements
        Returns:
        an array filled with the specified value
      • dimensions

        public int dimensions()
        Gets the number of dimensions of this array.
        Specified by:
        dimensions in interface Matrix
        Returns:
        one
      • size

        public int size()
        Gets the size of this array.
        Specified by:
        size in interface Matrix
        Returns:
        the array size, zero or greater
      • isEmpty

        public boolean isEmpty()
        Checks if this array is empty.
        Returns:
        true if empty
      • get

        public long get​(int index)
        Gets the value at the specified index in this array.
        Parameters:
        index - the zero-based index to retrieve
        Returns:
        the value at the index
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • contains

        public boolean contains​(long value)
        Checks if this array contains the specified value.
        Parameters:
        value - the value to find
        Returns:
        true if the value is contained in this array
      • indexOf

        public int indexOf​(long value)
        Find the index of the first occurrence of the specified value.
        Parameters:
        value - the value to find
        Returns:
        the index of the value, -1 if not found
      • lastIndexOf

        public int lastIndexOf​(long value)
        Find the index of the first occurrence of the specified value.
        Parameters:
        value - the value to find
        Returns:
        the index of the value, -1 if not found
      • copyInto

        public void copyInto​(long[] destination,
                             int offset)
        Copies this array into the specified array.

        The specified array must be at least as large as this array. If it is larger, then the remainder of the array will be untouched.

        Parameters:
        destination - the array to copy into
        offset - the offset in the destination array to start from
        Throws:
        IndexOutOfBoundsException - if the destination array is not large enough or the offset is negative
      • subArray

        public LongArray subArray​(int fromIndexInclusive)
        Returns an array holding the values from the specified index onwards.
        Parameters:
        fromIndexInclusive - the start index of the array to copy from
        Returns:
        an array instance with the specified bounds
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • subArray

        public LongArray subArray​(int fromIndexInclusive,
                                  int toIndexExclusive)
        Returns an array holding the values between the specified from and to indices.
        Parameters:
        fromIndexInclusive - the start index of the array to copy from
        toIndexExclusive - the end index of the array to copy to
        Returns:
        an array instance with the specified bounds
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • toArray

        public long[] toArray()
        Converts this instance to an independent long[].
        Returns:
        a copy of the underlying array
      • toArrayUnsafe

        public long[] toArrayUnsafe()
        Returns the underlying array.

        This method is inherently unsafe as it relies on good behavior by callers. Callers must never make any changes to the array returned by this method. Doing so would violate the immutability of this class.

        Returns:
        the raw array
      • toList

        public List<Long> toList()
        Returns a list equivalent to this array.
        Returns:
        a list wrapping this array
      • stream

        public LongStream stream()
        Returns a stream over the array values.
        Returns:
        a stream over the values in the array
      • forEach

        public void forEach​(IntLongConsumer action)
        Applies an action to each value in the array.

        This is used to perform an action on the contents of this array. The action receives both the index and the value. For example, the action could print out the array.

           base.forEach((index, value) -> System.out.println(index + ": " + value));
         

        This instance is immutable and unaffected by this method.

        Parameters:
        action - the action to be applied
      • with

        public LongArray with​(int index,
                              long newValue)
        Returns an instance with the value at the specified index changed.

        This instance is immutable and unaffected by this method.

        Parameters:
        index - the zero-based index to set
        newValue - the new value to store
        Returns:
        a copy of this array with the value at the index changed
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • plus

        public LongArray plus​(long amount)
        Returns an instance with the specified amount added to each value.

        This is used to add to the contents of this array, returning a new array.

        This is a special case of map(LongUnaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        amount - the amount to add, may be negative
        Returns:
        a copy of this array with the amount added to each value
      • minus

        public LongArray minus​(long amount)
        Returns an instance with the specified amount subtracted from each value.

        This is used to subtract from the contents of this array, returning a new array.

        This is a special case of map(LongUnaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        amount - the amount to subtract, may be negative
        Returns:
        a copy of this array with the amount subtracted from each value
      • multipliedBy

        public LongArray multipliedBy​(long factor)
        Returns an instance with each value multiplied by the specified factor.

        This is used to multiply the contents of this array, returning a new array.

        This is a special case of map(LongUnaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        factor - the multiplicative factor
        Returns:
        a copy of this array with the each value multiplied by the factor
      • dividedBy

        public LongArray dividedBy​(long divisor)
        Returns an instance with each value divided by the specified divisor.

        This is used to divide the contents of this array, returning a new array.

        This is a special case of map(LongUnaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        divisor - the value by which the array values are divided
        Returns:
        a copy of this array with the each value divided by the divisor
      • map

        public LongArray map​(LongUnaryOperator operator)
        Returns an instance with an operation applied to each value in the array.

        This is used to perform an operation on the contents of this array, returning a new array. The operator only receives the value. For example, the operator could multiply and add each element.

           result = base.map(value -> value * 3 + 4);
         

        This instance is immutable and unaffected by this method.

        Parameters:
        operator - the operator to be applied
        Returns:
        a copy of this array with the operator applied to the original values
      • mapWithIndex

        public LongArray mapWithIndex​(IntLongToLongFunction function)
        Returns an instance with an operation applied to each indexed value in the array.

        This is used to perform an operation on the contents of this array, returning a new array. The function receives both the index and the value. For example, the operator could multiply the value by the index.

           result = base.mapWithIndex((index, value) -> index * value);
         

        This instance is immutable and unaffected by this method.

        Parameters:
        function - the function to be applied
        Returns:
        a copy of this array with the operator applied to the original values
      • plus

        public LongArray plus​(LongArray other)
        Returns an instance where each element is the sum of the matching values in this array and the other array.

        This is used to add two arrays, returning a new array. Element n in the resulting array is equal to element n in this array plus element n in the other array. The arrays must be of the same size.

        This is a special case of combine(LongArray, LongBinaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        other - the other array
        Returns:
        a copy of this array with matching elements added
        Throws:
        IllegalArgumentException - if the arrays have different sizes
      • minus

        public LongArray minus​(LongArray other)
        Returns an instance where each element is equal to the difference between the matching values in this array and the other array.

        This is used to subtract the second array from the first, returning a new array. Element n in the resulting array is equal to element n in this array minus element n in the other array. The arrays must be of the same size.

        This is a special case of combine(LongArray, LongBinaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        other - the other array
        Returns:
        a copy of this array with matching elements subtracted
        Throws:
        IllegalArgumentException - if the arrays have different sizes
      • multipliedBy

        public LongArray multipliedBy​(LongArray other)
        Returns an instance where each element is equal to the product of the matching values in this array and the other array.

        This is used to multiply each value in this array by the corresponding value in the other array, returning a new array.

        Element n in the resulting array is equal to element n in this array multiplied by element n in the other array. The arrays must be of the same size.

        This is a special case of combine(LongArray, LongBinaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        other - the other array
        Returns:
        a copy of this array with matching elements multiplied
        Throws:
        IllegalArgumentException - if the arrays have different sizes
      • dividedBy

        public LongArray dividedBy​(LongArray other)
        Returns an instance where each element is calculated by dividing values in this array by values in the other array.

        This is used to divide each value in this array by the corresponding value in the other array, returning a new array.

        Element n in the resulting array is equal to element n in this array divided by element n in the other array. The arrays must be of the same size.

        This is a special case of combine(LongArray, LongBinaryOperator). This instance is immutable and unaffected by this method.

        Parameters:
        other - the other array
        Returns:
        a copy of this array with matching elements divided
        Throws:
        IllegalArgumentException - if the arrays have different sizes
      • combine

        public LongArray combine​(LongArray other,
                                 LongBinaryOperator operator)
        Returns an instance where each element is formed by some combination of the matching values in this array and the other array.

        This is used to combine two arrays, returning a new array. Element n in the resulting array is equal to the result of the operator when applied to element n in this array and element n in the other array. The arrays must be of the same size.

        This instance is immutable and unaffected by this method.

        Parameters:
        other - the other array
        operator - the operator used to combine each pair of values
        Returns:
        a copy of this array combined with the specified array
        Throws:
        IllegalArgumentException - if the arrays have different sizes
      • combineReduce

        public long combineReduce​(LongArray other,
                                  LongTernaryOperator operator)
        Combines this array and the other array returning a reduced value.

        This is used to combine two arrays, returning a single reduced value. The operator is called once for each element in the arrays. The arrays must be of the same size.

        The first argument to the operator is the running total of the reduction, starting from zero. The second argument to the operator is the element from this array. The third argument to the operator is the element from the other array.

        This instance is immutable and unaffected by this method.

        Parameters:
        other - the other array
        operator - the operator used to combine each pair of values with the current total
        Returns:
        the result of the reduction
        Throws:
        IllegalArgumentException - if the arrays have different sizes
      • concat

        public LongArray concat​(long... arrayToConcat)
        Returns an array that combines this array and the specified array.

        The result will have a length equal to this.size() + arrayToConcat.length.

        This instance is immutable and unaffected by this method.

        Parameters:
        arrayToConcat - the array to add to the end of this array
        Returns:
        a copy of this array with the specified array added at the end
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • concat

        public LongArray concat​(LongArray arrayToConcat)
        Returns an array that combines this array and the specified array.

        The result will have a length equal to this.size() + newArray.length.

        This instance is immutable and unaffected by this method.

        Parameters:
        arrayToConcat - the new array to add to the end of this array
        Returns:
        a copy of this array with the specified array added at the end
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • sorted

        public LongArray sorted()
        Returns a sorted copy of this array.

        This uses Arrays.sort(long[]).

        This instance is immutable and unaffected by this method.

        Returns:
        a sorted copy of this array
      • min

        public long min()
        Returns the minimum value held in the array.

        If the array is empty, then an exception is thrown. If the array contains NaN, then the result is NaN.

        Returns:
        the minimum value
        Throws:
        IllegalStateException - if the array is empty
      • max

        public long max()
        Returns the minimum value held in the array.

        If the array is empty, then an exception is thrown. If the array contains NaN, then the result is NaN.

        Returns:
        the maximum value
        Throws:
        IllegalStateException - if the array is empty
      • sum

        public long sum()
        Returns the sum of all the values in the array.

        This is a special case of reduce(long, LongBinaryOperator).

        Returns:
        the total of all the values
      • reduce

        public long reduce​(long identity,
                           LongBinaryOperator operator)
        Reduces this array returning a single value.

        This is used to reduce the values in this array to a single value. The operator is called once for each element in the arrays. The first argument to the operator is the running total of the reduction, starting from zero. The second argument to the operator is the element.

        This instance is immutable and unaffected by this method.

        Parameters:
        identity - the identity value to start from
        operator - the operator used to combine the value with the current total
        Returns:
        the result of the reduction
      • metaBean

        public org.joda.beans.MetaBean metaBean()
        Specified by:
        metaBean in interface org.joda.beans.Bean
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object