Skip to content

Commit a7cbc8d

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat!: move optional argument to options object in ndarray/concat
This commit moves an optional `dim` argument to an options object. The motivation for doing this is to allow future API expansion with additional options (e.g., a `dtype` option to specify the output value dtype, etc). BREAKING CHANGE: move `dim` argument to options object To migrate, users should replace any usage of an optional `dim` argument with an options object with a `dim` property (e.g., `{'dim': -1}`). PR-URL: #9480 Closes: stdlib-js/metr-issue-tracker#144 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com>
1 parent 88af63a commit a7cbc8d

File tree

13 files changed

+618
-267
lines changed

13 files changed

+618
-267
lines changed

‎lib/node_modules/@stdlib/ndarray/concat/README.md‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -40,58 +40,62 @@ limitations under the License.
4040
var concat = require( '@stdlib/ndarray/concat' );
4141
```
4242

43-
#### concat( arrays\[, dim] )
43+
#### concat( arrays\[, options] )
4444

4545
Concatenates a list of [ndarrays][@stdlib/ndarray/ctor] along a specified [ndarray][@stdlib/ndarray/ctor] dimension.
4646

4747
```javascript
4848
var array = require( '@stdlib/ndarray/array' );
49-
var ndarray2array = require( '@stdlib/ndarray/to-array' );
5049

5150
var x = array( [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ] );
5251
var y = array( [ [ -5.0, 6.0, -7.0 ], [ 8.0, -9.0, 10.0 ] ] );
5352

54-
var out = concat( [ x, y ], -1 );
55-
// returns <ndarray>
56-
57-
var arr = ndarray2array( out );
58-
// returns [ [ -1.0, 2.0, -5.0, 6.0, -7.0 ], [ -3.0, 4.0, 8.0, -9.0, 10.0 ] ]
53+
var out = concat( [ x, y ], {
54+
'dim': -1
55+
});
56+
// returns <ndarray>[ [ -1.0, 2.0, -5.0, 6.0, -7.0 ], [ -3.0, 4.0, 8.0, -9.0, 10.0 ] ]
5957
```
6058

6159
The function accepts the following arguments:
6260

6361
- **arrays**: a list of input [ndarrays][@stdlib/ndarray/ctor]. Must be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes] except for the dimension along which to concatenate. The data type of the output [ndarray][@stdlib/ndarray/ctor] is determined by applying [type promotion rules][@stdlib/ndarray/promotion-rules] to the list of input [ndarrays][@stdlib/ndarray/ctor]. If provided [ndarrays][@stdlib/ndarray/ctor] having different [memory layouts][@stdlib/ndarray/orders], the output [ndarray][@stdlib/ndarray/ctor] has the [default order][@stdlib/ndarray/defaults].
64-
- **dim**: dimension along which to concatenate input [ndarrays][@stdlib/ndarray/ctor] (_optional_). Must be a negative integer. The index of the dimension along which to concatenate is resolved relative to the last dimension, with the last dimension corresponding to the value `-1`. Default: `-1`.
62+
- **options**: function options (_optional_).
63+
64+
The function accepts the following `options`:
65+
66+
- **dim**: dimension along which to concatenate input [ndarrays][@stdlib/ndarray/ctor]. Must be a negative integer. The index of the dimension along which to concatenate is resolved relative to the last dimension, with the last dimension corresponding to the value `-1`. Default: `-1`.
6567

66-
#### concat.assign( arrays, out\[, dim] )
68+
#### concat.assign( arrays, out\[, options] )
6769

6870
Concatenates a list of ndarrays along a specified ndarray dimension and assigns results to an output ndarray.
6971

7072
```javascript
7173
var array = require( '@stdlib/ndarray/array' );
7274
var zeros = require( '@stdlib/ndarray/zeros' );
73-
var ndarray2array = require( '@stdlib/ndarray/to-array' );
7475

7576
var x = array( [ [ -1.0, 2.0 ], [ -3.0, 4.0 ] ] );
7677
var y = array( [ [ -5.0, 6.0, -7.0 ], [ 8.0, -9.0, 10.0 ] ] );
7778

7879
var z = zeros( [ 2, 5 ] );
7980

80-
var out = concat.assign( [ x, y ], z, -1 );
81-
// returns <ndarray>
81+
var out = concat.assign( [ x, y ], z, {
82+
'dim': -1
83+
});
84+
// returns <ndarray>[ [ -1.0, 2.0, -5.0, 6.0, -7.0 ], [ -3.0, 4.0, 8.0, -9.0, 10.0 ] ]
8285

