Skip to content

Commit f6eb120

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 5ffe7bc commit f6eb120

File tree

11 files changed

+3529
-0
lines changed

11 files changed

+3529
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
### Features
1212

13+
- [`c8652f3`](https://github.com/stdlib-js/stdlib/commit/c8652f3a3ca317179b46596787eb4db4966c154a) - add `ndarray/flatten-by` [(#8078)](https://github.com/stdlib-js/stdlib/pull/8078)
1314
- [`24c59ca`](https://github.com/stdlib-js/stdlib/commit/24c59ca8f9c70b81c705f4cd981dfd4816c29137) - add `broadcastArrayExceptDimensions` to namespace
1415
- [`0afeede`](https://github.com/stdlib-js/stdlib/commit/0afeedeeaff3c0d7f394b79125d633454fa7f9e3) - add `unaryAddonDispatch` to namespace
1516
- [`8917ae2`](https://github.com/stdlib-js/stdlib/commit/8917ae2818c6864d62edc83cc5b74013d6dfc672) - add `nullaryStrided1dDispatch` to namespace
@@ -528,6 +529,7 @@ A total of 24 issues were closed in this release:
528529

529530
<details>
530531

532+
- [`c8652f3`](https://github.com/stdlib-js/stdlib/commit/c8652f3a3ca317179b46596787eb4db4966c154a) - **feat:** add `ndarray/flatten-by` [(#8078)](https://github.com/stdlib-js/stdlib/pull/8078) _(by Muhammad Haris, Athan Reines)_
531533
- [`57a9400`](https://github.com/stdlib-js/stdlib/commit/57a9400329d0570d2b25ad6b87d4d9a74d7fc28b) - **fix:** avoid strict equality check _(by Athan Reines)_
532534
- [`905019c`](https://github.com/stdlib-js/stdlib/commit/905019c024611308865950e3d1dd51c642176e82) - **docs:** fix grammar in function descriptions _(by Philipp Burckhardt)_
533535
- [`5dde2ff`](https://github.com/stdlib-js/stdlib/commit/5dde2ff115443aa143dd19022e5593e022401920) - **refactor:** use extended BLAS utility _(by Athan Reines)_

‎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/ndarray/tree/main/ctor
226+
227+
[@stdlib/ndarray/orders]: https://github.com/stdlib-js/ndarray/tree/main/orders
228+
229+
</section>
230+
231+
<!-- /.links -->

0 commit comments

Comments
 (0)