# slice
> Return a read-only view of an input [`ndarray`][@stdlib/ndarray/ctor].
## Usage
```javascript
var slice = require( '@stdlib/ndarray/slice' );
```
#### slice( x, ...s\[, options] )
Returns a **read-only** view of an input [`ndarray`][@stdlib/ndarray/ctor].
```javascript
var Slice = require( '@stdlib/slice/ctor' );
var MultiSlice = require( '@stdlib/slice/multi' );
var ndarray = require( '@stdlib/ndarray/ctor' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
var shape = [ 3, 2 ];
var strides = [ 2, 1 ];
var offset = 0;
var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
// returns
var sh = x.shape;
// returns [ 3, 2 ]
var arr = ndarray2array( x );
// returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
var s0 = new Slice( null, null, -2 );
var s1 = new Slice( null, null, -1 );
var s = new MultiSlice( s0, s1 );
// returns
var y = slice( x, s );
// returns
sh = y.shape;
// returns [ 2, 2 ]
arr = ndarray2array( y );
// returns [ [ 6.0, 5.0 ], [ 2.0, 1.0 ] ]
```
The function accepts the following arguments:
- **x**: input [`ndarray`][@stdlib/ndarray/ctor].
- **s**: a [`MultiSlice`][@stdlib/slice/multi] instance, an array of slice arguments, or slice arguments as separate arguments.
- **options**: function options.
The function supports three (mutually exclusive) means for providing slice arguments:
1. providing a single [`MultiSlice`][@stdlib/slice/multi] instance.
2. providing a single array of slice arguments.
3. providing slice arguments as separate arguments.
The following example demonstrates each invocation style returning equivalent results.
```javascript
var Slice = require( '@stdlib/slice/ctor' );
var MultiSlice = require( '@stdlib/slice/multi' );
var ndarray = require( '@stdlib/ndarray/ctor' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
var shape = [ 3, 2 ];
var strides = [ 2, 1 ];
var offset = 0;
var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
// returns
var sh = x.shape;
// returns [ 3, 2 ]
var arr = ndarray2array( x );
// returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
// 1. Using a MultiSlice:
var s0 = new Slice( 1, null, 1 );
var s1 = new Slice( null, null, 1 );
var s = new MultiSlice( s0, s1 );
// returns
var y = slice( x, s );
// returns
sh = y.shape;
// returns [ 2, 2 ]
arr = ndarray2array( y );
// returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
// 2. Using an array of slice arguments:
y = slice( x, [ s0, s1 ] );
// returns
sh = y.shape;
// returns [ 2, 2 ]
arr = ndarray2array( y );
// returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
// 3. Providing separate arguments:
y = slice( x, s0, s1 );
// returns
sh = y.shape;
// returns [ 2, 2 ]
arr = ndarray2array( y );
// returns [ [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
```
The function supports the following `options`:
- **strict**: boolean indicating whether to enforce strict bounds checking.
By default, the function throws an error when provided a slice which exceeds array bounds. To return an empty array when a slice exceeds array bounds, set the `strict` option to `false`.
```javascript
var Slice = require( '@stdlib/slice/ctor' );
var MultiSlice = require( '@stdlib/slice/multi' );
var ndarray = require( '@stdlib/ndarray/ctor' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
var shape = [ 3, 2 ];
var strides = [ 2, 1 ];
var offset = 0;
var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
// returns
var sh = x.shape;
// returns [ 3, 2 ]
var arr = ndarray2array( x );
// returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
var s0 = new Slice( 1, null, 1 );
var s1 = new Slice( 10, 20, 1 );
var s = new MultiSlice( s0, s1 );
// returns
var y = slice( x, s, {
'strict': false
});
// returns
sh = y.shape;
// returns [ 2, 0 ]
arr = ndarray2array( y );
// returns []
```
## Notes
- A **slice argument** must be either a [`Slice`][@stdlib/slice/ctor], an integer, `null`, or `undefined`.
- The number of slice dimensions must match the number of array dimensions. Hence, if `x` is a zero-dimensional [`ndarray`][@stdlib/ndarray/ctor], then, if `s` is a [`MultiSlice`][@stdlib/slice/multi], `s` should be empty, and, if `s` is an array, `s` should not contain any slice arguments. Similarly, if `x` is a one-dimensional [`ndarray`][@stdlib/ndarray/ctor], then, if `s` is a [`MultiSlice`][@stdlib/slice/multi], `s` should have one slice dimension, and, if `s` is an array, `s` should contain a single slice argument. And so on and so forth.
## Examples
```javascript
var S = require( '@stdlib/slice/ctor' );
var E = require( '@stdlib/slice/multi' );
var array = require( '@stdlib/ndarray/array' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var zeroTo = require( '@stdlib/array/base/zero-to' );
var slice = require( '@stdlib/ndarray/slice' );
// Alias `null` to allow for more compact indexing expressions:
var _ = null;
// Create a linear ndarray buffer:
var buf = zeroTo( 27 );
// Create an ndarray:
var x = array( buf, {
'shape': [ 3, 3, 3 ]
});
// Get each matrix...
var s1 = E( 0, _, _ );
var y1 = slice( x, s1 );
// returns
var a1 = ndarray2array( y1 );
// returns [ [ 0, 1, 2 ], [ 3, 4, 5 ], [ 6, 7, 8 ] ]
var s2 = E( 1, _, _ );
var y2 = slice( x, s2 );
// returns
var a2 = ndarray2array( y2 );
// returns [ [ 9, 10, 11 ], [ 12, 13, 14 ], [ 15, 16, 17 ] ]
var s3 = E( 2, _, _ );
var y3 = slice( x, s3 );
// returns
var a3 = ndarray2array( y3 );
// returns [ [ 18, 19, 20 ], [ 21, 22, 23 ], [ 24, 25, 26 ] ]
// Reverse all elements:
var s = S( _, _, -1 );
var s4 = E( s, s, s );
var y4 = slice( x, s4 );
// returns
var a4 = ndarray2array( y4 );
// returns [...]
// Get the second rows from each matrix:
var s5 = E( _, 1, _ );
var y5 = slice( x, s5 );
// returns
var a5 = ndarray2array( y5 );
// returns [ [ 3, 4, 5 ], [ 12, 13, 14 ], [ 21, 22, 23 ] ]
// Get the second columns from each matrix:
var s6 = E( _, _, 1 );
var y6 = slice( x, s6 );
// returns
var a6 = ndarray2array( y6 );
// returns [ [ 1, 4, 7 ], [ 10, 13, 16 ], [ 19, 22, 25 ] ]
// Use an alternative invocation style:
var y7 = slice( x, _, _, 1 );
// returns
var a7 = ndarray2array( y7 );
// returns [ [ 1, 4, 7 ], [ 10, 13, 16 ], [ 19, 22, 25 ] ]
// Use an alternative invocation style:
var y8 = slice( x, [ _, _, 1 ] );
// returns
var a8 = ndarray2array( y8 );
// returns [ [ 1, 4, 7 ], [ 10, 13, 16 ], [ 19, 22, 25 ] ]
```
[@stdlib/slice/ctor]: https://www.npmjs.com/package/@stdlib/slice-ctor
[@stdlib/slice/multi]: https://www.npmjs.com/package/@stdlib/slice-multi
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray/tree/main/ctor
[@stdlib/ndarray/array]: https://github.com/stdlib-js/ndarray/tree/main/array
[@stdlib/ndarray/at]: https://github.com/stdlib-js/ndarray/tree/main/at
[@stdlib/ndarray/slice-assign]: https://github.com/stdlib-js/ndarray/tree/main/slice-assign
[@stdlib/ndarray/slice-dimension]: https://github.com/stdlib-js/ndarray/tree/main/slice-dimension