stdlib-js/ndarray-ctorPublic

NotificationsYou must be signed in to change notification settings
Fork0
Star3

Multidimensional array constructor.

License

Apache-2.0 license

3 stars 0 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 188 Commits
CONTRIBUTORS		CONTRIBUTORS
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
index.d.ts		index.d.ts
index.mjs		index.mjs
index.mjs.map		index.mjs.map
package.json		package.json
stats.html		stats.html

Repository files navigation

About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please considerfinancially supporting stdlib. We greatly appreciate your continued support!

ndarray

Multidimensional array constructor.

Usage

importndarrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-ctor@esm/index.mjs';

ndarray( dtype, buffer, shape, strides, offset, order[, options] )

Returns anndarray instance.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// returns <ndarray>

The constructor expects the following arguments:

dtype: underlyingdata type.
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 eitherrow-major (C-style) orcolumn-major (Fortran-style).

The constructor accepts the followingoptions:

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 constructor recycles modes using modulo arithmetic. Default:[ options.mode ].
readonly:boolean indicating whether an array should beread-only. Default:false.

The constructor supports the followingmodes:

throw: specifies that anndarray instance should throw an error when an index exceeds array dimensions.
normalize: specifies that anndarray instance should normalize negative indices and throw an error when an index exceeds array dimensions.
wrap: specifies that anndarray instance should wrap around an index exceeding array dimensions using modulo arithmetic.
clamp: specifies that anndarray instance should set an index exceeding array dimensions to either0 (minimum index) or the maximum index.

By default, anndarray instancethrows when provided an index which exceeds array dimensions. To support alternative indexing behavior, set themode option, which will affect all public methods for getting and setting array elements.

varopts={'mode':'clamp'};// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order,opts);// returns <ndarray>// Attempt to access an out-of-bounds linear index (clamped):varv=arr.iget(10);// returns 4.0

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

varopts={'submode':['wrap','clamp']};// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0];varshape=[2,2,2];varorder='row-major';varstrides=[4,2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order,opts);// returns <ndarray>// Attempt to access out-of-bounds subscripts:varv=arr.get(-2,10,-1);// linear index: 3// returns 4.0

Properties

ndarray.name

String value of the ndarray constructor name.

varstr=ndarray.name;// returns 'ndarray'

ndarray.prototype.byteLength

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

importFloat64Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-float64@esm/index.mjs';// Specify the array configuration:varbuffer=newFloat64Array([1.0,2.0,3.0,4.0]);varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('float64',buffer,shape,strides,offset,order);// Get the byte length:varnbytes=arr.byteLength;// returns 32

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

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Get the byte length:varnbytes=arr.byteLength;// returns null

ndarray.prototype.BYTES_PER_ELEMENT

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

importFloat32Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-float32@esm/index.mjs';// Specify the array configuration:varbuffer=newFloat32Array([1.0,2.0,3.0,4.0]);varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('float32',buffer,shape,strides,offset,order);// Get the number of bytes per element:varnbytes=arr.BYTES_PER_ELEMENT;// returns 4

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

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Get the number of bytes per element:varnbytes=arr.BYTES_PER_ELEMENT;// returns null

ndarray.prototype.data

A reference to the underlying data buffer.

importInt8Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-int8@esm/index.mjs';// Specify the array configuration:varbuffer=newInt8Array([1,2,3,4]);varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('int8',buffer,shape,strides,offset,order);// Get the buffer reference:vard=arr.data;// returns <Int8Array>[ 1, 2, 3, 4 ]varbool=(d===buffer);// returns true

ndarray.prototype.dtype

Underlyingdata type.

importUint8Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint8@esm/index.mjs';// Specify the array configuration:varbuffer=newUint8Array([1,2,3,4]);varshape=[2,2];varorder='row-major';varstrides=[-2,1];varoffset=2;// Create a new ndarray:vararr=ndarray('uint8',buffer,shape,strides,offset,order);// Get the underlying data type:vardtype=arr.dtype;// returns 'uint8'

ndarray.prototype.flags

Meta information, such as 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.
READONLY: boolean indicating whether an array isread-only.

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 withstrides = [1]).

importInt32Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-int32@esm/index.mjs';// Specify the array configuration:varbuffer=newInt32Array([1,2,3,4]);varshape=[2,2];varorder='column-major';varstrides=[1,2];varoffset=0;// Create a new ndarray:vararr=ndarray('int32',buffer,shape,strides,offset,order);// Get the array flags:varflg=arr.flags;// returns {...}

ndarray.prototype.length

Number of array elements.

importUint16Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint16@esm/index.mjs';// Specify the array configuration:varbuffer=newUint16Array([1,2,3,4]);varshape=[2,2];varorder='column-major';varstrides=[-1,-2];varoffset=3;// Create a new ndarray:vararr=ndarray('uint16',buffer,shape,strides,offset,order);// Get the array length:varlen=arr.length;// returns 4

