Skip to content

Commit 6b34a7c

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 95a6343 commit 6b34a7c

File tree

11 files changed

+4044
-1
lines changed

11 files changed

+4044
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,13 @@
44
55
<section class="release" id="unreleased">
66

7-
## Unreleased (2025-12-17)
7+
## Unreleased (2025-12-19)
88

99
<section class="features">
1010

1111
### Features
1212

13+
- [`3feb022`](https://github.com/stdlib-js/stdlib/commit/3feb02271d5335920ebbd4ca0268f0a24340e168) - add `ndarray/flatten-from-by` [(#9040)](https://github.com/stdlib-js/stdlib/pull/9040)
1314
- [`d360fe5`](https://github.com/stdlib-js/stdlib/commit/d360fe525de98bfac66993c5c54b13fffccab822) - add `ndarray/base/to-reversed-dimension` [(#8852)](https://github.com/stdlib-js/stdlib/pull/8852)
1415
- [`f375981`](https://github.com/stdlib-js/stdlib/commit/f375981dd59f1ce6aa575e48bafa0e7998a7efdd) - add `ndarray/base/to-flippedud` [(#8849)](https://github.com/stdlib-js/stdlib/pull/8849)
1516
- [`1080085`](https://github.com/stdlib-js/stdlib/commit/1080085cbf97a2d217339594fda596759a49386b) - add `ndarray/base/to-flippedlr` [(#8848)](https://github.com/stdlib-js/stdlib/pull/8848)
@@ -651,6 +652,7 @@ A total of 37 issues were closed in this release:
651652

652653
<details>
653654

655+
- [`3feb022`](https://github.com/stdlib-js/stdlib/commit/3feb02271d5335920ebbd4ca0268f0a24340e168) - **feat:** add `ndarray/flatten-from-by` [(#9040)](https://github.com/stdlib-js/stdlib/pull/9040) _(by Muhammad Haris, Athan Reines)_
654656
- [`a21edb1`](https://github.com/stdlib-js/stdlib/commit/a21edb10488a1a40457575ca21f07257c1ef5369) - **chore:** fix C lint errors [(#9111)](https://github.com/stdlib-js/stdlib/pull/9111) _(by Geo Daoyu)_
655657
- [`d360fe5`](https://github.com/stdlib-js/stdlib/commit/d360fe525de98bfac66993c5c54b13fffccab822) - **feat:** add `ndarray/base/to-reversed-dimension` [(#8852)](https://github.com/stdlib-js/stdlib/pull/8852) _(by Muhammad Haris, Athan Reines)_
656658
- [`01ab290`](https://github.com/stdlib-js/stdlib/commit/01ab29036205f4a0507133c1a4a7fd429bb7bd9e) - **fix:** rename import in `ndarray/base/unary-strided1d-dispatch` to resolve conflict [(#9010)](https://github.com/stdlib-js/stdlib/pull/9010) _(by Muhammad Haris)_

‎flatten-from-by/README.md‎

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

0 commit comments

Comments
 (0)