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 consider financially supporting stdlib. We greatly appreciate your continued support!
Fancy multidimensional array constructor.
A FancyArray is an ndarray which supports slicing via indexing expressions.
import ndarray2array from 'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-to-array@esm/index.mjs';
import FancyArray from 'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-fancy@esm/index.mjs';
var buffer = [ 1, 2, 3, 4, 5, 6 ];
var x = new FancyArray( 'generic', buffer, [ 6 ], [ 1 ], 0, 'row-major' );
// returns <FancyArray>
// Select the first 3 elements:
var y = x[ ':3' ];
// returns <FancyArray>
var arr = ndarray2array( y );
// returns [ 1, 2, 3 ]
// Select every other element, starting with the second element:
y = x[ '1::2' ];
// returns <FancyArray>
arr = ndarray2array( y );
// returns [ 2, 4, 6 ]
// Reverse the array, starting with last element and skipping every other element:
y = x[ '::-2' ];
// returns <FancyArray>
arr = ndarray2array( y );
// returns [ 6, 4, 2 ]import FancyArray from 'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-fancy@esm/index.mjs';Returns a FancyArray instance.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// returns <FancyArray>The constructor expects the following arguments:
- dtype: underlying data 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 either
row-major(C-style) orcolumn-major(Fortran-style).
The constructor accepts the following options:
- 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 be read-only. Default:
false.
The constructor supports the following modes:
- throw: specifies that a
FancyArrayinstance should throw an error when an index exceeds array dimensions. - normalize: specifies that a
FancyArrayinstance should normalize negative indices and throw an error when an index exceeds array dimensions. - wrap: specifies that a
FancyArrayinstance should wrap around an index exceeding array dimensions using modulo arithmetic. - clamp: specifies that a
FancyArrayinstance should set an index exceeding array dimensions to either0(minimum index) or the maximum index.
By default, a FancyArray 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 (but not slicing semantics) for getting and setting array elements.
var opts = {
'mode': 'clamp'
};
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order, opts );
// returns <FancyArray>
// Attempt to access an out-of-bounds linear index (clamped):
var v = arr.iget( 10 );
// returns 4.0By 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' ]
};
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order, opts );
// returns <FancyArray>
// Attempt to access out-of-bounds subscripts:
var v = arr.get( -2, 10, -1 ); // linear index: 3
// returns 4.0String value of the constructor name.
var str = FancyArray.name;
// returns 'ndarray'Size (in bytes) of the array (if known).
import Float64Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-float64@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'float64', buffer, shape, strides, offset, order );
// Get the byte length:
var nbytes = arr.byteLength;
// returns 32If unable to determine the size of the array, the property value is null.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Get the byte length:
var nbytes = arr.byteLength;
// returns nullSize (in bytes) of each array element (if known).
import Float32Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-float32@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'float32', buffer, shape, strides, offset, order );
// Get the number of bytes per element:
var nbytes = arr.BYTES_PER_ELEMENT;
// returns 4If size of each array element is unknown, the property value is null.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Get the number of bytes per element:
var nbytes = arr.BYTES_PER_ELEMENT;
// returns nullA reference to the underlying data buffer.
import Int8Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-int8@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'int8', buffer, shape, strides, offset, order );
// Get the buffer reference:
var d = arr.data;
// returns <Int8Array>[ 1, 2, 3, 4 ]
var bool = ( d === buffer );
// returns trueUnderlying data type.
import Uint8Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint8@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'uint8', buffer, shape, strides, offset, order );
// Get the underlying data type:
var dtype = arr.dtype;
// returns 'uint8'Meta information, such as information regarding the memory layout of the array. The returned object has the following properties:
- ROW_MAJOR_CONTIGUOUS:
booleanindicating if an array is row-major contiguous. - COLUMN_MAJOR_CONTIGUOUS:
booleanindicating if an array is column-major contiguous. - READONLY:
booleanindicating whether an array is read-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 array with strides = [1]).
import Int32Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-int32@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'int32', buffer, shape, strides, offset, order );
// Get the array flags:
var flg = arr.flags;
// returns {...}Number of array elements.
import Uint16Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint16@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'uint16', buffer, shape, strides, offset, order );
// Get the array length:
var len = arr.length;
// returns 4Number of dimensions.
import Uint8ClampedArray from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint8c@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'uint8c', buffer, shape, strides, offset, order );
// Get the number of dimensions:
var ndims = arr.ndims;
// returns 2Index offset which specifies the buffer index at which to start iterating over array elements.
import Int16Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-int16@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'int16', buffer, shape, strides, offset, order );
// Get the index offset:
var o = arr.offset;
// returns 10Array order. The array order is either row-major (C-style) or column-major (Fortran-style).
import Uint32Array from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-uint32@esm/index.mjs';
// 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 array:
var arr = new FancyArray( 'uint32', buffer, shape, strides, offset, order );
// Get the array order:
var ord = arr.order;
// returns 'row-major'Returns a copy of the array shape.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Get the array shape:
var dims = arr.shape;
// returns [ 2, 2 ]Returns a copy of the array strides which specify how to access data along corresponding array dimensions.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Get the array strides:
var s = arr.strides;
// returns [ -1, 2 ]Returns an array element specified according to provided subscripts. The number of provided subscripts must equal the number of dimensions.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Get the element located at (1,1):
var v = arr.get( 1, 1 );
// returns 6.0Returns an array element located at a specified linear index.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Get the element located at index 3:
var v = arr.iget( 3 );
// returns 6.0For zero-dimensional arrays, the input argument is ignored and, for clarity, should not be provided.
Sets an array element specified according to provided subscripts. The number of provided subscripts must equal the number of dimensions.
// 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 array:
var arr = new FancyArray( 'generic', 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.data;
// returns [ 1.0, 2.0, 3.0, 40.0 ]The method returns the FancyArray instance. If an array is read-only, the method raises an exception.
Sets an array element located at a specified linear index.
// 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 array:
var arr = new FancyArray( 'generic', 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.data;
// returns [ 1.0, 2.0, 3.0, 40.0 ]For zero-dimensional arrays, the first, and only, argument should be the value v to set.
The method returns the FancyArray instance. If an array is read-only, the method raises an exception.
Serializes a FancyArray as a string.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Serialize to a string:
var str = arr.toString();
// returns "ndarray( 'generic', [ 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.
Serializes a FancyArray as a JSON object. JSON.stringify() implicitly calls this method when stringifying a FancyArray instance.
// 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 array:
var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order );
// Serialize to JSON:
var o = 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 does not serialize data outside of the buffer region defined by the array configuration.
-
To create a zero-dimensional array, provide an empty
shapeand a singlestrideselement equal to0. Theordercan be eitherrow-majororcolumn-majorand has no effect on data storage or access.var buffer = [ 1 ]; var shape = []; var order = 'row-major'; var strides = [ 0 ]; var offset = 0; // Create a new zero-dimensional array: var arr = new FancyArray( 'generic', buffer, shape, strides, offset, order ); // returns <FancyArray>
-
A
FancyArrayis anndarrayinstance and supports allndarrayoptions, attributes, and methods. AFancyArraycan be consumed by any API which supportsndarrayinstances. -
Indexing expressions provide a convenient and powerful means for creating and operating on
ndarrayviews; however, their use does entail a performance cost. Indexing expressions are best suited for interactive use (e.g., in the REPL) and scripting. For performance critical applications, prefer equivalent functional APIs supportingndarrayinstances. -
In older JavaScript environments which do not support
Proxyobjects, the use of indexing expressions is not supported.
<!DOCTYPE html>
<html lang="en">
<body>
<script type="module">
import S from 'https://cdn.jsdelivr.net/gh/stdlib-js/slice-ctor@esm/index.mjs';
import E from 'https://cdn.jsdelivr.net/gh/stdlib-js/slice-multi@esm/index.mjs';
import toArray from 'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-to-array@esm/index.mjs';
import FancyArray from 'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-fancy@esm/index.mjs';
var buffer = [
1, 2,
3, 4, // 0
5, 6, // 1
7, 8, // 2
9, 10
];
var shape = [ 3, 2 ];
var strides = [ 2, 1 ];
var offset = 2;
var x = new FancyArray( 'generic', buffer, shape, strides, offset, 'row-major' );
// returns <FancyArray>
// Access an ndarray property:
var ndims = x.ndims;
// returns 2
// Retrieve an ndarray element:
var v = x.get( 2, 1 );
// returns 8
// Set an ndarray element:
x.set( 2, 1, 20 );
v = x.get( 2, 1 );
// returns 20
// Create an alias for `undefined` for more concise slicing expressions:
var _ = void 0;
// Create a multi-dimensional slice:
var s = E( S(0,_,2), _ );
// returns <MultiSlice>
// Use the slice to create a view on the original ndarray:
var y1 = x[ s ];
console.log( toArray( y1 ) );
// => [ [ 3, 4 ], [ 7, 20 ] ]
// Use alternative syntax:
var y2 = x[ [ S(0,_,2), _ ] ];
console.log( toArray( y2 ) );
// => [ [ 3, 4 ], [ 7, 20 ] ]
// Use alternative syntax:
var y3 = x[ '0::2,:' ];
console.log( toArray( y3 ) );
// => [ [ 3, 4 ], [ 7, 20 ] ]
// Flip dimensions:
var y4 = x[ [ S(_,_,-2), S(_,_,-1) ] ];
console.log( toArray( y4 ) );
// => [ [ 20, 7 ], [ 4, 3 ] ]
</script>
</body>
</html>@stdlib/ndarray-array: multidimensional arrays.@stdlib/ndarray-ctor: multidimensional array constructor.
This package is part of stdlib, 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 develop stdlib, see the main project repository.
See LICENSE.
Copyright © 2016-2025. The Stdlib Authors.
