# nditerMatrices
> Create an iterator which iterates over each matrix in a stack of matrices.
## Usage
```javascript
var nditerMatrices = require( '@stdlib/ndarray/iter/matrices' );
```
#### nditerMatrices( x\[, options] )
Returns an iterator which iterates over each matrix in a stack of matrices.
```javascript
var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ] );
// returns
var iter = nditerMatrices( x );
var v = iter.next().value;
// returns
var arr = ndarray2array( v );
// returns [ [ 1, 2 ], [ 3, 4 ] ]
v = iter.next().value;
// returns
arr = ndarray2array( v );
// returns [ [ 5, 6 ], [ 7, 8 ] ]
// ...
```
The function accepts the following `options`:
- **readonly**: boolean indicating whether returned [`ndarray`][@stdlib/ndarray/ctor] views should be read-only. In order to return writable [`ndarray`][@stdlib/ndarray/ctor] views, the input [`ndarray`][@stdlib/ndarray/ctor] must be writable. If the input [`ndarray`][@stdlib/ndarray/ctor] is read-only, setting this option to `false` raises an exception. Default: `true`.
By default, the iterator returns [`ndarray`][@stdlib/ndarray/ctor] views which are **read-only**. To return writable [views][@stdlib/ndarray/slice], set the `readonly` option to `false`.
```javascript
var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 5, 6 ], [ 7, 8 ] ] ] );
// returns
var iter = nditerMatrices( x, {
'readonly': false
});
var v = iter.next().value;
// returns
var arr = ndarray2array( v );
// returns [ [ 1, 2 ], [ 3, 4 ] ]
v.set( 0, 0, 10 );
arr = ndarray2array( v );
// returns [ [ 10, 2 ], [ 3, 4 ] ]
```
The returned [iterator][mdn-iterator-protocol] protocol-compliant object has the following properties:
- **next**: function which returns an [iterator][mdn-iterator-protocol] protocol-compliant object containing the next iterated value (if one exists) assigned to a `value` property and a `done` property having a `boolean` value indicating whether the [iterator][mdn-iterator-protocol] is finished.
- **return**: function which closes an [iterator][mdn-iterator-protocol] and returns a single (optional) argument in an [iterator][mdn-iterator-protocol] protocol-compliant object.
## Notes
- If an environment supports `Symbol.iterator`, the returned iterator is iterable.
- A returned iterator does **not** copy a provided [`ndarray`][@stdlib/ndarray/ctor]. To ensure iterable reproducibility, copy the input [`ndarray`][@stdlib/ndarray/ctor] **before** creating an iterator. Otherwise, any changes to the contents of input [`ndarray`][@stdlib/ndarray/ctor] will be reflected in the returned iterator.
- In environments supporting `Symbol.iterator`, the function **explicitly** does **not** invoke an ndarray's `@@iterator` method, regardless of whether this method is defined.
## Examples
```javascript
var array = require( '@stdlib/ndarray/array' );
var zeroTo = require( '@stdlib/array/base/zero-to' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var nditerMatrices = require( '@stdlib/ndarray/iter/matrices' );
// Define an input array:
var x = array( zeroTo( 27 ), {
'shape': [ 3, 3, 3 ]
});
// Create an iterator for iterating over matrices:
var it = nditerMatrices( x );
// Perform manual iteration...
var v;
while ( true ) {
v = it.next();
if ( v.done ) {
break;
}
console.log( ndarray2array( v.value ) );
}
```
[mdn-iterator-protocol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray/tree/main/ctor
[@stdlib/ndarray/slice]: https://github.com/stdlib-js/ndarray/tree/main/slice
[@stdlib/ndarray/iter/columns]: https://github.com/stdlib-js/ndarray/tree/main/iter/columns
[@stdlib/ndarray/iter/matrix-entries]: https://github.com/stdlib-js/ndarray/tree/main/iter/matrix-entries
[@stdlib/ndarray/iter/rows]: https://github.com/stdlib-js/ndarray/tree/main/iter/rows