8386
var bool = ( out === z );
8487
// returns true
85-
86-
var arr = ndarray2array( z );
87-
// returns [ [ -1.0, 2.0, -5.0, 6.0, -7.0 ], [ -3.0, 4.0, 8.0, -9.0, 10.0 ] ]
8888
```
8989

9090
The function accepts the following arguments:
9191

9292
- **arrays**: a list of input [ndarrays][@stdlib/ndarray/ctor]. Must be [broadcast compatible][@stdlib/ndarray/base/broadcast-shapes] except for the dimension along which to concatenate. Must [promote][@stdlib/ndarray/promotion-rules] to a [data type][@stdlib/ndarray/dtypes] which can be (mostly) [safely cast][@stdlib/ndarray/mostly-safe-casts] to the [data type][@stdlib/ndarray/dtypes] of the output [ndarray][@stdlib/ndarray/ctor].
9393
- **out**: output [ndarray][@stdlib/ndarray/ctor].
94-
- **dim**: dimension along which to concatenate input [ndarrays][@stdlib/ndarray/ctor] (_optional_). Must be a negative integer. The index of the dimension along which to concatenate is resolved relative to the last dimension, with the last dimension corresponding to the value `-1`. Default: `-1`.
94+
- **options**: function options (_optional_).
95+
96+
The function accepts the following `options`:
97+
98+
- **dim**: dimension along which to concatenate input [ndarrays][@stdlib/ndarray/ctor]. Must be a negative integer. The index of the dimension along which to concatenate is resolved relative to the last dimension, with the last dimension corresponding to the value `-1`. Default: `-1`.
9599

96100
</section>
97101

@@ -129,7 +133,7 @@ var ybuf = discreteUniform( 8, 0, 10, {
129133
var y = new ndarray( 'generic', ybuf, [ 2, 4 ], [ 4, 1 ], 0, 'row-major' );
130134
console.log( ndarray2array( y ) );
131135

132-
var out = concat( [ x, y ], -1 );
136+
var out = concat( [ x, y ] );
133137
console.log( ndarray2array( out ) );
134138
```
135139

‎lib/node_modules/@stdlib/ndarray/concat/benchmark/benchmark.assign.js‎

Lines changed: 56 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,14 @@
2323
var bench = require( '@stdlib/bench' );
2424
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
2525
var zeros = require( '@stdlib/ndarray/zeros' );
26+
var format = require( '@stdlib/string/format' );
2627
var pkg = require( './../package.json' ).name;
2728
var concat = require( './../lib/assign.js' );
2829

2930

3031
// MAIN //
3132

