# ndarray
> Create a multidimensional array.
## Usage
```javascript
var ndarray = require( '@stdlib/ndarray/base/ctor' );
```
#### ndarray( dtype, buffer, shape, strides, offset, order )
Returns an `ndarray` instance.
```javascript
// 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( 'generic', buffer, shape, strides, offset, order );
// returns
```
The constructor has the following parameters:
- **dtype**: underlying [data type][@stdlib/ndarray/dtypes].
- **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).
To create a zero-dimensional array, provide an empty `shape` and a single `strides` element equal to `0`. The `order` can be either `row-major` or `column-major` and has no effect on data storage or access.
```javascript
var buffer = [ 1 ];
var shape = [];
var order = 'row-major';
var strides = [ 0 ];
var offset = 0;
// Create a new zero-dimensional array:
var arr = ndarray( 'generic', buffer, shape, strides, offset, order );
// returns
```
* * *
### Properties
#### ndarray.name
String value of the ndarray constructor name.
```javascript
var str = ndarray.name;
// returns 'ndarray'
```
#### ndarray.prototype.byteLength
Size (in bytes) of the array (if known).
```javascript
var Float64Array = require( '@stdlib/array/float64' );
// 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( 'float64', 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`.
```javascript
// 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( 'generic', 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).
```javascript
var Float32Array = require( '@stdlib/array/float32' );
// 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( 'float32', 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`.
```javascript
// 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( 'generic', 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.
```javascript
var Int8Array = require( '@stdlib/array/int8' );
// 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( 'int8', buffer, shape, strides, offset, order );
// Get the buffer reference:
var d = arr.data;
// returns [ 1, 2, 3, 4 ]
var bool = ( d === buffer );
// returns true
```
#### ndarray.prototype.dtype
Underlying [data type][@stdlib/ndarray/dtypes].
```javascript
var Uint8Array = require( '@stdlib/array/uint8' );
// 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( 'uint8', 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]`).
```javascript
var Int32Array = require( '@stdlib/array/int32' );
// 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( 'int32', buffer, shape, strides, offset, order );
// Get the array flags:
var flg = arr.flags;
// returns {...}
```
#### ndarray.prototype.length
Number of array elements.
```javascript
var Uint16Array = require( '@stdlib/array/uint16' );
// 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( 'uint16', buffer, shape, strides, offset, order );
// Get the array length:
var len = arr.length;
// returns 4
```
#### ndarray.prototype.ndims
Number of dimensions.
```javascript
var Uint8ClampedArray = require( '@stdlib/array/uint8c' );
// 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( 'uint8c', 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.
```javascript
var Int16Array = require( '@stdlib/array/int16' );
// 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( 'int16', 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).
```javascript
var Uint32Array = require( '@stdlib/array/uint32' );
// 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( 'uint32', 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.
```javascript
// 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( 'generic', 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.
```javascript
// 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( 'generic', 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.
```javascript
// 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( 'generic', 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.
```javascript
// 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( 'generic', buffer, shape, strides, offset, order );
// Get the element located at index 3:
var v = arr.iget( 3 );
// returns 6
```
For zero-dimensional arrays, the input argument is ignored and, for clarity, should **not** be provided.
#### 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.
```javascript
// 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( 'generic', 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.data;
// 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.
```javascript
// 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( 'generic', 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.data;
// returns [ 1, 2, 3, 40 ]
```
For zero-dimensional arrays, the first, and **only**, argument should be the value `v` to set. The method returns the `ndarray` instance.
#### ndarray.prototype.toString()
Serializes an `ndarray` as a `string`.
```javascript
// 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( '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.
#### ndarray.prototype.toJSON()
Serializes an `ndarray` as a [JSON][json] `object`. `JSON.stringify()` implicitly calls this method when stringifying an `ndarray` instance.
```javascript
// 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( '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, 4, 5, 6, 7, 8 ] }
```
The method does **not** 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 a `length` property). For data buffers which are not indexed collections (i.e., collections which cannot support direct index access, such as `buffer[ index ]`; e.g., [`Complex64Array`][@stdlib/array/complex64], [`Complex128Array`][@stdlib/array/complex128], etc), a data buffer should provide `#.get( idx )` and `#.set( v[, idx] )` methods. Note that, for `set` methods, the value to set should be the first argument, followed by the linear index, similar to the native typed array `set` method.
* * *
## Examples
```javascript
var Float32Array = require( '@stdlib/array/float32' );
var ndarray = require( '@stdlib/ndarray/base/ctor' );
// 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( 'float32', 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( '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() );
// 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]}'
```
[json]: http://www.json.org/
[@stdlib/ndarray/dtypes]: https://www.npmjs.com/package/@stdlib/ndarray/tree/main/dtypes
[@stdlib/array/complex64]: https://www.npmjs.com/package/@stdlib/array-complex64
[@stdlib/array/complex128]: https://www.npmjs.com/package/@stdlib/array-complex128