# nditerInterleaveSubarrays
> Create an iterator which iterates over interleaved subarrays.
## Usage
```javascript
var nditerInterleaveSubarrays = require( '@stdlib/ndarray/iter/interleave-subarrays' );
```
#### nditerInterleaveSubarrays( arr, ndims )
Returns an iterator which iterates over interleaved subarrays.
```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 = nditerInterleaveSubarrays( [ x, x ], 2 );
var v = iter.next().value;
// returns
var arr = ndarray2array( v );
// returns [ [ 1, 2 ], [ 3, 4 ] ]
v = iter.next().value;
// returns
arr = ndarray2array( v );
// returns [ [ 1, 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
- All provided [`ndarrays`][@stdlib/ndarray/ctor] must be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes].
- After broadcasting, each broadcasted input [`ndarray`][@stdlib/ndarray/ctor] must have at least `ndims+1` dimensions.
- For input [`ndarrays`][@stdlib/ndarray/ctor] supporting read-only views, the function returns **read-only** views of interleaved subarrays. As input [`ndarrays`][@stdlib/ndarray/ctor] may be broadcasted, a view is typically **not** contiguous. As more than one element of a returned view may refer to the same memory location, writing to a view may affect multiple elements. If you need to write to a subarray, copy the subarray **before** attempting mutation.
- 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 nditerInterleaveSubarrays = require( '@stdlib/ndarray/iter/interleave-subarrays' );
// Define input arrays:
var x = array( zeroTo( 27 ), {
'shape': [ 3, 3, 3 ]
});
var y = array( zeroTo( 9 ), {
'shape': [ 3, 3 ]
});
// Create an iterator for iterating over interleaved matrices:
var it = nditerInterleaveSubarrays( [ x, y ], 2 );
// 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/base/broadcast-shapes]: https://github.com/stdlib-js/ndarray/tree/main/base/broadcast-shapes
[@stdlib/ndarray/iter/subarrays]: https://github.com/stdlib-js/ndarray/tree/main/iter/subarrays
[@stdlib/ndarray/slice]: https://github.com/stdlib-js/ndarray/tree/main/slice