Constructor

Create a multidimensional array constructor.

Usage

var ctor = require( '@stdlib/ndarray/ctor' );

ctor( dtype, ndims[, options] )

Returns a multidimensional array constructor customized according to an underlying data type dtype and the number of array dimensions ndims.

var ndarray = ctor( 'float64', 3 );
// returns <Function>

The function accepts the following options:

• codegen: boolean indicating whether to use code generation. Default: true.
• mode: specifies how to handle indices which exceed array dimensions. Default: 'throw'.
• submode: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions. If provided fewer modes than dimensions, the function recycles modes using modulo arithmetic. Default: [ options.mode ].

The function supports the following modes:

• throw: specifies that an ndarray instance should throw an error when an index exceeds array dimensions.
• wrap: specifies that an ndarray instance should wrap around an index exceeding array dimensions using modulo arithmetic.
• clamp: specifies that an ndarray instance should set an index exceeding array dimensions to either 0 (minimum index) or the maximum index.

By default, the function uses code generation for fast element lookup. To disable code generation, set the codegen option to false.

var opts = {
    'codegen': false
};

var ndarray = ctor( 'float64', 3, opts );
// returns <Function>

By default, an ndarray instance throws when provided an index which exceeds array dimensions. To support alternative indexing behavior, set the mode option, which will affect all public methods for getting and setting array elements.

var opts = {
    'mode': 'clamp'
};

var ndarray = ctor( 'generic', 2, opts );
// returns <Function>

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );
// returns <ndarray>

// Attempt to access an out-of-bounds linear index (clamped):
var v = arr.iget( 10 );
// returns 4.0

By default, the mode option is applied to subscripts which exceed array dimensions. To specify behavior for each dimension, set the submode option.

var opts = {
    'submode': [ 'wrap', 'clamp' ]
};

var ndarray = ctor( 'generic', 3, opts );
// returns <Function>

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
var shape = [ 2, 2, 2 ];
var order = 'row-major';
var strides = [ 4, 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );
// returns <ndarray>

// Attempt to access out-of-bounds subscripts:
var v = arr.get( -2, 10, -1 ); // linear index: 3
// returns 4.0

ndarray( buffer, shape, strides, offset, order )

Returns an ndarray instance.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );
// returns <ndarray>

The constructor expects the following arguments:

• buffer: data buffer.
• shape: array shape (dimensions).
• strides: array strides which are index offsets specifying how to access along corresponding dimensions.
• offset: index offset specifying the location of the first indexed element in the data buffer.
• order: array order, which is either row-major (C-style) or column-major (Fortran-style).

---

Properties

ndarray.BYTES_PER_ELEMENT

Static property returning the size (in bytes) of each array element (if known).

var ndarray = ctor( 'float64', 2 );
var nbytes = ndarray.BYTES_PER_ELEMENT;
// returns 8

ndarray = ctor( 'generic', 2 );
nbytes = ndarray.BYTES_PER_ELEMENT;
// returns null

ndarray.dtype

Static property returning the underlying data type.

var ndarray = ctor( 'float64', 2 );
var dtype = ndarray.dtype;
// returns 'float64'

ndarray = ctor( 'generic', 2 );
dtype = ndarray.dtype;
// returns 'generic'

ndarray.ndims

Static property returning the number of dimensions.

var ndarray = ctor( 'float64', 2 );
var ndims = ndarray.ndims;
// returns 2

ndarray.prototype.byteLength

Size (in bytes) of the array (if known).

var Float64Array = require( '@stdlib/array/float64' );

// Create a constructor for generating 2-dimensional ndarrays containing double-precision floating-point numbers:
var ndarray = ctor( 'float64', 2 );

// Specify the array configuration:
var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] );
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the byte length:
var nbytes = arr.byteLength;
// returns 32

If unable to determine the size of the array, the property value is null.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the byte length:
var nbytes = arr.byteLength;
// returns null

ndarray.prototype.BYTES_PER_ELEMENT

Size (in bytes) of each array element (if known).

var Float32Array = require( '@stdlib/array/float32' );

// Create a constructor for generating 2-dimensional ndarrays containing single-precision floating-point numbers:
var ndarray = ctor( 'float32', 2 );

// Specify the array configuration:
var buffer = new Float32Array( [ 1.0, 2.0, 3.0, 4.0 ] );
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the number of bytes per element:
var nbytes = arr.BYTES_PER_ELEMENT;
// returns 4

