org.apache.sis.math

## Class Vector

- Object
- - AbstractCollection<E>
  - - AbstractList<Number>
    - - Vector

- All Implemented Interfaces:
    Iterable<Number>, Collection<Number>, List<Number>, RandomAccess

      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 vis-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:

      float[] array = new float[100];
      Vector v = Vector.create(array, false).subList(20, 40)
      // At this point, v.doubleValue(0) is equivalent to (double) array[20].

  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 approximatively 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.
  Since:
    0.8
  See Also:
    `IntegerList`

  Defined in the `sis-utility` module

- - ### Field Summary

    - ### Fields inherited from class AbstractList

      `modCount`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Vector()` For subclasses constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte` | `byteValue(int index)` Returns the value at the given index as a `byte`.
    `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 can not do better than current `Vector` instance.
    `Vector` | `concatenate(Vector toAppend)` Returns the concatenation of this vector with the given one.
    `static Vector` | `create(Object array, boolean isUnsigned)` Wraps the given object in a vector.
    `static Vector` | `createForDecimal(float[] array)` Wraps the given `float[]` array in a vector that preserve the string representations in base 10.
    `static Vector` | `createSequence(Number first, Number increment, int length)` Creates a sequence of numbers in a given range of values using the given increment.
    `abstract double` | `doubleValue(int index)` Returns the value at the given index as a `double`.
    `double[]` | `doubleValues()` Copies all values in an array of double precision floating point numbers.
    `abstract float` | `floatValue(int index)` Returns the value at the given index as a `float`.
    `float[]` | `floatValues()` 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.
    `abstract Class<? extends Number>` | `getElementType()` Returns the type of elements in this vector.
    `Number` | `increment(double tolerance)` Returns the increment between all consecutive values if this increment is constant, or `null` otherwise.
    `int` | `intValue(int index)` Returns the value at the given index as an `int`.
    `boolean` | `isInteger()` 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`.
    `abstract boolean` | `isUnsigned()` 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`.
    `Vector` | `pick(int... indices)` Returns a view which contains the values of this vector at the given indexes.
    `NumberRange<?>` | `range()` Returns the minimal and maximal values found in this vector.
    `Vector` | `reverse()` 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` | `size()` Returns the number of elements in this vector.
    `abstract String` | `stringValue(int index)` Returns a string representation of the value at the given index.
    `Vector` | `subList(int lower, int upper)` Returns a view which contain the values of this vector in the given index range.
    `Vector` | `subSampling(int first, int step, int length)` Returns a view which contain the values of this vector in a given index range.
    `String` | `toString()` Returns a string representation of this vector.

    - ### Methods inherited from class AbstractList

      `add, add, addAll, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, remove, removeRange`

    - ### Methods inherited from class AbstractCollection

      `addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray`

    - ### Methods inherited from class Object

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

    - ### Methods inherited from interface List

      `addAll, contains, containsAll, isEmpty, remove, removeAll, replaceAll, retainAll, sort, spliterator, toArray, toArray`

    - ### Methods inherited from interface Collection

      `parallelStream, removeIf, stream`

    - ### Methods inherited from interface Iterable

      `forEach`

- - ### Constructor Detail

    - #### Vector

          protected Vector()

      For subclasses constructor.

  - ### Method Detail

    - #### 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.
      - 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 vis-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.

    - #### 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 than 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 object to wrap in a vector, or `null`.
      Returns:
        the given array wrapped in a vector, or `null` if the argument was `null`.
      See Also:
        `DecimalFunctions​.floatToDouble(float)`

    - #### 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.

    - #### 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 situation where the types may not match:

      - If this vector is unsigned, then the values returned by `get(int)` may 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:
        `CheckedContainer​.getElementType()`

    - #### 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 abstract 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.

      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.

    - #### 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 can not be parsed.
      See Also:
        `doubleValues()`

    - #### floatValue

          public abstract 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.
      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 can not be parsed.
      See Also:
        `floatValues()`

    - #### 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 can not 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 can not 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 can not 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 can not be parsed.
        `ArithmeticException` - if the value is too large for the capacity of the `byte` type.

    - #### 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:
        `toString()`

    - #### 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 may return instances of `Short` since that type is the smallest Java primitive type capable to hold byte values in the [128 … 255] range.
      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 can not 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 can not be parsed.
        `IllegalArgumentException` - if this vector uses some compression technic and the given value is out of range for that compression.

    - #### 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.

    - #### 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 vis-versa.

      Parameters:
        `first` - index of the first value to be included in the returned view.
        `step` - the index increment in this vector between two consecutive values in the returned vector. Can be positive, zero or negative.
        `length` - the length of the vector to be returned. Can not 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.

    - #### 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 vis-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 [`size` … `size` + `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.

    - #### 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.

    - #### 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 can not 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`.

    - #### 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:
        `doubleValue(int)`

    - #### 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:
        `floatValue(int)`

    - #### 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:
        `stringValue(int)`

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.