Constructor

Create a multidimensional array constructor.

Usage

var ctor = require( '@stdlib/ndarray/base/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.

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>

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, 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 );
// returns <ndarray>

The constructor expects the following parameters:

• 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, 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 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, 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 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, 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 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, 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 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, 2, 3, 4, 5, 6 ];
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, 2, 3, 4 ];
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, 2, 3, 4, 5, 6, 7, 8 ];
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

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, 2, 3, 4, 5, 6, 7, 8 ];
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

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, 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 );

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

// Get the underlying buffer:
var d = arr.buffer;
// returns [ 1, 2, 3, 40 ]

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, 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 );

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

// Get the underlying buffer:
var d = arr.buffer;
// returns [ 1, 2, 3, 40 ]

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, 2, 3, 4, 5, 6, 7, 8 ];
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, 2, 3, 4, 5, 6, 7, 8 ];
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, 4, 5, 6, 7, 8 ] }

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/base/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]}'