Skip to content

Commit 3bf733b

Browse files
kgrytekgryte
committed
feat: add slice/base/seq2multislice 
1 parent 983270f commit 3bf733b

File tree

16 files changed

+1926
-0
lines changed

16 files changed

+1926
-0
lines changed

‎lib/node_modules/@stdlib/slice/base/seq2multislice/README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2023 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# seq2multislice
22+
23+
> Convert a multidimensional subsequence string to a [`MultiSlice`][@stdlib/slice/multi] object.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var seq2multislice = require( '@stdlib/slice/base/seq2multislice' );
41+
```
42+
43+
<a name="main"></a>
44+
45+
#### seq2multislice( str, shape, strict )
46+
47+
Converts a multidimensional subsequence string to a [`MultiSlice`][@stdlib/slice/multi] object, where `shape` specifies the maximum allowed slice shape.
48+
49+
```javascript
50+
var s = seq2multislice( ':5', [ 10 ], false );
51+
// returns <MultiSlice>
52+
53+
var s0 = s.data[ 0 ];
54+
// returns <Slice>
55+
56+
var v = s0.start;
57+
// returns 0
58+
59+
v = s0.stop;
60+
// returns 5
61+
62+
v = s0.step;
63+
// returns 1
64+
```
65+
66+
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
67+
68+
```text
69+
2
70+
:
71+
2:
72+
:10
73+
2:10
74+
::-1
75+
10:2:-1
76+
:2:
77+
2:10:
78+
2::2
79+
:10:2
80+
:, :, :
81+
1, 2, 3
82+
0:10, 1:20:2, ::-1
83+
...
84+
:, ..., 2
85+
```
86+
87+
are all valid multidimensional subsequence strings. The function returns an error object if provided an invalid subsequence string.
88+
89+
```javascript
90+
var s = seq2multislice( '1:2:3:4', [ 10 ], false );
91+
// returns { 'code': 'ERR_SLICE_INVALID_SUBSEQUENCE' }
92+
```
93+
94+
When `strict` is `true`, the function returns an error object if a subsequence string resolves to a slice exceeding index bounds.
95+
96+
```javascript
97+
var s = seq2multislice( '10:20', [ 10 ], true );
98+
// returns { 'code': 'ERR_SLICE_OUT_OF_BOUNDS' }
99+
```
100+
101+
A returned error object may have one of the following error codes:
102+
103+
- **ERR_SLICE_INVALID_SUBSEQUENCE**: a subsequence string is invalid.
104+
- **ERR_SLICE_INVALID_INCREMENT**: a subsequence string must have a non-zero increment.
105+
- **ERR_SLICE_OUT_OF_BOUNDS**: a subsequence string resolves to a slice exceeding index bounds.
106+
- **ERR_SLICE_TOO_MANY_DIMENSIONS**: a subsequence string has more dimensions than the provided shape.
107+
- **ERR_SLICE_INSUFFICIENT_DIMENSIONS**: a subsequence string has too few dimensions.
108+
- **ERR_SLICE_INVALID_ELLIPSIS**: a subsequence string must only contain at most one ellipsis.
109+
110+
</section>
111+
112+
<!-- /.usage -->
113+
114+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
115+
116+
<section class="notes">
117+
118+
## Notes
119+
120+
- Providing a single nonnegative integer `i` as a single-dimension index indexes the same elements as the subsequence `i:i+1`.
121+
- 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.
122+
- 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[':,:'])`).
123+
- 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']`).
124+
- 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.
125+
126+
</section>
127+
128+
<!-- /.notes -->
129+
130+
<!-- Package usage examples. -->
131+
132+
<section class="examples">
133+
134+
## Examples
135+
136+
<!-- eslint no-undef: "error" -->
137+
138+
```javascript
139+
var seq2multislice = require( '@stdlib/slice/base/seq2multislice' );
140+
141+
var s = seq2multislice( ':,:,:', [ 10, 10, 10 ], false );
142+
var d = s.data;
143+
// returns [ <Slice>, <Slice>, <Slice> ]
144+
145+
s = seq2multislice( '3,2:10,:', [ 10, 10, 10 ], false );
146+
d = s.data;
147+
// returns [ 3, <Slice>, <Slice> ]
148+
149+
s = seq2multislice( '2,2:,-5', [ 10, 10, 10 ], false );
150+
d = s.data;
151+
// returns [ 2, <Slice>, -5 ]
152+
153+
s = seq2multislice( '::-2,-1,...,:', [ 10, 10, 10, 10, 10, 10 ], false );
154+
d = s.data;
155+
// returns [ <Slice>, -1, <Slice>, <Slice>, <Slice>, <Slice> ]
156+
157+
s = seq2multislice( 'foo,bar', [ 10, 10 ], false );
158+
// returns { 'code': 'ERR_SLICE_INVALID_SUBSEQUENCE' }
159+
```
160+
161+
</section>
162+
163+
<!-- /.examples -->
164+
165+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
166+
167+
<section class="references">
168+
169+
</section>
170+
171+
<!-- /.references -->
172+
173+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
174+
175+
<section class="related">
176+
177+
</section>
178+
179+
<!-- /.related -->
180+
181+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
182+
183+
<section class="links">
184+
185+
[@stdlib/slice/multi]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/slice/multi
186+
187+
[@stdlib/slice/base/seq2slice]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/slice/base/seq2slice
188+
189+
</section>
190+
191+
<!-- /.links -->

0 commit comments

Comments
 (0)