dynamic-typedarray

Introduction

This module wraps typed arrays with a minimal abstraction so that you can resize and append to them without reallocating and transferring data yourself.

Example

When initializing, you may pass an Array, a typed array, a size, or a dtype string. (Adding a dtype string will cast the data if necessary.) The following are equivalent ways to initialize a double precision dynamic typed array.

var DynamicTypedarray = require('dynamic-typedarray');

var arr;
arr = new DynamicTypedarray(3);
arr = new DynamicTypedarray(3, 'float64');
arr = new DynamicTypedarray([0, 0, 0]);
arr = new DynamicTypedarray(new Float64Array(3));
arr = new DynamicTypedarray(new Float64Array(3), 'float64');
arr = new DynamicTypedarray(new Uint32Array(3), 'float64');

arr.view
// => Float64Array([0, 0, 0])

arr.buffer
// => Float64Array([0, 0, 0, 0])

arr.length
// => 3

You may push elements:

var arr = new DynamicTypedarrary([1, 2, 3]);
arr.push(4, 5, 6);

arr.view
// => Float64Array([1, 2, 3, 4, 5, 6])

arr.buffer
// => Float64Array([1, 2, 3, 4, 5, 6, 0, 0])

arr.length
// => 6

You can set the length directly in order to allocate space or truncate.

var arr = new DynamicTypedarrary([1, 2, 3]);
arr.length = 100;

arr.view.length
// => 100

arr.buffer.length
// => 128

If I were really trying to use this module and minimize overhead to append to a typed array, I'd do this:

// Instantiate from some data source
var array = new DynamicTypedArray(Int32Array([...]));
var initialLength = array.length;

// Make space for fifty extra entries
array.length += 50;

// Query the view once
var arrayView = array.view;

// Set the next fifty entries directly
for (var i = 0, pointer = initialLength; i < 50; i++, pointer++) {
  arrayView[pointer] = myFunction(i);
}

API

Constructor

require('dynamic-typedarray')([dataOrLength[, dtype]])

Constructor for a new dynamic typed array instance. dataOrLength may either be an Array or typed array of data or an whole number length. If provided, dtype is a string indicating the data type. The list of available dtype strings may be found here.

Properties

.length

Readable and writable. If it exceeds the current buffer length, will allocate storage according to the next power of two.

.view

Read-only. Creates and caches a subarray of the buffer matching the current length of the dynamic array. The subarray will be cached and recreated as needed so that you must not retain this reference if the typed array length may have changed.

Methods

.push(value[, value1[, value2[, ...]]])

Push one or multiple values and return the resulting length of the array. Roughly equivalent to Array.prototype.push.

.pushArray(array)

Push a typed array. and return the resulting length. Similar to Array.prototype.concat, but mutates the current array and does not allocate a new array.

.ensureCapacity(length)

Ensure the buffer has enough space for the requested length. Can be used in advance before appending a known number of values so that you don't need to check the length (or use a method like .push that implicitly checks the length) on each addition.

See also

• allocated-dynamic-typedarray: Lovely, but it's not for me: "Notice how the order of the items is not guaranteed after a .remove(). ... If you need functionality otherwise, try a different module."
• dynamic-typed-array: A very nice module, but adds a bit too much, uses typescript, and doesn't quite satisfy my aims.

License

© 2018 Ricky Reusser.