ndarray.prototype.ndims

Number of dimensions.

importUint8ClampedArrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint8c@esm/index.mjs';// Specify the array configuration:varbuffer=newUint8ClampedArray([1,2,3,4]);varshape=[2,2];varorder='row-major';varstrides=[-2,-1];varoffset=3;// Create a new ndarray:vararr=ndarray('uint8c',buffer,shape,strides,offset,order);// Get the number of dimensions:varndims=arr.ndims;// returns 2

ndarray.prototype.offset

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

importInt16Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-int16@esm/index.mjs';// Specify the array configuration:varbuffer=newInt16Array([1,2,3,4,5,6,7,8,9,10,11,12]);varshape=[2,2];varorder='row-major';varstrides=[-2,-1];varoffset=10;// Create a new ndarray:vararr=ndarray('int16',buffer,shape,strides,offset,order);// Get the index offset:varo=arr.offset;// returns 10

ndarray.prototype.order

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

importUint32Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint32@esm/index.mjs';// Specify the array configuration:varbuffer=newUint32Array([1,2,3,4]);varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('uint32',buffer,shape,strides,offset,order);// Get the array order:varord=arr.order;// returns 'row-major'

ndarray.prototype.shape

Returns a copy of the array shape.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0,5.0,6.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=2;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Get the array shape:vardims=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.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0];varshape=[2,2];varorder='column-major';varstrides=[-1,2];varoffset=1;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Get the array strides:vars=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 mustequal the number of dimensions.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=2;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Get the element located at (1,1):varv=arr.get(1,1);// returns 6.0

ndarray.prototype.iget( idx )

Returns an array element located at a specified linear index.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=2;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Get the element located at index 3:varv=arr.iget(3);// returns 6.0

For zero-dimensional arrays, the input argument is ignored and, for clarity, shouldnot be provided.

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

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

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Set the element located at (1,1):arr.set(1,1,40.0);varv=arr.get(1,1);// returns 40.0// Get the underlying buffer:vard=arr.data;// returns [ 1.0, 2.0, 3.0, 40.0 ]

The method returns thendarray instance. If an array isread-only, the method raises an exception.

ndarray.prototype.iset( idx, v )

Sets an array element located at a specified linear index.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0];varshape=[2,2];varorder='row-major';varstrides=[2,1];varoffset=0;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Set the element located at index 3:arr.iset(3,40.0);varv=arr.iget(3);// returns 40.0// Get the underlying buffer:vard=arr.data;// returns [ 1.0, 2.0, 3.0, 40.0 ]

For zero-dimensional arrays, the first, andonly, argument should be the valuev to set.

The method returns thendarray instance. If an array isread-only, the method raises an exception.

ndarray.prototype.toString()

Serializes anndarray as astring.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0];varshape=[3,2];varorder='row-major';varstrides=[2,1];varoffset=2;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Serialize to a string:varstr=arr.toString();// returns "ndarray( 'generic', [ 3, 4, 5, 6, 7, 8 ], [ 3, 2 ], [ 2, 1 ], 0, 'row-major' )"

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

ndarray.prototype.toJSON()

Serializes anndarray as aJSONobject.JSON.stringify() implicitly calls this method when stringifying anndarray instance.

// Specify the array configuration:varbuffer=[1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0];varshape=[3,2];varorder='row-major';varstrides=[2,1];varoffset=2;// Create a new ndarray:vararr=ndarray('generic',buffer,shape,strides,offset,order);// Serialize to JSON:varo=arr.toJSON();// 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 doesnot serialize data outside of the buffer region defined by the array configuration.

Notes

To create a zero-dimensional array, provide an emptyshape and a singlestrides element equal to0. Theorder can be eitherrow-major orcolumn-major and has no effect on data storage or access.

varbuffer=[1];varshape=[];varorder='row-major';varstrides=[0];varoffset=0;// Create a new zero-dimensional array:vararr=ndarray('generic',buffer,shape,strides,offset,order);// returns <ndarray>

Examples

<!DOCTYPE html><htmllang="en"><body><scripttype="module">importFloat32Arrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/array-float32@esm/index.mjs';importndarrayfrom'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-ctor@esm/index.mjs';// Create a data buffer:varbuffer=newFloat32Array((3*3*3*3)+100);// Specify the array shape:varshape=[3,3,3,3];// Specify the array strides:varstrides=[27,9,3,1];// Specify the index offset:varoffset=4;// Specify the order:varorder='row-major';// C-style// Create a new ndarray:vararr=ndarray('float32',buffer,shape,strides,offset,order);// Retrieve an array value:varv=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:varstr=arr.toString();// returns "ndarray( 'float32', 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());// e.g., returns '{"type":"ndarray","dtype":"float32","flags":{"READONLY":false},"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]}'</script></body></html>

Notice

This package is part ofstdlib, a standard library with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to developstdlib, see the main projectrepository.