Skip to content

Commit c90e739

Browse files
kgrytekgryte
committed
feat: add ndarray/base/slice-assign 
1 parent 8d7dfdc commit c90e739

10 files changed

Lines changed: 4508 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/ndarray/base/slice-assign/README.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
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+
# sliceAssign
22+
23+
> Assign element values from a broadcasted input `ndarray` to corresponding elements in an output `ndarray` view.
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 sliceAssign = require( '@stdlib/ndarray/base/slice-assign' );
41+
```
42+
43+
#### slice( x, y, slice, strict )
44+
45+
Assigns element values from a broadcasted input `ndarray` to corresponding elements in an output `ndarray` view.
46+
47+
```javascript
48+
var Slice = require( '@stdlib/slice/ctor' );
49+
var MultiSlice = require( '@stdlib/slice/multi' );
50+
var ndarray = require( '@stdlib/ndarray/ctor' );
51+
var ndzeros = require( '@stdlib/ndarray/zeros' );
52+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
53+
54+
// Define an input array:
55+
var buffer = [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ];
56+
var shape = [ 3, 2 ];
57+
var strides = [ 2, 1 ];
58+
var offset = 0;
59+
60+
var x = ndarray( 'generic', buffer, shape, strides, offset, 'row-major' );
61+
// returns <ndarray>
62+
63+
var sh = x.shape;
64+
// returns [ 3, 2 ]
65+
66+
var arr = ndarray2array( x );
67+
// returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.0 ] ]
68+
69+
// Define an output array:
70+
var y = ndzeros( [ 2, 3, 2 ], {
71+
'dtype': x.dtype
72+
});
73+
74+
// Create a slice:
75+
var s0 = null;
76+
var s1 = new Slice( null, null, -1 );
77+
var s2 = new Slice( null, null, -1 );
78+
var s = new MultiSlice( s0, s1, s2 );
79+
// returns <MultiSlice>
80+
81+
// Perform assignment:
82+
var out = sliceAssign( x, y, s, false );
83+
// returns <ndarray>
84+
85+
var bool = ( out === y );
86+
// returns true
87+
88+
arr = ndarray2array( y );
89+
// returns [ [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ], [ [ 6.0, 5.0 ], [ 4.0, 3.0 ], [ 2.0, 1.0 ] ] ]
90+
```
91+
92+
The function accepts the following arguments:
93+
94+
- **x**: input `ndarray`.
95+
- **y**: output `ndarray`.
96+
- **slice**: a [`MultiSlice`][@stdlib/slice/multi] instance specifying the output `ndarray` view.
97+
- **strict**: boolean indicating whether to enforce strict bounds checking.
98+
99+
</section>
100+
101+
<!-- /.usage -->
102+
103+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
104+
105+
<section class="notes">
106+
107+
## Notes
108+
109+
- The input `ndarray` **must** be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes] with the output `ndarray` view.
110+
- The input `ndarray` must have a [data type][@stdlib/ndarray/dtypes] which can be [safely cast][@stdlib/ndarray/safe-casts] to the output `ndarray` data type. Floating-point data types (both real and complex) are allowed to downcast to a lower precision data type of the [same kind][@stdlib/ndarray/same-kind-casts] (e.g., element values from a `'float64'` input `ndarray` can be assigned to corresponding elements in a `'float32'` output `ndarray`).
111+
112+
</section>
113+
114+
<!-- /.notes -->
115+
116+
<!-- Package usage examples. -->
117+
118+
<section class="examples">
119+
120+
## Examples
121+
122+
<!-- eslint no-undef: "error" -->
123+
124+
<!-- eslint-disable new-cap -->
125+
126+
```javascript
127+
var E = require( '@stdlib/slice/multi' );
128+
var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
129+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
130+
var ndzeros = require( '@stdlib/ndarray/zeros' );
131+
var slice = require( '@stdlib/ndarray/base/slice' );
132+
var sliceAssign = require( '@stdlib/ndarray/base/slice-assign' );
133+
134+
// Alias `null` to allow for more compact indexing expressions:
135+
var _ = null;
136+
137+
// Create an output ndarray:
138+
var y = ndzeros( [ 3, 3, 3 ] );
139+
140+
// Update each matrix...
141+
var s1 = E( 0, _, _ );
142+
sliceAssign( scalar2ndarray( 100 ), y, s1, false );
143+
144+
var a1 = ndarray2array( slice( y, s1, false ) );
145+
// returns [ [ 100, 100, 100 ], [ 100, 100, 100 ], [ 100, 100, 100 ] ]
146+
147+
var s2 = E( 1, _, _ );
148+
sliceAssign( scalar2ndarray( 200 ), y, s2, false );
149+
150+
var a2 = ndarray2array( slice( y, s2, false ) );
151+
// returns [ [ 200, 200, 200 ], [ 200, 200, 200 ], [ 200, 200, 200 ] ]
152+
153+
var s3 = E( 2, _, _ );
154+
sliceAssign( scalar2ndarray( 300 ), y, s3, false );
155+
156+
var a3 = ndarray2array( slice( y, s3, false ) );
157+
// returns [ [ 300, 300, 300 ], [ 300, 300, 300 ], [ 300, 300, 300 ] ]
158+
159+
// Update the second rows in each matrix:
160+
var s4 = E( _, 1, _ );
161+
sliceAssign( scalar2ndarray( 400 ), y, s4, false );
162+
163+
var a4 = ndarray2array( slice( y, s4, false ) );
164+
// returns [ [ 400, 400, 400 ], [ 400, 400, 400 ], [ 400, 400, 400 ] ]
165+
166+
// Update the second columns in each matrix:
167+
var s5 = E( _, _, 1 );
168+
sliceAssign( scalar2ndarray( 500 ), y, s5, false );
169+
170+
var a5 = ndarray2array( slice( y, s5, false ) );
171+
// returns [ [ 500, 500, 500 ], [ 500, 500, 500 ], [ 500, 500, 500 ] ]
172+
173+
// Return the contents of the entire ndarray:
174+
var a6 = ndarray2array( y );
175+
/* returns
176+
[
177+
[
178+
[ 100, 500, 100 ],
179+
[ 400, 500, 400 ],
180+
[ 100, 500, 100 ]
181+
],
182+
[
183+
[ 200, 500, 200 ],
184+
[ 400, 500, 400 ],
185+
[ 200, 500, 200 ]
186+
],
187+
[
188+
[ 300, 500, 300 ],
189+
[ 400, 500, 400 ],
190+
[ 300, 500, 300 ]
191+
]
192+
]
193+
*/
194+
```
195+
196+
</section>
197+
198+
<!-- /.examples -->
199+
200+
<!-- 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. -->
201+
202+
<section class="references">
203+
204+
</section>
205+
206+
<!-- /.references -->
207+
208+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
209+
210+
<section class="related">
211+
212+
</section>
213+
214+
<!-- /.related -->
215+
216+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
217+
218+
<section class="links">
219+
220+
[@stdlib/slice/multi]: https://github.com/stdlib-js/stdlib
221+
222+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/stdlib
223+
224+
[@stdlib/ndarray/safe-casts]: https://github.com/stdlib-js/stdlib
225+
226+
[@stdlib/ndarray/same-kind-casts]: https://github.com/stdlib-js/stdlib
227+
228+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib
229+
230+
</section>
231+
232+
<!-- /.links -->

0 commit comments

Comments
 (0)