public abstract class Vector extends AbstractList<Number> implements RandomAccess
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:
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].
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:
int[index]
value to a double
value.isUnsigned()
is true
, apply the necessary bitmask before conversion.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.
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.IntegerList
Defined in the sis-utility
module
modCount
Modifier | Constructor and Description |
---|---|
protected |
Vector()
For subclasses constructor.
|
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.
|
add, add, addAll, clear, equals, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, remove, removeRange
addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
addAll, contains, containsAll, isEmpty, remove, removeAll, replaceAll, retainAll, sort, spliterator, toArray, toArray
parallelStream, removeIf, stream
public static Vector create(Object array, boolean isUnsigned) throws IllegalArgumentException
float[]
.Number[]
array.String[]
array (not recommended, but happen with some file formats).Vector
, in which case it is returned unchanged.null
value, in which case null
is returned.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.array
- the object to wrap in a vector, or null
.isUnsigned
- true
if integer types should be interpreted as unsigned integers.null
if the argument was null
.IllegalArgumentException
- if the type of the given object is not recognized by the method.public static Vector createForDecimal(float[] array)
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.
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.array
- the object to wrap in a vector, or null
.null
if the argument was null
.DecimalFunctions.floatToDouble(float)
public static Vector createSequence(Number first, Number increment, int length)
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.
first
- the first value, inclusive.increment
- the difference between the values at two adjacent indexes.length
- the length of the desired vector.public abstract Class<? extends Number> getElementType()
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:
get(int)
may be instances of a type wider than the type used by this vector for storing the values.get(int)
will use double-precision even if this vector
stores the values as single-precision floating point numbers.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
.
CheckedContainer.getElementType()
public boolean isInteger()
true
if this vector contains only integer values.
This method may iterate over all values for performing this verification.true
if this vector contains only integer values.public abstract boolean isUnsigned()
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.
true
if the integer values shall be interpreted as unsigned values.public abstract int size()
size
in interface Collection<Number>
size
in interface List<Number>
size
in class AbstractCollection<Number>
public abstract boolean isNaN(int index)
true
if the value at the given index is null
or NaN
.index
- the index in the [0 … size-1] range.true
if the value at the given index is NaN
.IndexOutOfBoundsException
- if the given index is out of bounds.public abstract double doubleValue(int index)
double
.
This is the safest method since all primitive types supported by Vector
are convertible to the double
type.index
- the index in the [0 … size-1] range.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.doubleValues()
public abstract float floatValue(int index)
float
.
This method may result in a lost of precision if this vector
stores or computes its values with the double
type.index
- the index in the [0 … size-1] range.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.floatValues()
public long longValue(int index)
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.
index
- the index in the [0 … size-1] range.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.public int intValue(int index)
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.
index
- the index in the [0 … size-1] range.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.public short shortValue(int index)
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.
index
- the index in the [0 … size-1] range.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.public byte byteValue(int index)
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.
index
- the index in the [0 … size-1] range.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.public abstract String stringValue(int index)
String.valueOf(get(index))
except if the values are unsigned integers.index
- the index in the [0 … size-1] range.null
).IndexOutOfBoundsException
- if the given index is out of bounds.toString()
public abstract Number get(int index)
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.
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.get
in interface List<Number>
get
in class AbstractList<Number>
index
- the index in the [0 … size-1] range.null
).IndexOutOfBoundsException
- if the given index is out of bounds.NumberFormatException
- if the value is stored as a String
and can not be parsed.public abstract Number set(int index, Number value)
get(int)
.
If not, the stored value may lost precision as a result of the cast.set
in interface List<Number>
set
in class AbstractList<Number>
index
- the index in the [0 … size-1] range.value
- the value to set at the given index.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.public Number increment(double tolerance)
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.tolerance
- the tolerance threshold for verifying if the increment is constant.null
if the increment is not constant.public NumberRange<?> range()
public final Vector subList(int lower, int upper)
lower
inclusive to
upper
exclusive.
subSampling(lower, 1, upper - lower)
.
This method is declared final in order to force subclasses to override subSampling(…)
instead.subList
in interface List<Number>
subList
in class AbstractList<Number>
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.IndexOutOfBoundsException
- if an index is outside the [0 … size-1] range.public Vector subSampling(int first, int step, int length)
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.
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.IndexOutOfBoundsException
- if first
or first + step*(length-1)
is outside the [0 … size-1] range.public Vector pick(int... indices)
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.
indices
- indexes of the values to be returned.IndexOutOfBoundsException
- if at least one index is out of bounds.public Vector concatenate(Vector toAppend)
size
- 1]
range will map to this vector, while indexes in the [size
… size
+ toAppend.size
]
range while map to the given vector.toAppend
- the vector to concatenate at the end of this vector.public final Vector reverse()
subSampling(size-1, -1, size)
.
This method is declared final in order to force subclasses to override subSampling(…)
instead.public Vector compress(double tolerance)
this
if this method can not do better than current Vector
instance.
Examples:
int[]
array while values could be stored as short
values.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).
tolerance
- maximal difference allowed between original and compressed vectors (can be zero).this
.public double[] doubleValues()
The default implementation invokes doubleValue(int)
for all indices from 0 inclusive
to size()
exclusive. Subclasses may override with more efficient implementation.
doubleValue(int)
public float[] floatValues()
The default implementation invokes floatValue(int)
for all indices from 0 inclusive
to size()
exclusive. Subclasses may override with more efficient implementation.
floatValue(int)
public String toString()
toString
in class AbstractCollection<Number>
stringValue(int)
Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.