stdlib-js/ndarray-base-ctorPublic

NotificationsYou must be signed in to change notification settings
Fork0
Star3

Base multidimensional array.

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 270 Commits
CONTRIBUTORS		CONTRIBUTORS
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
browser.js		browser.js
browser.js.map		browser.js.map
index.js		index.js
index.js.map		index.js.map
package.json		package.json
stats_browser.html		stats_browser.html
stats_node.html		stats_node.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

Create a multidimensional array.

Usage

To use in Observable,

ndarray=require('https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-base-ctor@umd/browser.js')

To vendor stdlib functionality and avoid installing dependency trees for Node.js, you can use the UMD server build:

varndarray=require('path/to/vendor/umd/ndarray-base-ctor/index.js')

To include the bundle in a webpage,

<scripttype="text/javascript"src="https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-base-ctor@umd/browser.js"></script>

If no recognized module system is present, access bundle contents via the global scope:

<scripttype="text/javascript">(function(){window.ndarray;})();</script>

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

Returns anndarray instance.

// Specify the array configuration:varbuffer=[1,2,3,4];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 has the following parameters:

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

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>

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

varFloat64Array=require('@stdlib/array-float64');// Specify the array configuration:varbuffer=newFloat64Array([1,2,3,4]);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,2,3,4];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).

varFloat32Array=require('@stdlib/array-float32');// Specify the array configuration:varbuffer=newFloat32Array([1,2,3,4]);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,2,3,4];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.

varInt8Array=require('@stdlib/array-int8');// 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.

varUint8Array=require('@stdlib/array-uint8');// 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 concerning 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 if 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]).

varInt32Array=require('@stdlib/array-int32');// 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.

varUint16Array=require('@stdlib/array-uint16');// 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.

varUint8ClampedArray=require('@stdlib/array-uint8c');// 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.

varInt16Array=require('@stdlib/array-int16');// 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).

varUint32Array=require('@stdlib/array-uint32');// 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,2,3,4,5,6];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,2,3,4];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 shouldequal the number of dimensions.

// Specify the array configuration:varbuffer=[1,2,3,4,5,6,7,8];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

ndarray.prototype.iget( idx )

Returns an array element located at a specified linear index.

// Specify the array configuration:varbuffer=[1,2,3,4,5,6,7,8];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

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 shouldequal the number of dimensions.

// Specify the array configuration:varbuffer=[1,2,3,4];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);varv=arr.get(1,1);// returns 40// Get the underlying buffer:vard=arr.data;// returns [ 1, 2, 3, 40 ]

The method returns thendarray instance.

ndarray.prototype.iset( idx, v )

Sets an array element located at a specified linear index.

// Specify the array configuration:varbuffer=[1,2,3,4];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);varv=arr.iget(3);// returns 40// Get the underlying buffer:vard=arr.data;// returns [ 1, 2, 3, 40 ]

For zero-dimensional arrays, the first, andonly, argument should be the valuev to set. The method returns thendarray instance.

ndarray.prototype.toString()

Serializes anndarray as astring.

// Specify the array configuration:varbuffer=[1,2,3,4,5,6,7,8];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 aJSON object.JSON.stringify() implicitly calls this method when stringifying anndarray instance.

// Specify the array configuration:varbuffer=[1,2,3,4,5,6,7,8];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, 4, 5, 6, 7, 8 ]}

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

Notes

A data buffer must be an array-like object (i.e., have alength property). For data buffers which are not indexed collections (i.e., collections which cannot support direct index access, such asbuffer[ index ]; e.g.,Complex64Array,Complex128Array, etc), a data buffer should provide#.get( idx ) and#.set( v[, idx] ) methods. Note that, forset methods, the value to set should be the first argument, followed by the linear index, similar to the native typed arrayset method.

Examples

<!DOCTYPE html><htmllang="en"><body><scripttype="text/javascript"src="https://cdn.jsdelivr.net/gh/stdlib-js/array-float32@umd/browser.js"></script><scripttype="text/javascript"src="https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-base-ctor@umd/browser.js"></script><scripttype="text/javascript">(function(){// 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 for JavaScript and Node.js, 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.