32-
bench( pkg+'::1d', function benchmark( b ) {
33+
bench( format( '%s::1d', pkg ), function benchmark( b ) {
3334
var values;
3435
var opts;
3536
var out;
@@ -50,7 +51,7 @@ bench( pkg+'::1d', function benchmark( b ) {
5051

5152
b.tic();
5253
for ( i = 0; i < b.iterations; i++ ) {
53-
v = concat( values, out, -1 );
54+
v = concat( values, out );
5455
if ( typeof v !== 'object' ) {
5556
b.fail( 'should return an ndarray' );
5657
}
@@ -63,27 +64,27 @@ bench( pkg+'::1d', function benchmark( b ) {
6364
b.end();
6465
});
6566

66-
bench( pkg+'::1d,casting', function benchmark( b ) {
67+
bench( format( '%s::1d,casting', pkg ), function benchmark( b ) {
6768
var values;
6869
var out;
6970
var v;
7071
var i;
7172

72-
/* eslint-disable object-curly-newline */
73+
/* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */
7374

7475
values = [
75-
zeros( [ 32 ], { 'dtype': 'float64' }),
76-
zeros( [ 32 ], { 'dtype': 'float32' }),
77-
zeros( [ 32 ], { 'dtype': 'int32' }),
78-
zeros( [ 32 ], { 'dtype': 'generic' })
76+
zeros( [ 32 ], { 'dtype': 'float64' } ),
77+
zeros( [ 32 ], { 'dtype': 'float32' } ),
78+
zeros( [ 32 ], { 'dtype': 'int32' } ),
79+
zeros( [ 32 ], { 'dtype': 'generic' } )
7980
];
80-
out = zeros( [ 128 ], { 'dtype': 'generic' });
81+
out = zeros( [ 128 ], { 'dtype': 'generic' } );
8182

82-
/* eslint-enable object-curly-newline */
83+
/* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */
8384

8485
b.tic();
8586
for ( i = 0; i < b.iterations; i++ ) {
86-
v = concat( values, out, -1 );
87+
v = concat( values, out );
8788
if ( typeof v !== 'object' ) {
8889
b.fail( 'should return an ndarray' );
8990
}
@@ -96,7 +97,7 @@ bench( pkg+'::1d,casting', function benchmark( b ) {
9697
b.end();
9798
});
9899

99-
bench( pkg+'::2d', function benchmark( b ) {
100+
bench( format( '%s::2d', pkg ), function benchmark( b ) {
100101
var values;
101102
var opts;
102103
var out;
@@ -117,7 +118,7 @@ bench( pkg+'::2d', function benchmark( b ) {
117118

118119
b.tic();
119120
for ( i = 0; i < b.iterations; i++ ) {
120-
v = concat( values, out, -1 );
121+
v = concat( values, out );
121122
if ( typeof v !== 'object' ) {
122123
b.fail( 'should return an ndarray' );
123124
}
@@ -130,27 +131,27 @@ bench( pkg+'::2d', function benchmark( b ) {
130131
b.end();
131132
});
132133

133-
bench( pkg+'::2d,casting', function benchmark( b ) {
134+
bench( format( '%s::2d,casting', pkg ), function benchmark( b ) {
134135
var values;
135136
var out;
136137
var v;
137138
var i;
138139

139-
/* eslint-disable object-curly-newline */
140+
/* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */
140141

141142
values = [
142-
zeros( [ 2, 16 ], { 'dtype': 'float64' }),
143-
zeros( [ 2, 16 ], { 'dtype': 'float32' }),
144-
zeros( [ 2, 16 ], { 'dtype': 'int32' }),
145-
zeros( [ 2, 16 ], { 'dtype': 'generic' })
143+
zeros( [ 2, 16 ], { 'dtype': 'float64' } ),
144+
zeros( [ 2, 16 ], { 'dtype': 'float32' } ),
145+
zeros( [ 2, 16 ], { 'dtype': 'int32' } ),
146+
zeros( [ 2, 16 ], { 'dtype': 'generic' } )
146147
];
147-
out = zeros( [ 2, 64 ], { 'dtype': 'generic' });
148+
out = zeros( [ 2, 64 ], { 'dtype': 'generic' } );
148149

149-
/* eslint-enable object-curly-newline */
150+
/* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */
150151

151152
b.tic();
152153
for ( i = 0; i < b.iterations; i++ ) {
153-
v = concat( values, out, -1 );
154+
v = concat( values, out );
154155
if ( typeof v !== 'object' ) {
155156
b.fail( 'should return an ndarray' );
156157
}
@@ -163,7 +164,7 @@ bench( pkg+'::2d,casting', function benchmark( b ) {
163164
b.end();
164165
});
165166

166-
bench( pkg+'::3d', function benchmark( b ) {
167+
bench( format( '%s::3d', pkg ), function benchmark( b ) {
167168
var values;
168169
var opts;
169170
var out;
@@ -184,7 +185,7 @@ bench( pkg+'::3d', function benchmark( b ) {
184185

185186
b.tic();
186187
for ( i = 0; i < b.iterations; i++ ) {
187-
v = concat( values, out, -1 );
188+
v = concat( values, out );
188189
if ( typeof v !== 'object' ) {
189190
b.fail( 'should return an ndarray' );
190191
}
@@ -197,27 +198,27 @@ bench( pkg+'::3d', function benchmark( b ) {
197198
b.end();
198199
});
199200

200-
bench( pkg+'::3d,casting', function benchmark( b ) {
201+
bench( format( '%s::3d,casting', pkg ), function benchmark( b ) {
201202
var values;
202203
var out;
203204
var v;
204205
var i;
205206

206-
/* eslint-disable object-curly-newline */
207+
/* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */
207208

208209
values = [
209-
zeros( [ 2, 2, 8 ], { 'dtype': 'float64' }),
210-
zeros( [ 2, 2, 8 ], { 'dtype': 'float32' }),
211-
zeros( [ 2, 2, 8 ], { 'dtype': 'int32' }),
212-
zeros( [ 2, 2, 8 ], { 'dtype': 'generic' })
210+
zeros( [ 2, 2, 8 ], { 'dtype': 'float64' } ),
211+
zeros( [ 2, 2, 8 ], { 'dtype': 'float32' } ),
212+
zeros( [ 2, 2, 8 ], { 'dtype': 'int32' } ),
213+
zeros( [ 2, 2, 8 ], { 'dtype': 'generic' } )
213214
];
214-
out = zeros( [ 2, 2, 32 ], { 'dtype': 'generic' });
215+
out = zeros( [ 2, 2, 32 ], { 'dtype': 'generic' } );
215216

216-
/* eslint-enable object-curly-newline */
217+
/* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */
217218

218219
b.tic();
219220
for ( i = 0; i < b.iterations; i++ ) {
220-
v = concat( values, out, -1 );
221+
v = concat( values, out );
221222
if ( typeof v !== 'object' ) {
222223
b.fail( 'should return an ndarray' );
223224
}
@@ -230,7 +231,7 @@ bench( pkg+'::3d,casting', function benchmark( b ) {
230231
b.end();
231232
});
232233

233-
bench( pkg+'::4d', function benchmark( b ) {
234+
bench( format( '%s::4d', pkg ), function benchmark( b ) {
234235
var values;
235236
var opts;
236237
var out;
@@ -251,7 +252,7 @@ bench( pkg+'::4d', function benchmark( b ) {
251252

252253
b.tic();
253254
for ( i = 0; i < b.iterations; i++ ) {
254-
v = concat( values, out, -1 );
255+
v = concat( values, out );
255256
if ( typeof v !== 'object' ) {
256257
b.fail( 'should return an ndarray' );
257258
}
@@ -264,27 +265,27 @@ bench( pkg+'::4d', function benchmark( b ) {
264265
b.end();
265266
});
266267

267-
bench( pkg+'::4d,casting', function benchmark( b ) {
268+
bench( format( '%s::4d,casting', pkg ), function benchmark( b ) {
268269
var values;
269270
var out;
270271
var v;
271272
var i;
272273

273-
/* eslint-disable object-curly-newline */
274+
/* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */
274275

275276
values = [
276-
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'float64' }),
277-
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'float32' }),
278-
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'int32' }),
279-
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'generic' })
277+
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'float64' } ),
278+
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'float32' } ),
279+
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'int32' } ),
280+
zeros( [ 2, 2, 2, 4 ], { 'dtype': 'generic' } )
280281
];
281-
out = zeros( [ 2, 2, 2, 16 ], { 'dtype': 'generic' });
282+
out = zeros( [ 2, 2, 2, 16 ], { 'dtype': 'generic' } );
282283

283-
/* eslint-enable object-curly-newline */
284+
/* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */
284285

285286
b.tic();
286287
for ( i = 0; i < b.iterations; i++ ) {
287-
v = concat( values, out, -1 );
288+
v = concat( values, out );
288289
if ( typeof v !== 'object' ) {
289290
b.fail( 'should return an ndarray' );
290291
}
@@ -297,7 +298,7 @@ bench( pkg+'::4d,casting', function benchmark( b ) {
297298
b.end();
298299
});
299300

300-
bench( pkg+'::5d', function benchmark( b ) {
301+
bench( format( '%s::5d', pkg ), function benchmark( b ) {
301302
var values;
302303
var opts;
303304
var out;
@@ -318,7 +319,7 @@ bench( pkg+'::5d', function benchmark( b ) {
318319

319320
b.tic();
320321
for ( i = 0; i < b.iterations; i++ ) {
321-
v = concat( values, out, -1 );
322+
v = concat( values, out );
322323
if ( typeof v !== 'object' ) {
323324
b.fail( 'should return an ndarray' );
324325
}
@@ -331,27 +332,27 @@ bench( pkg+'::5d', function benchmark( b ) {
331332
b.end();
332333
});
333334

334-
bench( pkg+'::5d,casting', function benchmark( b ) {
335+
bench( format( '%s::5d,casting', pkg ), function benchmark( b ) {
335336
var values;
336337
var out;
337338
var v;
338339
var i;
339340

340-
/* eslint-disable object-curly-newline */
341+
/* eslint-disable object-curly-newline, stdlib/line-closing-bracket-spacing */
341342

342343
values = [
343-
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'float64' }),
344-
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'float32' }),
345-
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'int32' }),
346-
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'generic' })
344+
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'float64' } ),
345+
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'float32' } ),
346+
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'int32' } ),
347+
zeros( [ 2, 2, 2, 2, 2 ], { 'dtype': 'generic' } )
347348
];
348-
out = zeros( [ 2, 2, 2, 2, 8 ], { 'dtype': 'generic' });
349+
out = zeros( [ 2, 2, 2, 2, 8 ], { 'dtype': 'generic' } );
349350

350-
/* eslint-enable object-curly-newline */
351+
/* eslint-enable object-curly-newline, stdlib/line-closing-bracket-spacing */
351352

352353
b.tic();
353354
for ( i = 0; i < b.iterations; i++ ) {
354-
v = concat( values, out, -1 );
355+
v = concat( values, out );
355356
if ( typeof v !== 'object' ) {
356357
b.fail( 'should return an ndarray' );
357358
}

0 commit comments

Comments
 (0)