Skip to content

Commit 699c224

Browse files
kgrytekgryte
committed
Merge branch 'develop' of https://github.com/stdlib-js/stdlib into develop
2 parents 2743732 + c8652f3 commit 699c224

File tree

10 files changed

+3527
-0
lines changed

10 files changed

+3527
-0
lines changed

‎lib/node_modules/@stdlib/ndarray/flatten-by/README.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 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+
# flattenBy
22+
23+
> Flatten an [ndarray][@stdlib/ndarray/ctor] according to a callback function.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var flattenBy = require( '@stdlib/ndarray/flatten-by' );
37+
```
38+
39+
#### flattenBy( x\[, options], fcn\[, thisArg] )
40+
41+
Flattens an [ndarray][@stdlib/ndarray/ctor] according to a callback function.
42+
43+
```javascript
44+
var array = require( '@stdlib/ndarray/array' );
45+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
46+
47+
function scale( value ) {
48+
return value * 2.0;
49+
}
50+
51+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
52+
// returns <ndarray>
53+
54+
var y = flattenBy( x, scale );
55+
// returns <ndarray>
56+
57+
var arr = ndarray2array( y );
58+
// returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ]
59+
```
60+
61+
The function accepts the following arguments:
62+
63+
- **x**: input [ndarray][@stdlib/ndarray/ctor].
64+
- **options**: function options (_optional_).
65+
- **fcn**: callback function.
66+
- **thisArg**: callback execution context (_optional_).
67+
68+
The function accepts the following options:
69+
70+
- **order**: order in which input [ndarray][@stdlib/ndarray/ctor] elements should be flattened. Must be one of the following:
71+
72+
- `'row-major'`: flatten elements in lexicographic order. For example, given a two-dimensional input [ndarray][@stdlib/ndarray/ctor] (i.e., a matrix), flattening in lexicographic order means flattening the input [ndarray][@stdlib/ndarray/ctor] row-by-row.
73+
- `'column-major'`: flatten elements in colexicographic order. For example, given a two-dimensional input [ndarray][@stdlib/ndarray/ctor] (i.e., a matrix), flattening in colexicographic order means flattening the input [ndarray][@stdlib/ndarray/ctor] column-by-column.
74+
- `'any'`: flatten according to the physical layout of the input [ndarray][@stdlib/ndarray/ctor] data in memory, regardless of the stated [order][@stdlib/ndarray/orders] of the input [ndarray][@stdlib/ndarray/ctor].
75+
- `'same'`: flatten according to the stated [order][@stdlib/ndarray/orders] of the input [ndarray][@stdlib/ndarray/ctor].
76+
77+
Default: `'row-major'`.
78+
79+
- **depth**: maximum number of input [ndarray][@stdlib/ndarray/ctor] dimensions to flatten.
80+
81+
By default, the function flattens all dimensions of the input [ndarray][@stdlib/ndarray/ctor]. To flatten to a desired depth, specify the `depth` option.
82+
83+
```javascript
84+
var array = require( '@stdlib/ndarray/array' );
85+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
86+
87+
function scale( value ) {
88+
return value * 2.0;
89+
}
90+
91+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
92+
// returns <ndarray>
93+
94+
var opts = {
95+
'depth': 1
96+
};
97+
98+
var y = flattenBy( x, opts, scale );
99+
// returns <ndarray>
100+
101+
var arr = ndarray2array( y );
102+
// returns [ [ 2.0, 4.0 ], [ 6.0, 8.0 ], [ 10.0, 12.0 ] ]
103+
```
104+
105+
By default, the input [ndarray][@stdlib/ndarray/ctor] is flattened in lexicographic order. To flatten elements in a different order, specify the `order` option.
106+
107+
```javascript
108+
var array = require( '@stdlib/ndarray/array' );
109+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
110+
111+
function scale( value ) {
112+
return value * 2.0;
113+
}
114+
115+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
116+
// returns <ndarray>
117+
118+
var opts = {
119+
'order': 'column-major'
120+
};
121+
122+
var y = flattenBy( x, opts, scale );
123+
// returns <ndarray>
124+
125+
var arr = ndarray2array( y );
126+
// returns [ 2.0, 6.0, 10.0, 4.0, 8.0, 12.0 ]
127+
```
128+
129+
To set the callback function execution context, provide a `thisArg`.
130+
131+
<!-- eslint-disable no-invalid-this, max-len -->
132+
133+
```javascript
134+
var array = require( '@stdlib/ndarray/array' );
135+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
136+
137+
function scale( value ) {
138+
this.count += 1;
139+
return value * 2.0;
140+
}
141+
142+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
143+
// returns <ndarray>
144+
145+
var ctx = {
146+
'count': 0
147+
};
148+
149+
var y = flattenBy( x, scale, ctx );
150+
// returns <ndarray>
151+
152+
var arr = ndarray2array( y );
153+
// returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ]
154+
155+
var count = ctx.count;
156+
// returns 6
157+
```
158+
159+
</section>
160+
161+
<!-- /.usage -->
162+
163+
<section class="notes">
164+
165+
## Notes
166+
167+
- The function **always** returns a copy of input [ndarray][@stdlib/ndarray/ctor] data, even when an input [ndarray][@stdlib/ndarray/ctor] already has the desired number of dimensions.
168+
169+
- The callback function is provided the following arguments:
170+
171+
- **value**: current array element.
172+
- **indices**: current array element indices.
173+
- **arr**: the input [ndarray][@stdlib/ndarray/ctor].
174+
175+
- The order in which array elements are traversed and passed to a provided callback function is **not** guaranteed to match the order of array elements in an [ndarray][@stdlib/ndarray/ctor] view. Accordingly, a provided callback should avoid making assumptions regarding the order of provided elements.
176+
177+
</section>
178+
179+
<!-- /.notes -->
180+
181+
<section class="examples">
182+
183+
## Examples
184+
185+
<!-- eslint no-undef: "error" -->
186+
187+
```javascript
188+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
189+
var array = require( '@stdlib/ndarray/array' );
190+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
191+
var flattenBy = require( '@stdlib/ndarray/flatten-by' );
192+
193+
function scale( value ) {
194+
return value * 2.0;
195+
}
196+
197+
var xbuf = discreteUniform( 12, -100, 100, {
198+
'dtype': 'generic'
199+
});
200+
201+
var x = array( xbuf, {
202+
'shape': [ 2, 2, 3 ],
203+
'dtype': 'generic'
204+
});
205+
console.log( ndarray2array( x ) );
206+
207+
var y = flattenBy( x, scale );
208+
console.log( ndarray2array( y ) );
209+
```
210+
211+
</section>
212+
213+
<!-- /.examples -->
214+
215+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
216+
217+
<section class="related">
218+
219+
</section>
220+
221+
<!-- /.related -->
222+
223+
<section class="links">
224+
225+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
226+
227+
[@stdlib/ndarray/orders]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/orders
228+
229+
</section>
230+
231+
<!-- /.links -->

0 commit comments

Comments
 (0)