Mnemonist
Vector
The Vector
is an abstract class representing a dynamic JavaScript typed array, such as the Int32Array
.
As such, contrary to the normal byte array, the Vector
is able to grow dynamically if required (typically at a 1.5 rate).
It is a very useful structure when you don’t know the size of your typed array beforehand and is quite memory-efficient (typed arrays are really lean compared to an Array
and you’ll be able to store billions of entries while such an Array
would crash your engine).
Also, dynamic arrays are faster than JavaScript’s Array
(else, all this would be pointless, no?).
Just keep in mind that even if a Int8Vector
really is faster, a Float64Vector
won’t give you an edge because this is often how an Array
containing number would be optimized under the hood by most JavaScript engines.
var Vector = require('mnemonist/vector');
Constructor
The Vector
takes a typed array class as first argument and an initial capacity or alternatively more complex options as second argument.
var vector = new Vector(ArrayClass, initialCapacity);
// If you need to pass options such as a custom growth policy
var vector = new Vector(ArrayClass, {
initialCapacity: 10,
initialLength: 3,
policy: function(capacity) {
return Math.ceil(capacity * 2.5);
}
});
// Subclasses for each of JS typed array also exists as a convenience
var vector = new Vector.Int8Vector(initialCapacity);
var vector = new Vector.Uint8Vector(initialCapacity);
var vector = new Vector.Uint8Vector(initialCapacity);
var vector = new Vector.Int16Vector(initialCapacity);
var vector = new Vector.Uint16Vector(initialCapacity);
var vector = new Vector.Int32Vector(initialCapacity);
var vector = new Vector.Uint32Vector(initialCapacity);
var vector = new Vector.Float32Vector(initialCapacity);
var vector = new Vector.Float64Vector(initialCapacity);
Static #.from
Alternatively, one can build a Vector
from an arbitrary JavaScript iterable likewise:
// Attempting the guess the given iterable's length/size
var vector = Vector.from([1, 2, 3], Int8Array);
// Providing the desired capacity
var vector = Vector.from([1, 2, 3], Int8Array, 10);
// Subclasses also have a static #.from
var vector = Vector.Uint16Vector.from([1, 2, 3]);
Members
Methods
Mutation
Read
Iteration
#.array
The underlying typed array, if you need it for any reason (probably performance, in some precise use cases).
var vector = new Vector(Uint8Array, 4);
vector.push(1);
vector.push(2);
vector.array
>>> [1, 2, 0, 0]
// BEWARE: don't keep a reference of this array
// it can be swapped by the implementation when growing!
var underlyingArray = vector.array;
// ^ this could result in unexpected behaviors
// if you expand the array later on
// Example:
vector.push(3);
vector.push(4);
vector.push(5);
underlyingArray;
>>> [1, 2, 3, 4]
vector.array
>>> [1, 2, 3, 4, 5, 0] // The underlying array has grown!
#.capacity
Real length of the underlying array, i.e. the maximum number of items the array can hold before needing to resize. Not to be confused with #.length.
var vector = new Vector(Uint8Array, 10);
vector.push(1);
vector.push(2);
vector.capacity
>>> 10
#.length
Current length of the vector, that is to say the last set index plus one.
var vector = new Vector(Uint8Array, 10);
vector.push(1);
vector.push(2);
vector.length
>>> 2
#.grow
Applies the growing policy once and reallocates the underlying array.
If given a number, will run the growing policy until we attain a suitable capacity.
var vector = new Vector(Uint8Array, 3);
vector.grow();
// Grow until we can store at least 100 items:
vector.grow(100);
#.set
Sets the value at the given index.
var vector = new Vector(Uint8Array, 2);
vector.set(1, 45);
vector.get(1);
>>> 45
#.pop
Removes & returns the last value of the vector.
var vector = new Vector(Uint8Array, 2);
vector.push(1);
vector.push(2);
vector.push(3);
vector.pop();
>>> 3
vector.length
>>> 2
#.push
Pushes a new value in the vector.
var vector = new Vector(Uint8Array, 2);
vector.push(1);
vector.push(2);
vector.push(3);
vector.push(4);
vector.length
>>> 4
vector.get(1);
>>> 2
#.reallocate
Reallocates the underlying array and truncates length if needed.
var vector = new Vector(Uint8Array, 3);
vector.reallocate(10);
vector.set(7, 3);
// This will truncate length
vector.reallocate(5);
#.resize
Resize the vector’s length. Will reallocate if current capacity is insufficient.
Note that it won’t deallocate if the given length is inferior to the current one. You can use #.reallocate for that.
var vector = new Vector(Uint8Array, {initialLength: 10});
vector.resize(5);
vector.length;
>>> 5
vector.capacity;
>>> 10
// This will reallocate
vector.resize(25);
vector.length;
>>> 25
vector.capacity;
>>> 25
#.get
Retrieves the value stored at the given index.
var vector = new Vector(Uint8Array, 2);
vector.push(1);
vector.push(2);
vector.push(3);
vector.push(4);
vector.get(1);
>>> 2
#.forEach
Iterates over the vector’s items.
var vector = new Vector(Array, 10);
stack.push(1);
stack.push(2);
stack.forEach(function(item, index, stack) {
console.log(index, item);
});
#.values
Returns an iterator over the vector’s values.
var vector = Vector.from([1, 2, 3], Uint8Array);
var iterator = vector.values();
iterator.next().value
>>> 3
#.entries
Returns an iterator over the vector’s entries.
var vector = Vector.from([1, 2, 3], Uint8Array);
var iterator = vector.entries();
iterator.next().value
>>> [0, 3]
Iterable
Alternatively, you can iterate over a vector’s values using ES2015 for...of
protocol:
var vector = Vector.from([1, 2, 3], Uint8Array);
for (var item of vector) {
console.log(item);
}