If size of each array element is unknown, the property value is null.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the number of bytes per element:
var nbytes = arr.BYTES_PER_ELEMENT;
// returns null

ndarray.prototype.data

A reference to the underlying data buffer.

var Int8Array = require( '@stdlib/array/int8' );

// Create a constructor for generating 2-dimensional ndarrays containing signed 8-bit integers:
var ndarray = ctor( 'int8', 2 );

// Specify the array configuration:
var buffer = new Int8Array( [ 1, 2, 3, 4 ] );
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the buffer reference:
var d = arr.data;
// returns <Int8Array>[ 1, 2, 3, 4 ]

var bool = ( d === buffer );
// returns true

ndarray.prototype.dtype

Underlying data type.

var Uint8Array = require( '@stdlib/array/uint8' );

// Create a constructor for generating 2-dimensional ndarrays containing unsigned 8-bit integers:
var ndarray = ctor( 'uint8', 2 );

// Specify the array configuration:
var buffer = new Uint8Array( [ 1, 2, 3, 4 ] );
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ -2, 1 ];
var offset = 2;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the underlying data type:
var dtype = arr.dtype;
// returns 'uint8'

ndarray.prototype.flags

Information regarding the memory layout of the array. The returned object has the following properties:

• ROW_MAJOR_CONTIGUOUS: boolean indicating if an array is row-major contiguous.
• COLUMN_MAJOR_CONTIGUOUS: boolean indicating if an array is column-major contiguous.

An array is contiguous if (1) an array is compatible with being stored in a single memory segment and (2) each array element is adjacent to the next array element. Note that an array can be both row-major contiguous and column-major contiguous at the same time (e.g., if an array is a 1-dimensional ndarray with strides = [1]).

var Int32Array = require( '@stdlib/array/int32' );

// Create a constructor for generating 2-dimensional ndarrays containing signed 32-bit integers:
var ndarray = ctor( 'int32', 2 );

// Specify the array configuration:
var buffer = new Int32Array( [ 1, 2, 3, 4 ] );
var shape = [ 2, 2 ];
var order = 'column-major';
var strides = [ 1, 2 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the array flags:
var flg = arr.flags;
// returns {...}

ndarray.prototype.length

Number of array elements.

var Uint16Array = require( '@stdlib/array/uint16' );

// Create a constructor for generating 2-dimensional ndarrays containing unsigned 16-bit integers:
var ndarray = ctor( 'uint16', 2 );

// Specify the array configuration:
var buffer = new Uint16Array( [ 1, 2, 3, 4 ] );
var shape = [ 2, 2 ];
var order = 'column-major';
var strides = [ -1, -2 ];
var offset = 3;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the array length:
var len = arr.length;
// returns 4

ndarray.prototype.ndims

Number of dimensions.

var Uint8ClampedArray = require( '@stdlib/array/uint8c' );

// Create a constructor for generating 2-dimensional ndarrays containing clamped unsigned 8-bit integers:
var ndarray = ctor( 'uint8c', 2 );

// Specify the array configuration:
var buffer = new Uint8ClampedArray( [ 1, 2, 3, 4 ] );
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ -2, -1 ];
var offset = 3;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the number of dimensions:
var ndims = arr.ndims;
// returns 2

ndarray.prototype.offset

Index offset which specifies the buffer index at which to start iterating over array elements.

var Int16Array = require( '@stdlib/array/int16' );

// Create a constructor for generating 2-dimensional ndarrays containing signed 16-bit integers:
var ndarray = ctor( 'int16', 2 );

// Specify the array configuration:
var buffer = new Int16Array( [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 ] );
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ -2, -1 ];
var offset = 10;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the index offset:
var o = arr.offset;
// returns 10

ndarray.prototype.order

Array order. The array order is either row-major (C-style) or column-major (Fortran-style).

var Uint32Array = require( '@stdlib/array/uint32' );

// Create a constructor for generating 2-dimensional ndarrays containing unsigned 32-bit integers:
var ndarray = ctor( 'uint32', 2 );

// Specify the array configuration:
var buffer = new Uint32Array( [ 1, 2, 3, 4 ] );
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the array order:
var ord = arr.order;
// returns 'row-major'

ndarray.prototype.shape

Returns a copy of the array shape.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 2;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the array shape:
var dims = arr.shape;
// returns [ 2, 2 ]

ndarray.prototype.strides

