Skip to content

Commit 841d345

Browse files
kgrytekgryte
committed
feat: add support for assigning results to an output array
1 parent 3556beb commit 841d345

File tree

10 files changed

+965
-149
lines changed

10 files changed

+965
-149
lines changed

‎lib/node_modules/@stdlib/array/base/flatten4d/README.md

+21-1
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,26 @@ var out = flatten4d( x, [ 2, 1, 1, 2 ], true );
5050
// returns [ 1, 3, 2, 4 ]
5151
```
5252

53+
#### flatten4d.assign( x, shape, colexicographic, out, stride, offset )
54+
55+
Flattens a four-dimensional nested array and assigns elements to a provided output array.
56+
57+
```javascript
58+
var Float64Array = require( '@stdlib/array/float64' );
59+
60+
var x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
61+
var out = new Float64Array( 4 );
62+
63+
var y = flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, 0 );
64+
// returns <Float64Array>[ 1, 2, 3, 4 ]
65+
66+
var bool = ( y === out );
67+
// returns true
68+
69+
y = flatten4d.assign( x, [ 2, 1, 1, 2 ], true, out, 1, 0 );
70+
// returns <Float64Array>[ 1, 3, 2, 4 ]
71+
```
72+
5373
</section>
5474

5575
<!-- /.usage -->
@@ -58,7 +78,7 @@ var out = flatten4d( x, [ 2, 1, 1, 2 ], true );
5878

5979
## Notes
6080

61-
- The function assumes that all nested arrays have the same length (i.e., the input array is **not** a ragged array).
81+
- Both functions assume that all nested arrays have the same length (i.e., the input array is **not** a ragged array).
6282

6383
</section>
6484

‎lib/node_modules/@stdlib/array/base/flatten4d/benchmark/benchmark.js

+50
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,10 @@
2222

2323
var bench = require( '@stdlib/bench' );
2424
var isArray = require( '@stdlib/assert/is-array' );
25+
var isFloat64Array = require( '@stdlib/assert/is-float64array' );
2526
var zeroTo = require( '@stdlib/array/base/zero-to' );
2627
var filled = require( '@stdlib/array/base/filled' );
28+
var Float64Array = require( '@stdlib/array/float64' );
2729
var pkg = require( './../package.json' ).name;
2830
var flatten4d = require( './../lib' );
2931

@@ -73,3 +75,51 @@ bench( pkg+':size=144,colexicographic', function benchmark( b ) {
7375
b.pass( 'benchmark finished' );
7476
b.end();
7577
});
78+
79+
bench( pkg+'::assign:size=144,lexicographic', function benchmark( b ) {
80+
var out;
81+
var x;
82+
var i;
83+
var v;
84+
85+
out = new Float64Array( 144 );
86+
x = filled( filled( filled( zeroTo( 3 ), 4 ), 3 ), 4 );
87+
88+
b.tic();
89+
for ( i = 0; i < b.iterations; i++ ) {
90+
v = flatten4d.assign( x, [ 4, 3, 4, 3 ], false, out, 1, 0 );
91+
if ( typeof v !== 'object' ) {
92+
b.fail( 'should return a Float64Array' );
93+
}
94+
}
95+
b.toc();
96+
if ( !isFloat64Array( v ) ) {
97+
b.fail( 'should return a Float64Array' );
98+
}
99+
b.pass( 'benchmark finished' );
100+
b.end();
101+
});
102+
103+
bench( pkg+':assign:size=144,colexicographic', function benchmark( b ) {
104+
var out;
105+
var x;
106+
var i;
107+
var v;
108+
109+
out = new Float64Array( 144 );
110+
x = filled( filled( filled( zeroTo( 3 ), 4 ), 3 ), 4 );
111+
112+
b.tic();
113+
for ( i = 0; i < b.iterations; i++ ) {
114+
v = flatten4d.assign( x, [ 4, 3, 4, 3 ], true, out, 1, 0 );
115+
if ( typeof v !== 'object' ) {
116+
b.fail( 'should return a Float64Array' );
117+
}
118+
}
119+
b.toc();
120+
if ( !isFloat64Array( v ) ) {
121+
b.fail( 'should return a Float64Array' );
122+
}
123+
b.pass( 'benchmark finished' );
124+
b.end();
125+
});

‎lib/node_modules/@stdlib/array/base/flatten4d/docs/repl.txt

+46
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,52 @@
2929
> out = {{alias}}( x, [ 2, 1, 1, 2 ], true )
3030
[ 1, 3, 2, 4 ]
3131

32+
33+
{{alias}}.assign( x, shape, colexicographic, out, stride, offset )
34+
Flattens a four-dimensional nested array and assigns elements to a provided
35+
output array.
36+
37+
The function assumes that all nested arrays have the same length (i.e., the
38+
input array is *not* a ragged array).
39+
40+
Parameters
41+
----------
42+
x: Array
43+
Input array.
44+
45+
shape: Array<integer>
46+
Array shape.
47+
48+
colexicographic: boolean
49+
Specifies whether to flatten array values in colexicographic order.
50+
51+
out: Collection
52+
Output array.
53+
54+
stride: integer
55+
Output array stride.
56+
57+
offset: integer
58+
Output array index offset.
59+
60+
Returns
61+
-------
62+
out: Array
63+
Output array.
64+
65+
Examples
66+
--------
67+
> var x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
68+
> var out = [ 0, 0, 0, 0 ];
69+
> var v = {{alias}}.assign( x, [ 2, 1, 1, 2 ], false, out, 1, 0 )
70+
[ 1, 2, 3, 4 ]
71+
> var bool = ( v === out )
72+
true
73+
> out = [ 0, 0, 0, 0 ];
74+
> {{alias}}.assign( x, [ 2, 1, 1, 2 ], true, out, 1, 0 );
75+
> out
76+
[ 1, 3, 2, 4 ]
77+
3278
See Also
3379
--------
3480

‎lib/node_modules/@stdlib/array/base/flatten4d/docs/types/index.d.ts

+65-1
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,70 @@ import { Collection } from '@stdlib/types/object';
2727
*/
2828
type Array4D<T> = Array<Array<Array<Collection<T>>>>;
2929

30+
/**
31+
* Interface describing `flatten4d`.
32+
*/
33+
interface Flatten4d {
34+
/**
35+
* Flattens a four-dimensional nested array.
36+
*
37+
* ## Notes
38+
*
39+
* - The function assumes that all nested arrays have the same length (i.e., the input array is **not** a ragged array).
40+
*
41+
* @param x - input array
42+
* @param shape - array shape
43+
* @param colexicographic - specifies whether to flatten array values in colexicographic order
44+
* @returns flattened array
45+
*
46+
* @example
47+
* var x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
48+
*
49+
* var out = flatten4d( x, [ 2, 1, 1, 2 ], false );
50+
* // returns [ 1, 2, 3, 4 ]
51+
*
52+
* @example
53+
* var x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
54+
*
55+
* var out = flatten4d( x, [ 2, 1, 1, 2 ], true );
56+
* // returns [ 1, 3, 2, 4 ]
57+
*/
58+
<T = unknown>( x: Array4D<T>, shape: Collection<number>, colexicographic: boolean ): Array<T>;
59+
60+
/**
61+
* Flattens a four-dimensional nested array and assigns elements to a provided output array.
62+
*
63+
* ## Notes
64+
*
65+
* - The function assumes that all nested arrays have the same length (i.e., the input array is **not** a ragged array).
66+
*
67+
* @param x - input array
68+
* @param shape - array shape
69+
* @param colexicographic - specifies whether to flatten array values in colexicographic order
70+
* @param out - output array
71+
* @param stride - output array stride
72+
* @param offset - output array index offset
73+
* @returns output array
74+
*
75+
* @example
76+
* var Float64Array = require( `@stdlib/array/float64` );
77+
*
78+
* var x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
79+
*
80+
* var out = flatten4d.assign( x, [ 2, 2 ], false, new Float64Array( 4 ), 1, 0 );
81+
* // returns <Float64Array>[ 1, 2, 3, 4 ]
82+
*
83+
* @example
84+
* var Float64Array = require( `@stdlib/array/float64` );
85+
*
86+
* var x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
87+
*
88+
* var out = flatten4d.assign( x, [ 2, 2 ], true, new Float64Array( 4 ), 1, 0 );
89+
* // returns <Float64Array>[ 1, 3, 2, 4 ]
90+
*/
91+
assign<T = unknown, U = unknown>( x: Array4D<T>, shape: Collection<number>, colexicographic: boolean, out: Collection<U>, stride: number, offset: number ): Collection<T | U>;
92+
}
93+
3094
/**
3195
* Flattens a four-dimensional nested array.
3296
*
@@ -51,7 +115,7 @@ type Array4D<T> = Array<Array<Array<Collection<T>>>>;
51115
* var out = flatten4d( x, [ 2, 1, 1, 2 ], true );
52116
* // returns [ 1, 3, 2, 4 ]
53117
*/
54-
declare function flatten4d<T = unknown>( x: Array4D<T>, shape: Collection<number>, colexicographic: boolean ): Array<T>;
118+
declare var flatten4d: Flatten4d;
55119

56120

57121
// EXPORTS //

‎lib/node_modules/@stdlib/array/base/flatten4d/docs/types/test.ts

+116
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,119 @@ import flatten4d = require( './index' );
8282
flatten4d( x, [ 2, 1, 1, 2 ] ); // $ExpectError
8383
flatten4d( x, [ 2, 1, 1, 2 ], false, {} ); // $ExpectError
8484
}
85+
86+
// Attached to the main export is an `assign` method which returns a collection...
87+
{
88+
const x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
89+
90+
const out1 = [ 0, 0, 0, 0 ];
91+
92+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out1, 1, 0 ); // $ExpectType Collection<number>
93+
flatten4d.assign( x, [ 2, 1, 1, 2 ], true, out1, 1, 0 ); // $ExpectType Collection<number>
94+
95+
flatten4d.assign<number, number>( x, [ 2, 1, 1, 2 ], false, out1, 1, 0 ); // $ExpectType Collection<number>
96+
flatten4d.assign<number, number>( x, [ 2, 1, 1, 2 ], true, out1, 1, 0 ); // $ExpectType Collection<number>
97+
98+
const out2 = [ '', '', '', '' ];
99+
100+
flatten4d.assign<string, string>( [ [ [ [ '1', '2' ] ] ], [ [ [ '3', '4' ] ] ] ], [ 2, 1, 1, 2 ], false, out2, 1, 0 ); // $ExpectType Collection<string>
101+
flatten4d.assign<string, string>( [ [ [ [ '1', '2' ] ] ], [ [ [ '3', '4' ] ] ] ], [ 2, 1, 1, 2 ], true, out2, 1, 0 ); // $ExpectType Collection<string>
102+
}
103+
104+
// The compiler throws an error if the `assign` method is provided a first argument which is not an array-like object...
105+
{
106+
const out = [ 0, 0, 0, 0 ];
107+
108+
flatten4d.assign( 1, [ 2, 1, 1, 2 ], false, out, 1, 0 ); // $ExpectError
109+
flatten4d.assign( true, [ 2, 1, 1, 2 ], false, out, 1, 0 ); // $ExpectError
110+
flatten4d.assign( false, [ 2, 1, 1, 2 ], false, out, 1, 0 ); // $ExpectError
111+
flatten4d.assign( null, [ 2, 1, 1, 2 ], false, out, 1, 0 ); // $ExpectError
112+
flatten4d.assign( void 0, [ 2, 1, 1, 2 ], false, out, 1, 0 ); // $ExpectError
113+
flatten4d.assign( {}, [ 2, 1, 1, 2 ], false, out, 1, 0 ); // $ExpectError
114+
}
115+
116+
// The compiler throws an error if the `assign` method is provided a second argument which is not an array-like object containing numbers...
117+
{
118+
const x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
119+
const out = [ 0, 0, 0, 0 ];
120+
121+
flatten4d.assign( x, '', false, out, 1, 0 ); // $ExpectError
122+
flatten4d.assign( x, 1, false, out, 1, 0 ); // $ExpectError
123+
flatten4d.assign( x, true, false, out, 1, 0 ); // $ExpectError
124+
flatten4d.assign( x, false, false, out, 1, 0 ); // $ExpectError
125+
flatten4d.assign( x, null, false, out, 1, 0 ); // $ExpectError
126+
flatten4d.assign( x, void 0, false, out, 1, 0 ); // $ExpectError
127+
flatten4d.assign( x, {}, false, out, 1, 0 ); // $ExpectError
128+
flatten4d.assign( x, [ 1, '2', 3 ], false, out, 1, 0 ); // $ExpectError
129+
flatten4d.assign( x, ( x: number ): number => x, false, out, 1, 0 ); // $ExpectError
130+
}
131+
132+
// The compiler throws an error if the `assign` method is provided a third argument which is not a boolean...
133+
{
134+
const x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
135+
const out = [ 0, 0, 0, 0 ];
136+
137+
flatten4d.assign( x, [ 2, 1, 1, 2 ], '', out, 1, 0 ); // $ExpectError
138+
flatten4d.assign( x, [ 2, 1, 1, 2 ], 1, out, 1, 0 ); // $ExpectError
139+
flatten4d.assign( x, [ 2, 1, 1, 2 ], null, out, 1, 0 ); // $ExpectError
140+
flatten4d.assign( x, [ 2, 1, 1, 2 ], void 0, out, 1, 0 ); // $ExpectError
141+
flatten4d.assign( x, [ 2, 1, 1, 2 ], {}, out, 1, 0 ); // $ExpectError
142+
flatten4d.assign( x, [ 2, 1, 1, 2 ], [], out, 1, 0 ); // $ExpectError
143+
flatten4d.assign( x, [ 2, 1, 1, 2 ], ( x: number ): number => x, out, 1, 0 ); // $ExpectError
144+
}
145+
146+
// The compiler throws an error if the `assign` method is provided a fourth argument which is not an array-like object...
147+
{
148+
const x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
149+
150+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, 1, 1, 0 ); // $ExpectError
151+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, true, 1, 0 ); // $ExpectError
152+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, false, 1, 0 ); // $ExpectError
153+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, null, 1, 0 ); // $ExpectError
154+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, void 0, 1, 0 ); // $ExpectError
155+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, {}, 1, 0 ); // $ExpectError
156+
}
157+
158+
// The compiler throws an error if the `assign` method is provided a fifth argument which is not a number...
159+
{
160+
const x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
161+
const out = [ 0, 0, 0, 0 ];
162+
163+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, '1', 0 ); // $ExpectError
164+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, true, 0 ); // $ExpectError
165+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, false, 0 ); // $ExpectError
166+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, null, 0 ); // $ExpectError
167+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, void 0, 0 ); // $ExpectError
168+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, {}, 0 ); // $ExpectError
169+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, [], 0 ); // $ExpectError
170+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, ( x: number ): number => x, 0 ); // $ExpectError
171+
}
172+
173+
// The compiler throws an error if the `assign` method is provided a sixth argument which is not a number...
174+
{
175+
const x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
176+
const out = [ 0, 0, 0, 0 ];
177+
178+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, '1' ); // $ExpectError
179+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, true ); // $ExpectError
180+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, false ); // $ExpectError
181+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, null ); // $ExpectError
182+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, void 0 ); // $ExpectError
183+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, {} ); // $ExpectError
184+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, [] ); // $ExpectError
185+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, ( x: number ): number => x ); // $ExpectError
186+
}
187+
188+
// The compiler throws an error if the `assign` method is provided an unsupported number of arguments...
189+
{
190+
const x = [ [ [ [ 1, 2 ] ] ], [ [ [ 3, 4 ] ] ] ];
191+
const out = [ 0, 0, 0, 0 ];
192+
193+
flatten4d.assign(); // $ExpectError
194+
flatten4d.assign( x ); // $ExpectError
195+
flatten4d.assign( x, [ 2, 1, 1, 2 ] ); // $ExpectError
196+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false ); // $ExpectError
197+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out ); // $ExpectError
198+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1 ); // $ExpectError
199+
flatten4d.assign( x, [ 2, 1, 1, 2 ], false, out, 1, 0, {} ); // $ExpectError
200+
}

0 commit comments

Comments
 (0)