Class Vector

All Implemented Interfaces:
Iterable<Number>, Collection<Number>, List<Number>, RandomAccess, SequencedCollection<Number>
Direct Known Subclasses:
ArrayVector, ConcatenatedVector, LinearlyDerivedVector, RepeatedVector, SequenceVector, Vector.Pick, Vector.SubSampling

public abstract class Vector extends AbstractList<Number> implements RandomAccess
A vector of real numbers. An instance of Vector can be a wrapper around an array of Java primitive type (typically float[] or double[]), or it may be a function calculating values on the fly. Often the two above-cited cases are used together, for example in a time series where:
  • x[i] is a linear function of i (e.g. the sampling time of measurements performed at a fixed time interval)
  • y[i] is the measurement of a phenomenon at time x[i].

Instantiation

Instances of Vector are usually created by calls to the create(Object, boolean) static method. The supplied array is not cloned – changes to the primitive array are reflected in the vector, and vice-versa. Vectors can be a view over a subsection of the given array, or can provide a view of the elements in reverse order, etc. The example below creates a view over a subsection:

Usage

The methods that are most often used after Vector creation are size() and doubleValue(int) or intValue(int). Those methods make abstraction of the underlying data type. For example if the vector is backed by an array of type int[], then calls to doubleValue(index) will:
  • Convert the int[index] value to a double value.
  • If isUnsigned() is true, apply the necessary bitmask before conversion.
