Skip to content

Commit 9d84704

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/flatten-from
PR-URL: #8153 Ref: #2656 Closes: stdlib-js/metr-issue-tracker#90 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com>
1 parent 06be0fa commit 9d84704

File tree

10 files changed

+2966
-0
lines changed

10 files changed

+2966
-0
lines changed

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

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
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+
# flattenFrom
22+
23+
> Return a copy of an input [ndarray][@stdlib/ndarray/ctor] where all dimensions of the input [ndarray][@stdlib/ndarray/ctor] are flattened 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 flattenFrom = require( '@stdlib/ndarray/flatten-from' );
37+
```
38+
39+
#### flattenFrom( x, dim\[, options] )
40+
41+
Returns a copy of an input [ndarray][@stdlib/ndarray/ctor] where all dimensions of the input [ndarray][@stdlib/ndarray/ctor] are flattened starting from a specified dimension.
42+
43+
```javascript
44+
var array = require( '@stdlib/ndarray/array' );
45+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
46+
47+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
48+
// returns <ndarray>
49+
50+
var y = flattenFrom( x, 1 );
51+
// returns <ndarray>
52+
53+
var arr = ndarray2array( y );
54+
// returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ], [ 5.0, 6.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+
63+
The function accepts the following options:
64+
65+
- **order**: order in which input [ndarray][@stdlib/ndarray/ctor] elements should be flattened. Must be one of the following:
66+
67+
- `'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.
68+
- `'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.
69+
- `'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].
70+
- `'same'`: flatten according to the stated [order][@stdlib/ndarray/orders] of the input [ndarray][@stdlib/ndarray/ctor].
71+
72+
Default: `'row-major'`.
73+
74+
- **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].
75+
76+
By default, the input [ndarray][@stdlib/ndarray/ctor] is flattened in lexicographic order. To flatten elements in a different order, specify the `order` option.
77+
78+
```javascript
79+
var array = require( '@stdlib/ndarray/array' );
80+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
81+
82+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
83+
// returns <ndarray>
84+
85+
var y = flattenFrom( x, 0, {
86+
'order': 'column-major'
87+
});
88+
// returns <ndarray>
89+
90+
var arr = ndarray2array( y );
91+
// returns [ 1.0, 3.0, 5.0, 2.0, 4.0, 6.0 ]
92+
```
93+
94+
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.
95+
96+
```javascript
97+
var array = require( '@stdlib/ndarray/array' );
98+
var dtype = require( '@stdlib/ndarray/dtype' );
99+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
100+
101+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] );
102+
// returns <ndarray>
103+
104+
var y = flattenFrom( x, 0, {
105+
'dtype': 'float32'
106+
});
107+
// returns <ndarray>
108+
109+
var dt = dtype( y );
110+
// returns 'float32'
111+
112+
var arr = ndarray2array( y );
113+
// returns [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]
114+
```
115+
116+
</section>
117+
118+
<!-- /.usage -->
119+
120+
<section class="notes">
121+
122+
## Notes
123+
124+
- 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.
125+
126+
</section>
127+
128+
<!-- /.notes -->
129+
130+
<section class="examples">
131+
132+
## Examples
133+
134+
<!-- eslint no-undef: "error" -->
135+
136+
```javascript
137+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
138+
var array = require( '@stdlib/ndarray/array' );
139+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
140+
var flattenFrom = require( '@stdlib/ndarray/flatten-from' );
141+
142+
var xbuf = discreteUniform( 12, -100, 100, {
143+
'dtype': 'generic'
144+
});
145+
146+
var x = array( xbuf, {
147+
'shape': [ 2, 2, 3 ],
148+
'dtype': 'generic'
149+
});
150+
console.log( ndarray2array( x ) );
151+
152+
var y = flattenFrom( x, 1 );
153+
console.log( ndarray2array( y ) );
154+
```
155+
156+
</section>
157+
158+
<!-- /.examples -->
159+
160+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
161+
162+
<section class="related">
163+
164+
</section>
165+
166+
<!-- /.related -->
167+
168+
<section class="links">
169+
170+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
171+
172+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes
173+
174+
[@stdlib/ndarray/orders]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/orders
175+
176+
<!-- <related-links> -->
177+
178+
<!-- </related-links> -->
179+
180+
</section>
181+
182+
<!-- /.links -->

0 commit comments

Comments
 (0)