Returns a copy of the array strides which specify how to access data along corresponding array dimensions.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
var shape = [ 2, 2 ];
var order = 'column-major';
var strides = [ -1, 2 ];
var offset = 1;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the array strides:
var s = arr.strides;
// returns [ -1, 2 ]

---

Methods

ndarray.prototype.get( i, j, k, ... )

Returns an array element specified according to provided subscripts. The number of provided subscripts should equal the number of dimensions.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 2;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the element located at (1,1):
var v = arr.get( 1, 1 );
// returns 6.0

ndarray.prototype.iget( idx )

Returns an array element located at a specified linear index.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 2;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Get the element located at index 3:
var v = arr.iget( 3 );
// returns 6.0

ndarray.prototype.set( i, j, k, ..., v )

Sets an array element specified according to provided subscripts. The number of provided subscripts should equal the number of dimensions.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Set the element located at (1,1):
arr.set( 1, 1, 40.0 );
var v = arr.get( 1, 1 );
// returns 40.0

// Get the underlying buffer:
var d = arr.buffer;
// returns [ 1.0, 2.0, 3.0, 40.0 ]

The method returns the ndarray instance.

ndarray.prototype.iset( idx, v )

Sets an array element located at a specified linear index.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0 ];
var shape = [ 2, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 0;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Set the element located at index 3:
arr.iset( 3, 40.0 );
var v = arr.iget( 3 );
// returns 40.0

// Get the underlying buffer:
var d = arr.buffer;
// returns [ 1.0, 2.0, 3.0, 40.0 ]

The method returns the ndarray instance.

ndarray.prototype.toString()

Serializes an ndarray as a string.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
var shape = [ 3, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 2;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Serialize to a string:
var str = arr.toString();
// e.g., returns 'ndarray( [ 3, 4, 5, 6, 7, 8 ], [ 3, 2 ], [ 2, 1 ], 0, "row-major" )'

The method does not serialize data outside of the buffer region defined by the array configuration.

ndarray.prototype.toJSON()

Serializes an ndarray as a JSON object. JSON.stringify() implicitly calls this method when stringifying an ndarray instance.

// Create a constructor for generating "generic" 2-dimensional ndarrays:
var ndarray = ctor( 'generic', 2 );

// Specify the array configuration:
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ];
var shape = [ 3, 2 ];
var order = 'row-major';
var strides = [ 2, 1 ];
var offset = 2;

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Serialize to JSON:
var o = arr.toJSON();
// e.g., returns { 'type': 'ndarray', 'dtype': 'generic', 'flags': {...}, 'offset': 0, 'order': 'row-major', 'shape': [ 3, 2 ], 'strides': [ 2, 1 ], 'data': [ 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] }

The method does not serialize data outside of the buffer region defined by the array configuration.

---

Notes

• Code generation can boost performance, but may be problematic in browser contexts enforcing a strict content security policy (CSP). If running in or targeting an environment with a CSP, set the codegen option to false.

---

Examples

var Float32Array = require( '@stdlib/array/float32' );
var ctor = require( '@stdlib/ndarray/ctor' );

// Create an ndarray constructor for a 4-dimensional array containing single-precision floating-point numbers:
var ndarray = ctor( 'float32', 4 );

// Create a data buffer:
var buffer = new Float32Array( (3*3*3*3) + 100 );

// Specify the array shape:
var shape = [ 3, 3, 3, 3 ];

// Specify the array strides:
var strides = [ 27, 9, 3, 1 ];

// Specify the index offset:
var offset = 4;

// Specify the order:
var order = 'row-major'; // C-style

// Create a new ndarray:
var arr = ndarray( buffer, shape, strides, offset, order );

// Retrieve an array value:
var v = arr.get( 1, 2, 1, 2 );
// returns 0.0

// Set an array value:
arr.set( 1, 2, 1, 2, 10.0 );

// Retrieve the array value:
v = arr.get( 1, 2, 1, 2 );
// returns 10.0

// Serialize the array as a string:
var str = arr.toString();
// returns "ndarray( new Float32Array( [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] ), [ 3, 3, 3, 3 ], [ 27, 9, 3, 1 ], 0, 'row-major' )"

// Serialize the array as JSON:
str = JSON.stringify( arr.toJSON() );
// returns '{"type":"ndarray","dtype":"float32","flags":{},"order":"row-major","shape":[3,3,3,3],"strides":[27,9,3,1],"data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,10,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}'