# seq2multislice
> Convert a multidimensional subsequence string to a [`MultiSlice`][@stdlib/slice/multi] object.
## Usage
```javascript
var seq2multislice = require( '@stdlib/slice/base/seq2multislice' );
```
#### seq2multislice( str, shape, strict )
Converts a multidimensional subsequence string to a [`MultiSlice`][@stdlib/slice/multi] object, where `shape` specifies the maximum allowed slice shape.
```javascript
var s = seq2multislice( ':5', [ 10 ], false );
// returns
var s0 = s.data[ 0 ];
// returns
var v = s0.start;
// returns 0
v = s0.stop;
// returns 5
v = s0.step;
// returns 1
```
A multidimensional subsequence string is a comma-separated list of single-dimension indexing expressions (i.e., integers and/or [subsequence strings][@stdlib/slice/base/seq2slice]). For example, the following
```text
2
:
2:
:10
2:10
::-1
10:2:-1
:2:
2:10:
2::2
:10:2
:, :, :
1, 2, 3
0:10, 1:20:2, ::-1
...
:, ..., 2
```
are all valid multidimensional subsequence strings. The function returns an error object if provided an invalid subsequence string.
```javascript
var s = seq2multislice( '1:2:3:4', [ 10 ], false );
// returns { 'code': 'ERR_SLICE_INVALID_SUBSEQUENCE' }
```
When `strict` is `true`, the function returns an error object if a subsequence string resolves to a slice exceeding index bounds.
```javascript
var s = seq2multislice( '10:20', [ 10 ], true );
// returns { 'code': 'ERR_SLICE_OUT_OF_BOUNDS' }
```
A returned error object may have one of the following error codes:
- **ERR_SLICE_INVALID_SUBSEQUENCE**: a subsequence string is invalid.
- **ERR_SLICE_INVALID_INCREMENT**: a subsequence string must have a non-zero increment.
- **ERR_SLICE_OUT_OF_BOUNDS**: a subsequence string resolves to a slice exceeding index bounds.
- **ERR_SLICE_TOO_MANY_DIMENSIONS**: a subsequence string has more dimensions than the provided shape.
- **ERR_SLICE_INSUFFICIENT_DIMENSIONS**: a subsequence string has too few dimensions.
- **ERR_SLICE_INVALID_ELLIPSIS**: a subsequence string must only contain at most one ellipsis.
## Notes
- Providing a single nonnegative integer `i` as a single-dimension index indexes the same elements as the subsequence `i:i+1`.
- Providing a single negative integer `i` as a single-dimension index indexes the same elements as the subsequence `n+i:n+i+i`, where `n` is the dimension size.
- While integers index the same elements as equivalent subsequences, providing an integer as a single-dimension index indicates to reduce the number of dimensions by one (e.g., if the provided shape corresponds to an array having rank `2`, then `rank(A)-1 == rank(A['0,:'])`). In contrast, providing a subsequence indicates to retain a respective dimension (e.g., if the provided shape corresponds to an array having rank `2`, then `rank(A) == rank(A[':,:'])`).
- A multidimensional subsequence string can only contain **one** ellipsis ('...') operator. An ellipsis indicates to apply `:` to each dimension necessary to index all dimensions (e.g., if `A` has rank `4`, `A['1:, ..., 2:5'] == A['1:, :, :, 2:5']`).
- Except in the case of providing a single ellipsis, the number of single-dimension indexing expressions must equal the number of dimensions in the input shape.
## Examples
```javascript
var seq2multislice = require( '@stdlib/slice/base/seq2multislice' );
var s = seq2multislice( ':,:,:', [ 10, 10, 10 ], false );
var d = s.data;
// returns [ , , ]
s = seq2multislice( '3,2:10,:', [ 10, 10, 10 ], false );
d = s.data;
// returns [ 3, , ]
s = seq2multislice( '2,2:,-5', [ 10, 10, 10 ], false );
d = s.data;
// returns [ 2, , -5 ]
s = seq2multislice( '::-2,-1,...,:', [ 10, 10, 10, 10, 10, 10 ], false );
d = s.data;
// returns [ , -1, , , , ]
s = seq2multislice( 'foo,bar', [ 10, 10 ], false );
// returns { 'code': 'ERR_SLICE_INVALID_SUBSEQUENCE' }
```
[@stdlib/slice/multi]: https://github.com/stdlib-js/slice/tree/main/multi
[@stdlib/slice/base/seq2slice]: https://github.com/stdlib-js/slice/tree/main/base/seq2slice