Widening conversions (for example from short to long) are always allowed. Narrowing conversions are allowed if the result can be represented at least approximately by the target type. For example, conversions from double to float are always allowed (values that are too large for the float type are represented by positive of negative infinity), but conversions from long to short are allowed only if the value is between Short.MIN_VALUE and Short.MAX_VALUE inclusive.
Comparison with other API: the above functionalities look like similar functionalities provided by ByteBuffer in standard Java, but they actually serve different purposes. The ByteBuffer getter methods (for example getShort(int), getLong(int), etc.) allow to decode a sequence of bytes in a way determined by the type of the value to decode (2 bytes for a short, 8 bytes for a long, etc.) – the type of the stored value must be known before to read it. By contrast, this Vector class is used in situations where the decoding has already been done by the code that create a Vector object, but the data type may not be known by the code that will use the Vector object. For example, a method performing a numerical calculation may want to see the data as double values without concern about whether the data were really stored as double or as float values. For the situations where a Buffer is needed, inter-operability is provided by the buffer() method and by accepting buffer in the create(Object, boolean) method.
Since:
0.8
Version:
1.1
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private final class 
    A view over another vector at pre-selected indexes.
    private final class 
    A view over another vector in a range of index.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) static final int
    The prime number used in hash code computation.

    Fields inherited from class java.util.AbstractList

    modCount
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    For subclasses constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) Vector
    If this vector is a view over a subset of another vector, returns the backing vector.
    Returns the vector data as a java.nio buffer.
    byte
    byteValue(int index)
    Returns the value at the given index as a byte.
    canNotConvert(int index, Class<?> target)
    Returns the exception to be thrown when the component type in the backing array can not be converted to the requested type through an identity or widening conversion.
    compress(double tolerance)
    Returns a vector with the same data than this vector but encoded in a more compact way, or this if this method cannot do better than current Vector instance.
    concatenate(Vector toAppend)
    Returns the concatenation of this vector with the given one.
    (package private) final Vector
    Returns a copy of this vector.
    static Vector
    create(double[] array)
    Wraps the given array of floating point values.
    static Vector
    create(Object array, boolean isUnsigned)
    Wraps the given object in a vector.
    (package private) Vector
    Implementation of concatenate(Vector) after argument has been validated.
    static Vector
    createForDecimal(float[] array)
    Wraps the given float[] array in a vector that preserve the string representations in base 10.
    (package private) static Vector
    createSequence(Class<? extends Number> type, Number first, Number increment, int length)
    Creates a sequence of the given type.
    static Vector
    createSequence(Number first, Number increment, int length)
    Creates a sequence of numbers in a given range of values using the given increment.
    (package private) Vector
    createSubSampling(int first, int step, int length)
    Implementation of subSampling(int,int,int) to be overridden by subclasses.
    (package private) Vector
    createTransform(double scale, double offset)
    Implementation of createTransform(double, double) after arguments have been validated.
    abstract double
    doubleValue(int index)
    Returns the value at the given index as a double.
    double[]
    Copies all values in an array of double precision floating point numbers.
    (package private) boolean
    equals(int lower, int upper, Vector other, int otherOffset)
    Returns true if this vector in the given range is equal to the specified vector.
    boolean
    equals(Object object)
    Returns true if the given object is a vector containing the same values than this vector.
    void
    fill(int fromIndex, int toIndex, Number value)
    Sets a range of elements to the given number.
    float
    floatValue(int index)
    Returns the value at the given index as a float.
    float[]
    Copies all values in an array of single precision floating point numbers.
    abstract Number
    get(int index)
    Returns the number at the given index, or null if none.
    private int
    Returns an estimation of the number of bits used by each value in this vector.
    abstract Class<? extends Number>
    Returns the type of elements in this vector.
    int
    Returns a hash code for the values in this vector.
    increment(double tolerance)
    Returns the increment between all consecutive values if this increment is constant, or null otherwise.
    (package private) int
    indexOf(int toSearch, int index, boolean equality)
    Returns the index of the first value which is equal (if equality is true) or different (if equality is false) to the value at the toSearch index.
    int
    intValue(int index)
    Returns the value at the given index as an int.
    boolean
    Returns true if this vector is empty or contains only NaN values.
    boolean
    Returns true if this vector contains only integer values.
    abstract boolean
    isNaN(int index)
    Returns true if the value at the given index is null or NaN.
    boolean
    Returns true if values in this vector can be casted to single-precision floating point numbers (float) without precision lost.
    boolean
    Returns true if integer values shall be interpreted as unsigned values.
    long
    longValue(int index)
    Returns the value at the given index as a long.
    pick(int... indices)
    Returns a view which contains the values of this vector at the given indexes.
    Returns the minimal and maximal values found in this vector.
    (package private) NumberRange<?>
    range(IntSupplier indices, int n)
    Computes the range of values at the indices provided by the given supplier.
    repeat(boolean eachValue, int count)
    Returns a vector whose value is the content of this vector repeated count times.
    int[]
    repetitions(int... candidates)
    Detects repetition patterns in the values contained in this vector.
    final Vector
    Returns a view which contains the values of this vector in reverse order.
    abstract Number
    set(int index, Number value)
    Sets the number at the given index.
    short
    shortValue(int index)
    Returns the value at the given index as a short.
    abstract int
    Returns the number of elements in this vector.
    abstract String
    stringValue(int index)
    Returns a string representation of the value at the given index.
    final Vector
    subList(int lower, int upper)
    Returns a view which contain the values of this vector in the given index range.
    subSampling(int first, int step, int length)
    Returns a view which contain the values of this vector in a given index range.
    (package private) final long
    subtract(long a, long b)
    Returns a-b as a signed value, throwing an exception if the result overflows a long.
    (package private) int[]
    toBacking(int[] indices)
    Converts an array of indexes used by this vector to the indexes used by the backing vector.
    Returns a string representation of this vector.
    transform(double scale, double offset)
    Returns a view of this vector with all values transformed by the given linear equation.
    (package private) final void
    Logs a warning about an exception that can be safely ignored.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface java.util.Collection

    parallelStream, removeIf, stream, toArray

    Methods inherited from interface java.lang.Iterable

    forEach
  • Field Details

  • Constructor Details

    • Vector

      protected Vector()
      For subclasses constructor.
  • Method Details

    • create

      public static Vector create(Object array, boolean isUnsigned) throws IllegalArgumentException
      Wraps the given object in a vector. The argument should be one of the following:
      • An array of a primitive type, like float[].
      • A Number[] array.
      • A String[] array (not recommended, but happen with some file formats).
      • A Vector, in which case it is returned unchanged.
      • A Buffer backed by an array.
      • The null value, in which case null is returned.
      The given argument is not cloned. Consequently, changes in the underlying array are reflected in this vector, and vice-versa.

      Unsigned integers

      Java has no primitive support for unsigned integers. But some file formats use unsigned integers, which can be simulated in Java by the use of bit masks or methods like Integer.toUnsignedLong(int). This Vector class applies automatically those masks (unless otherwise noticed in method Javadoc) if the isUnsigned argument is true. That argument applies only to byte[], short[], int[] or long[] arrays and is ignored for all other kind of arrays.
      Parameters:
      array - the object to wrap in a vector, or null.
      isUnsigned - true if integer types should be interpreted as unsigned integers.
      Returns:
      the given object wrapped in a vector, or null if the argument was null.
      Throws:
      IllegalArgumentException - if the type of the given object is not recognized by the method.
    • create

      public static Vector create(double[] array)
      Wraps the given array of floating point values. This method does not clone the array: changes in the given array will be reflected in the returned vector and vice-versa. This method is equivalent to create(array, false) but potentially faster.
      Parameters:
      array - the array of floating point values to wrap in a vector, or null.
      Returns:
      the given array wrapped in a vector, or null if the argument was null.
      Since:
      1.0
    • createForDecimal

      public static Vector createForDecimal(float[] array)
      Wraps the given float[] array in a vector that preserve the string representations in base 10. For example, the 0.1 float value casted to double normally produces 0.10000000149011612 because of the way IEEE 754 arithmetic represents numbers (in base 2 instead of base 10). But the vector returned by this method will convert the 0.1 float value into the 0.1 double value. Note that despite the appearance, this is not more accurate than the normal cast, because base 10 is not more privileged in nature than base 2.

      When to use

      This method can be used when there is good reasons to think that the float numbers were parsed from decimal representations, for example an ASCII file. There is usually no reason to use this method if the values are the result of some numerical computations.
      Parameters:
      array - the array of floating point values to wrap in a vector, or null.
      Returns:
      the given array wrapped in a vector, or null if the argument was null.
      See Also:
    • createSequence

      public static Vector createSequence(Number first, Number increment, int length)
      Creates a sequence of numbers in a given range of values using the given increment. The range of values will be first inclusive to (first + increment*length) exclusive. Note that the value given by the first argument is equivalent to a "lowest" or "minimum" value only if the given increment is positive.

      The element type will be inferred from the type of the given Number instances. If will typically be Integer.class for the [100:1:120] range and Double.class for the [0:0.1:1] range.

      Parameters:
      first - the first value, inclusive.
      increment - the difference between the values at two adjacent indexes.
      length - the length of the desired vector.
      Returns:
      the given sequence as a vector.
    • createSequence

      static Vector createSequence(Class<? extends Number> type, Number first, Number increment, int length)
      Creates a sequence of the given type.
    • getElementType

      public abstract Class<? extends Number> getElementType()
      Returns the type of elements in this vector. If this vector is backed by an array of a primitive type, then this method returns the wrapper class, not the primitive type. For example if this vector is backed by an array of type float[], then this method returns Float.class, not Float.TYPE.

      The information returned by this method is only indicative; it is not guaranteed to specify accurately this kind of objects returned by the get(int) method. There is various situations where the types may not match:

      • If this vector is unsigned, then the values returned by get(int) will be instances of a type wider than the type used by this vector for storing the values.
      • If this vector has been created for decimal numbers, then the values returned by get(int) will use double-precision even if this vector stores the values as single-precision floating point numbers.
      • If this vector has been compressed, then the type returned by this method does not describe accurately the range of values that this vector can store.

      Users of the doubleValue(int) method do not need to care about this information since Vector will perform automatically the type conversion. Users of other methods may want to verify this information for avoiding ArithmeticException.

      Returns:
      the type of elements in this vector.
      See Also:
    • isSinglePrecision

      public boolean isSinglePrecision()
      Returns true if values in this vector can be casted to single-precision floating point numbers (float) without precision lost. In case of doubt, this method conservatively returns false.
      Returns:
      whether values in this vector can be casted to float primitive type.
      Since:
      1.1
      See Also:
    • getBitCount

      private int getBitCount()
      Returns an estimation of the number of bits used by each value in this vector. This is an estimation only and should be used only as a hint.
    • isInteger

      public boolean isInteger()
      Returns true if this vector contains only integer values. This method may iterate over all values for performing this verification.
      Returns:
      true if this vector contains only integer values.
    • isUnsigned

      public boolean isUnsigned()
      Returns true if integer values shall be interpreted as unsigned values. This method may return true for data stored in byte[], short[], int[] or long[] arrays, but never for data stored in float[] and double[] arrays. The default implementation returns false.

      Unless otherwise noticed in Javadoc, users do not need to care about this information since Vector methods will perform automatically the operations needed for unsigned integers.

      Returns:
      true if the integer values shall be interpreted as unsigned values.
    • size

      public abstract int size()
      Returns the number of elements in this vector.
      Specified by:
      size in interface Collection<Number>
      Specified by:
      size in interface List<Number>
      Specified by:
      size in class AbstractCollection<Number>
      Returns:
      the number of elements in this vector.
    • isEmptyOrNaN

      public boolean isEmptyOrNaN()
      Returns true if this vector is empty or contains only NaN values.
      Returns:
      whether this vector is empty or contains only NaN values.
      Since:
      1.1
    • isNaN

      public abstract boolean isNaN(int index)
      Returns true if the value at the given index is null or NaN.
      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      true if the value at the given index is NaN.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
    • doubleValue

      public abstract double doubleValue(int index)
      Returns the value at the given index as a double. This is the safest method since all primitive types supported by Vector are convertible to the double type.
      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NullPointerException - if the value is null (never happen if this vector wraps an array of primitive type).
      NumberFormatException - if the value is stored as a String and cannot be parsed.
      See Also:
    • floatValue

      public float floatValue(int index)
      Returns the value at the given index as a float. This method may result in a lost of precision if this vector stores or computes its values with the double type.

      The default implementation delegates to doubleValue(int) and cast the result to float.

      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NullPointerException - if the value is null (never happen if this vector wraps an array of primitive type).
      NumberFormatException - if the value is stored as a String and cannot be parsed.
      See Also:
    • longValue

      public long longValue(int index)
      Returns the value at the given index as a long. If this vector uses floating point values, the value is rounded to the nearest integer.

      The default implementation delegates to doubleValue(int) and verifies if the result can be rounded to a long with an error not greater than 0.5. Subclasses that store or compute their values with an integer type should override this method.

      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NullPointerException - if the value is null (never happen if this vector wraps an array of primitive type).
      NumberFormatException - if the value is stored as a String and cannot be parsed.
      ArithmeticException - if the value is too large for the capacity of the long type.
    • intValue

      public int intValue(int index)
      Returns the value at the given index as an int. If this vector uses floating point values, the value is rounded to the nearest integer.

      The default implementation delegates to longValue(int) and verifies if the result fits in the int type. Subclasses that store or compute their values with the int, short or byte type should override this method.

      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NullPointerException - if the value is null (never happen if this vector wraps an array of primitive type).
      NumberFormatException - if the value is stored as a String and cannot be parsed.
      ArithmeticException - if the value is too large for the capacity of the int type.
    • shortValue

      public short shortValue(int index)
      Returns the value at the given index as a short. If this vector uses floating point values, the value is rounded to the nearest integer.

      The default implementation delegates to longValue(int) and verifies if the result fits in the short type. Subclasses that store or compute their values with the short or byte type should override this method.

      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NullPointerException - if the value is null (never happen if this vector wraps an array of primitive type).
      NumberFormatException - if the value is stored as a String and cannot be parsed.
      ArithmeticException - if the value is too large for the capacity of the short type.
    • byteValue

      public byte byteValue(int index)
      Returns the value at the given index as a byte. If this vector uses floating point values, the value is rounded to the nearest integer.

      The default implementation delegates to longValue(int) and verifies if the result fits in the byte type. Subclasses that store or compute their values with the byte type should override this method.

      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NullPointerException - if the value is null (never happen if this vector wraps an array of primitive type).
      NumberFormatException - if the value is stored as a String and cannot be parsed.
      ArithmeticException - if the value is too large for the capacity of the byte type.
    • canNotConvert

      private ArithmeticException canNotConvert(int index, Class<?> target)
      Returns the exception to be thrown when the component type in the backing array can not be converted to the requested type through an identity or widening conversion.
    • stringValue

      public abstract String stringValue(int index)
      Returns a string representation of the value at the given index. Invoking this method is generally equivalent to invoking String.valueOf(get(index)) except if the values are unsigned integers.
      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      a string representation of the value at the given index (may be null).
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      See Also:
    • get

      public abstract Number get(int index)
      Returns the number at the given index, or null if none. The object returned by this method is usually an instance of the class returned by getElementType(), but may also be an instance of a wider type if this is necessary for representing the values.
      Example: if getElementType() returns Byte.class but isUnsigned() returns true, then this method will rather return instances of Short because that type is the smallest Java primitive type capable to hold byte values in the [0 … 255] range. But the elements are still stored internally as byte, and the vector cannot accept values outside the [0 … 255] range even if they are valid Short values.
      The class of returned objects should be stable. For example, this method should not use different types for different range of values. This stability is recommended but not guaranteed because Vector can also wrap arbitrary Number[] arrays.
      Specified by:
      get in interface List<Number>
      Specified by:
      get in class AbstractList<Number>
      Parameters:
      index - the index in the [0 … size-1] range.
      Returns:
      the value at the given index (may be null).
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      NumberFormatException - if the value is stored as a String and cannot be parsed.
    • set

      public abstract Number set(int index, Number value)
      Sets the number at the given index. The given number should be an instance of the same type than the number returned by get(int). If not, the stored value may lost precision as a result of the cast.
      Specified by:
      set in interface List<Number>
      Overrides:
      set in class AbstractList<Number>
      Parameters:
      index - the index in the [0 … size-1] range.
      value - the value to set at the given index.
      Returns:
      the value previously stored at the given index.
      Throws:
      UnsupportedOperationException - if this vector is read-only.
      IndexOutOfBoundsException - if the given index is out of bounds.
      NumberFormatException - if the previous value was stored as a String and cannot be parsed.
      IllegalArgumentException - if this vector uses some compression technic and the given value is out of range for that compression.
    • fill

      public void fill(int fromIndex, int toIndex, Number value)
      Sets a range of elements to the given number. Invoking this method is equivalent to invoking set(int, Number) in a loop, but potentially much more efficient.
      Parameters:
      fromIndex - index of the first element (inclusive) to be filled with the specified value.
      toIndex - index of the last element (exclusive) to be filled with the specified value.
      value - the value to be stored in elements of the vector.
      Since:
      1.1
    • indexOf

      int indexOf(int toSearch, int index, boolean equality)
      Returns the index of the first value which is equal (if equality is true) or different (if equality is false) to the value at the toSearch index. Subclasses should override if they can provide a more efficient implementation.
      Parameters:
      toSearch - index of the value to search.
      index - index of the first value where to start the search.
      equality - whether we search the first equal value, or the first different value.
      Returns:
      index of the value found, or the vector size if the value has not been found.
    • repetitions

      public int[] repetitions(int... candidates)
      Detects repetition patterns in the values contained in this vector. The repetitions detected by this method are patterns that at repeated at a regular interval on the whole vector; this method does not search for repetitions occurring at irregular intervals. This method returns an array of typically 0, 1 or 2 elements where zero element means that no repetition has been found, one element describes a repetition (see the example below), and two elements describes a repetition of the repetitions (examples below). More elements (deeper recursivity) are theoretically possible but not yet implemented.

      If the values in this vector are of the form (x, x, …, x, y, y, …, y, z, z, …, z, …), then the first integer in the returned array is the number of consecutive x values before the y values. That number of occurrences must be the same than the number of consecutive y values before the z values, the number of consecutive z values before the next values, and so on until the end of the vector.

      Examples: in the following vector, each value is repeated 3 times. So the array returned by this method would be {4}, meaning that the first number appears 4 times, followed by a new number appearing 4 times, followed by a new number appearing 4 times, and so on until the end of the vector.
      For the next level (the second integer in the returned array), this method represents above repetitions by single entities then reapplies the same repetition detection. This method processes has if the (x, x, …, x, y, y, …, y, z, z, …, z, …) vector was replaced by a new (x, y, z, …) vector, then the same detection algorithm was applied recursively.
      Examples: in the following vector, each value is repeated 2 times, then the sequence of 12 values is itself repeated 2 times. So the array returned by this method would be {3,4}, meaning that the first number appears 3 times, followed by a new number appearing 3 times, etc. until we counted 4 groups of 3 numbers. Then the whole sequence is repeated until the end of the vector.

      This method is useful for analyzing the localization grid provided by some files (for example in netCDF format). Those grids sometimes have constant longitude for the same column index, or constant latitude for the same row index. This method can detect such regularity, which allows more efficient handling of the grid to CRS transform.

      Parameters:
      candidates - probable values, or null or an empty array if unknown. If non-empty, those values will be used for narrowing the search, which may improve performances. There is no guarantee that the values returned by this method will be among the given candidates.
      Returns:
      the number of times that entities (numbers, or group of numbers) appears consecutively with identical values. If no such repetition is found, an empty array.
      Since:
      1.0
      See Also:
    • subtract

      final long subtract(long a, long b)
      Returns a-b as a signed value, throwing an exception if the result overflows a long. The given values will be interpreted as unsigned values if this vector is unsigned.
      Parameters:
      a - the first value, unsigned if isUnsigned() return true.
      b - the value to subtract from a, unsigned if isUnsigned() return true.
      Returns:
      the difference, always signed.
      Throws:
      ArithmeticException - if the difference is too large.
      See Also:
    • increment

      public Number increment(double tolerance)
      Returns the increment between all consecutive values if this increment is constant, or null otherwise. If the returned value is non-null, then the following condition shall hold for all values of i in the [0 … size() - 1] range:
      abs(doubleValue(i) - (doubleValue(0) + increment*i)) ≤ tolerance
      The tolerance threshold can be zero if exact matches are desired. The return value (if non-null) is always a signed value, even if this vector is unsigned.
      Parameters:
      tolerance - the tolerance threshold for verifying if the increment is constant.
      Returns:
      the increment as a signed value, or null if the increment is not constant.
    • range

      public NumberRange<?> range()
      Returns the minimal and maximal values found in this vector.
      Returns:
      minimal and maximal values found in this vector.
    • range

      NumberRange<?> range(IntSupplier indices, int n)
      Computes the range of values at the indices provided by the given supplier. The default implementation iterates over all double values, but subclasses should override with a more efficient implementation if possible.
      Parameters:
      indices - supplier of indices of the values to examine for computing the range, or null for the 0, 1, 2, … n-1 sequence.
      n - number of indices to get from the supplier.
      Returns:
      the range of all values at the given indices.
    • subList

      public final Vector subList(int lower, int upper)
      Returns a view which contain the values of this vector in the given index range. The returned view will contain the values from index lower inclusive to upper exclusive.
      Implementation note: this method delegates its work subSampling(lower, 1, upper - lower). This method is declared final in order to force subclasses to override subSampling(…) instead.
      Specified by:
      subList in interface List<Number>
      Overrides:
      subList in class AbstractList<Number>
      Parameters:
      lower - index of the first value to be included in the returned view.
      upper - index after the last value to be included in the returned view.
      Returns:
      a view of this vector containing values in the given index range.
      Throws:
      IndexOutOfBoundsException - if an index is outside the [0 … size-1] range.
    • subSampling

      public Vector subSampling(int first, int step, int length)
      Returns a view which contain the values of this vector in a given index range. The returned view will contain the values from index first inclusive to (first + step*length) exclusive with index incremented by the given step value, which can be negative. More specifically the index i in the returned vector will maps the element at index (first + step*i) in this vector.

      This method does not copy the values. Consequently, any modification to the values of this vector will be reflected in the returned view and vice-versa.

      Parameters:
      first - index of the first value in this vector to be included in the returned view.
      step - the index increment between values in this vector to be included in the returned view. Can be positive, zero or negative.
      length - the length of the view to be returned. Cannot be greater than the length of this vector, except if the step is zero.
      Returns:
      a view of this vector containing values in the given index range.
      Throws:
      IndexOutOfBoundsException - if first or first + step*(length-1) is outside the [0 … size-1] range.
    • createSubSampling

      Vector createSubSampling(int first, int step, int length)
      Implementation of subSampling(int,int,int) to be overridden by subclasses. Argument validity must have been verified by the caller.
    • backingVector

      Vector backingVector()
      If this vector is a view over a subset of another vector, returns the backing vector. Otherwise returns this. If this method is overridden, it should be together with the toBacking(int[]) method. This method shall not be overridden when the view transform the values.
    • toBacking

      int[] toBacking(int[] indices)
      Converts an array of indexes used by this vector to the indexes used by the backing vector. If there is no such backing vector, then returns a clone of the given array. This method must also check index validity.

      Only subclasses that are views over a subset of this vector will override this method.

      Parameters:
      indices - the indexes given by the user.
      Returns:
      the indexes to use. Must be a new array in order to protect it from user changes.
      Throws:
      IndexOutOfBoundsException - if at least one index is out of bounds.
    • pick

      public Vector pick(int... indices)
      Returns a view which contains the values of this vector at the given indexes. This method does not copy the values, consequently any modification to the values of this vector will be reflected in the returned view and vice-versa.

      The indexes do not need to be in any particular order. The same index can be repeated more than once. Thus it is possible to create a vector larger than the original vector.

      Parameters:
      indices - indexes of the values to be returned.
      Returns:
      a view of this vector containing values at the given indexes.
      Throws:
      IndexOutOfBoundsException - if at least one index is out of bounds.
    • concatenate

      public Vector concatenate(Vector toAppend)
      Returns the concatenation of this vector with the given one. Indexes in the [0 … size - 1] range will map to this vector, while indexes in the [sizesize + toAppend.size] range while map to the given vector.
      Parameters:
      toAppend - the vector to concatenate at the end of this vector.
      Returns:
      the concatenation of this vector with the given vector.
    • createConcatenate

      Vector createConcatenate(Vector toAppend)
      Implementation of concatenate(Vector) after argument has been validated. Provides a more convenient (but non-essential) overriding point for subclasses.
    • repeat

      public Vector repeat(boolean eachValue, int count)
      Returns a vector whose value is the content of this vector repeated count times. The content can be repeated in two different ways:
      • If eachValue is true, then each value is repeated count times before to move to the next value.
      • If eachValue is false, then whole vector is repeated count times.
      Example: if vec contains {1, 2, 3}, then:
      • vec.repeat(true, 4) returns {1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3}.
      • vec.repeat(false, 4) returns {1, 2, 3, 1, 2, 3, 1, 2, 3, 1, 2, 3}.
      This method returns an empty vector if count is zero and returns this if count is one. For other positive count values, this method returns an unmodifiable view of this vector: changes in this vector are reflected in the repeated vector.
      Parameters:
      eachValue - whether to apply the repetition on each value (true) or on the whole vector (false).
      count - number of repetitions as a positive number (including zero).
      Returns:
      this vector repeated count time.
      Since:
      1.0
      See Also:
    • reverse

      public final Vector reverse()
      Returns a view which contains the values of this vector in reverse order.
      Implementation note: this method delegates its work to subSampling(size-1, -1, size). This method is declared final in order to force subclasses to override subSampling(…) instead.
      Returns:
      the vector values in reverse order.
    • transform

      public Vector transform(double scale, double offset)
      Returns a view of this vector with all values transformed by the given linear equation. If scale = 1 and offset = 0, then this method returns this. Otherwise this method returns a vector where each value at index i is computed by doubleValue(i) × scale + offset. The values are computed on-the-fly; they are not copied.
      Parameters:
      scale - the scale factor to apply on each value, or 1 if none.
      offset - the offset to apply on each value, or 0 if none.
      Returns:
      a vector with values computed by doubleValue(i) × scale + offset.
      Throws:
      IllegalArgumentException - if an argument is NaN or infinite.
      Since:
      1.0
    • createTransform

      Vector createTransform(double scale, double offset)
      Implementation of createTransform(double, double) after arguments have been validated. Provides a more convenient (but non-essential) overriding point for subclasses.
    • compress

      public Vector compress(double tolerance)
      Returns a vector with the same data than this vector but encoded in a more compact way, or this if this method cannot do better than current Vector instance. Examples:
      • Vector is backed by an int[] array while values could be stored as short values.
      • Vector contains increasing or decreasing values with a constant delta between consecutive values.
      The returned vector may or may not be backed by the array given to the create(Object, boolean) method. Since the returned array may be a copy of this array, caller should not retain reference to this or reference to the backing array after this method call (otherwise an unnecessary duplication of data may exist in memory).

      When to use

      It is usually not worth to compress small arrays. Performance-critical arrays may not be compressed neither. This method is best suited for vectors that may potentially be large and for which the cost of fetching values in that vector is small compared to the calculation performed with the values.
      Parameters:
      tolerance - maximal difference allowed between original and compressed vectors (can be zero).
      Returns:
      a more compact vector with the same data than this vector, or this.
    • warning

      final void warning(String method, RuntimeException e)
      Logs a warning about an exception that can be safely ignored.
    • buffer

      public Optional<Buffer> buffer()
      Returns the vector data as a java.nio buffer. Data are not copied: changes in the buffer are reflected on this vector and vice-versa. Date are provided in their "raw" form. For example, unsigned integers are given as plain int elements and it is caller responsibility to use Integer.toUnsignedLong(int) if needed.
      Returns:
      the vector data as a buffer. Absent if this vector is not backed by an array or a buffer.
      Since:
      1.0
    • doubleValues

      public double[] doubleValues()
      Copies all values in an array of double precision floating point numbers. This method is for inter-operability with APIs requiring an array of primitive type.

      The default implementation invokes doubleValue(int) for all indices from 0 inclusive to size() exclusive. Subclasses may override with more efficient implementation.

      Returns:
      a copy of all floating point values in this vector.
      See Also:
    • floatValues

      public float[] floatValues()
      Copies all values in an array of single precision floating point numbers. This method is for inter-operability with APIs requiring an array of primitive type.

      The default implementation invokes floatValue(int) for all indices from 0 inclusive to size() exclusive. Subclasses may override with more efficient implementation.

      Returns:
      a copy of all floating point values in this vector.
      See Also:
    • copy

      final Vector copy()
      Returns a copy of this vector. The returned vector is writable, and changes in that vector has no effect on this original vector. The copy is not a clone since it may not be an instance of the same class.
      Returns:
      a copy of this vector.
    • toString

      public String toString()
      Returns a string representation of this vector.
      Overrides:
      toString in class AbstractCollection<Number>
      Returns:
      a string representation of this vector.
      See Also:
    • hashCode

      public int hashCode()
      Returns a hash code for the values in this vector. The hash code is computed as if this vector was converted to an array of Numbers, then the Arrays.hashCode(Object[]) method invoked for that array. This contract is defined for compatibility with List.hashCode() contract.
      Specified by:
      hashCode in interface Collection<Number>
      Specified by:
      hashCode in interface List<Number>
      Overrides:
      hashCode in class AbstractList<Number>
      Returns:
      a hash code value for the values in this vector.
      Since:
      1.0
    • equals

      public boolean equals(Object object)
      Returns true if the given object is a vector containing the same values than this vector. This method performs the comparison as if the two vectors where converted to arrays of Numbers, then the Arrays.equals(Object[], Object[]) method invoked for those arrays.
      Specified by:
      equals in interface Collection<Number>
      Specified by:
      equals in interface List<Number>
      Overrides:
      equals in class AbstractList<Number>
      Parameters:
      object - the other object to compare with this vector.
      Returns:
      true if the given object is a vector containing the same values than this vector.
      Since:
      1.0
    • equals

      boolean equals(int lower, int upper, Vector other, int otherOffset)
      Returns true if this vector in the given range is equal to the specified vector. NaN values are considered equal to all other NaN values, and -0.0 is different than +0.0.
      Parameters:
      lower - index of the first value to compare in this vector, inclusive.
      upper - index after the last value to compare in this vector.
      other - the other vector to compare values with this vector. May be this.
      otherOffset - index of the first element to compare in the other vector.
      Returns:
      whether values over the specified range of the two vectors are equal.