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.

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

const vector = new Vector(ArrayClass, initialCapacity);

// If you need to pass options such as a custom growth policy
const vector = new Vector(ArrayClass, {
  initialCapacity: 10,
  initialLength: 3,
  policy: (capacity) => Math.ceil(capacity * 2.5)  
});

Subclasses for each of JS typed array also exists as a convenience.

const int8vector    = new Vector.Int8Vector(initialCapacity);
const uint8vector   = new Vector.Uint8Vector(initialCapacity);
const int16vector   = new Vector.Int16Vector(initialCapacity);
const uint16vector  = new Vector.Uint16Vector(initialCapacity);
const int32vector   = new Vector.Int32Vector(initialCapacity);
const uint32vector  = new Vector.Uint32Vector(initialCapacity);
const float32vector = new Vector.Float32Vector(initialCapacity);
const float64vector = 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
const vector = Vector.from([1, 2, 3], Int8Array);

// Providing the desired capacity
const vector = Vector.from([1, 2, 3], Int8Array, 10);

// Subclasses also have a static #.from
const 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).

const 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!
const 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.

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

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

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

const vector = new Vector(Uint8Array, 2);

vector.set(1, 45);

vector.get(1);
>>> 45

#.pop

Removes & returns the last value of the vector.

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

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

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

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

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

const vector = new Vector(Array, 10);

stack.push(1);
stack.push(2);

stack.forEach((item, index, stack) => {
  console.log(index, item);
});

#.values

Returns an iterator over the vector’s values.

const vector = Vector.from([1, 2, 3], Uint8Array);

const iterator = vector.values();

iterator.next().value
>>> 3

#.entries

Returns an iterator over the vector’s entries.

const vector = Vector.from([1, 2, 3], Uint8Array);

const iterator = vector.entries();

iterator.next().value
>>> [0, 3]

Iterable

Alternatively, you can iterate over a vector’s values using ES2015 for...of protocol:

const vector = Vector.from([1, 2, 3], Uint8Array);

for (const item of vector) {
  console.log(item);
}