Skip to content

Commit 53caca8

Browse files
headlessNodekgryte
headlessNode
and
kgryte
authored
feat: add ndarray/base/atleastnd
PR-URL: #10422 Closes: stdlib-js/metr-issue-tracker#165 Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com>
1 parent 177c9b9 commit 53caca8

File tree

10 files changed

+777
-0
lines changed

10 files changed

+777
-0
lines changed

‎lib/node_modules/@stdlib/ndarray/base/atleastnd/README.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2026 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+
# atleastnd
22+
23+
> Convert a list of values (scalars and/or ndarrays) to ndarrays having at least a specified number of dimensions.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var atleastnd = require( '@stdlib/ndarray/base/atleastnd' );
37+
```
38+
39+
#### atleastnd( ndims, arrays )
40+
41+
Converts a list of values (scalars and/or ndarrays) to ndarrays having at least a specified number of dimensions.
42+
43+
```javascript
44+
var array = require( '@stdlib/ndarray/array' );
45+
46+
var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] );
47+
// returns <ndarray>[ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ]
48+
49+
var y = array( [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] );
50+
// returns <ndarray>[ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ]
51+
52+
var out = atleastnd( 3, [ x, y ] );
53+
// returns [ <ndarray>, <ndarray> ]
54+
```
55+
56+
The function accepts the following arguments:
57+
58+
- **ndims**: minimum number of dimensions.
59+
- **arrays**: array-like object containing a list of scalars and/or ndarrays.
60+
61+
</section>
62+
63+
<!-- /.usage -->
64+
65+
<section class="notes">
66+
67+
## Notes
68+
69+
- If a provided ndarray has fewer dimensions than `ndims`, the returned ndarray is a view on the input ndarray data buffer. The view is typically **not** contiguous. As more than one element of a returned view may refer to the same memory location, writing to the view may affect multiple elements. If you need to write to the returned ndarray, copy the ndarray **before** performing operations which may mutate elements.
70+
71+
- The returned ndarray is a "base" [ndarray][@stdlib/ndarray/base/ctor], and, thus, the returned [ndarray][@stdlib/ndarray/base/ctor] does not perform bounds checking or afford any of the guarantees of the non-base [ndarray][@stdlib/ndarray/ctor] constructor. The primary intent of this function is to broadcast an ndarray-like object within internal implementations and to do so with minimal overhead.
72+
73+
- If provided a scalar value (i.e., a non-ndarray) and that value
74+
75+
- is a number, the returned ndarray will have the [default][@stdlib/ndarray/defaults] real-valued floating-point data type.
76+
- is a boolean, the returned ndarray will have the [default][@stdlib/ndarray/defaults] boolean data type.
77+
- is a complex number object of a known data type, the data type of the returned ndarray will be the same as the provided value.
78+
- is a complex number object of an unknown data type, the returned ndarray will have the [default][@stdlib/ndarray/defaults] complex-valued floating-point data type.
79+
- is any other value type, the returned ndarray will have a `'generic'` data type.
80+
81+
</section>
82+
83+
<!-- /.notes -->
84+
85+
<section class="examples">
86+
87+
## Examples
88+
89+
<!-- eslint no-undef: "error" -->
90+
91+
```javascript
92+
var discreteUniform = require( '@stdlib/random/discrete-uniform' );
93+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
94+
var atleastnd = require( '@stdlib/ndarray/base/atleastnd' );
95+
96+
var x = discreteUniform( [ 2, 2, 2 ], -100, 100 );
97+
// returns <ndarray>
98+
99+
var y = discreteUniform( [ 5, 2 ], -100, 100 );
100+
// returns <ndarray>
101+
102+
var out = atleastnd( 3, [ x, y ] );
103+
// returns [ <ndarray>, <ndarray> ]
104+
105+
console.log( ndarray2array( out[ 0 ] ) );
106+
console.log( ndarray2array( out[ 1 ] ) );
107+
```
108+
109+
</section>
110+
111+
<!-- /.examples -->
112+
113+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
114+
115+
<section class="related">
116+
117+
</section>
118+
119+
<!-- /.related -->
120+
121+
<section class="links">
122+
123+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor
124+
125+
[@stdlib/ndarray/base/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/ctor
126+
127+
[@stdlib/ndarray/defaults]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/defaults
128+
129+
</section>
130+
131+
<!-- /.links -->

‎lib/node_modules/@stdlib/ndarray/base/atleastnd/benchmark/benchmark.js‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var Float64Array = require( '@stdlib/array/float64' );
25+
var ndarrayBase = require( '@stdlib/ndarray/base/ctor' );
26+
var ndarray = require( '@stdlib/ndarray/ctor' );
27+
var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
28+
var format = require( '@stdlib/string/format' );
29+
var pkg = require( './../package.json' ).name;
30+
var atleastnd = require( './../lib' );
31+
32+
33+
// MAIN //
34+
35+
bench( format( '%s::base_ndarray:ndims=2', pkg ), function benchmark( b ) {
36+
var values;
37+
var buffer;
38+
var offset;
39+
var dtype;
40+
var order;
41+
var out;
42+
var i;
43+
44+
dtype = 'float64';
45+
buffer = new Float64Array( 12 );
46+
offset = 0;
47+
order = 'row-major';
48+
49+
values = [
50+
ndarrayBase( dtype, buffer, [ 3, 2, 2 ], [ 4, 2, 1 ], offset, order ),
51+
ndarrayBase( dtype, buffer, [ 4, 3 ], [ 3, 1 ], offset, order ),
52+
ndarrayBase( dtype, buffer, [ 12 ], [ 1 ], offset, order )
53+
];
54+
55+
b.tic();
56+
for ( i = 0; i < b.iterations; i++ ) {
57+
out = atleastnd( 2, [ 10.0, values[ i%values.length ] ] );
58+
if ( typeof out !== 'object' ) {
59+
b.fail( 'should return an object' );
60+
}
61+
}
62+
b.toc();
63+
if ( !isndarrayLike( out[ 0 ] ) || !isndarrayLike( out[ 1 ] ) ) {
64+
b.fail( 'should return an array of ndarrays' );
65+
}
66+
b.pass( 'benchmark finished' );
67+
b.end();
68+
});
69+
70+
bench( format( '%s::ndarray:ndims=2', pkg ), function benchmark( b ) {
71+
var values;
72+
var buffer;
73+
var offset;
74+
var dtype;
75+
var order;
76+
var out;
77+
var i;
78+
79+
dtype = 'float64';
80+
buffer = new Float64Array( 12 );
81+
offset = 0;
82+
order = 'row-major';
83+
84+
values = [
85+
ndarray( dtype, buffer, [ 3, 2, 2 ], [ 4, 2, 1 ], offset, order ),
86+
ndarray( dtype, buffer, [ 4, 3 ], [ 3, 1 ], offset, order ),
87+
ndarray( dtype, buffer, [ 12 ], [ 1 ], offset, order )
88+
];
89+
90+
b.tic();
91+
for ( i = 0; i < b.iterations; i++ ) {
92+
out = atleastnd( 2, [ 10.0, values[ i%values.length ] ] );
93+
if ( typeof out !== 'object' ) {
94+
b.fail( 'should return an object' );
95+
}
96+
}
97+
b.toc();
98+
if ( !isndarrayLike( out[ 0 ] ) || !isndarrayLike( out[ 1 ] ) ) {
99+
b.fail( 'should return an array of ndarrays' );
100+
}
101+
b.pass( 'benchmark finished' );
102+
b.end();
103+
});

‎lib/node_modules/@stdlib/ndarray/base/atleastnd/docs/repl.txt‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
2+
{{alias}}( ndims, arrays )
3+
Converts a list of values (scalars and/or ndarrays) to ndarrays having at
4+
least a specified number of dimensions.
5+
6+
Parameters
7+
----------
8+
ndims: number
9+
Minimum number of dimensions.
10+
11+
arrays: ArrayLikeObject
12+
List of scalars and/or ndarrays.
13+
14+
Returns
15+
-------
16+
out: Array<ndarray>
17+
List of ndarrays.
18+
19+
Examples
20+
--------
21+
> var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ] )
22+
<ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
23+
> var y = {{alias:@stdlib/ndarray/array}}( [ 5, 6, 7, 8 ] )
24+
<ndarray>[ 5, 6, 7, 8 ]
25+
> var out = {{alias}}( 3, [ x, y ] )
26+
[ <ndarray>, <ndarray> ]
27+
28+
See Also
29+
--------

‎lib/node_modules/@stdlib/ndarray/base/atleastnd/docs/types/index.d.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
import { ArrayLike } from '@stdlib/types/array';
24+
import { ndarray } from '@stdlib/types/ndarray';
25+
26+
/**
27+
* Converts a list of values (scalars and/or ndarrays) to ndarrays having at least a specified number of dimensions.
28+
*
29+
* @param ndims - minimum number of dimensions
30+
* @param arrays - array-like object containing a list of scalars and/or ndarrays
31+
* @returns an array of ndarrays
32+
*
33+
* @example
34+
* var array = require( '@stdlib/ndarray/array' );
35+
*
36+
* var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] );
37+
* // returns <ndarray>[ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ]
38+
*
39+
* var y = array( [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] );
40+
* // returns <ndarray>[ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ]
41+
*
42+
* var out = atleastnd( 3, [ x, y ] );
43+
* // returns [ <ndarray>, <ndarray> ]
44+
*/
45+
declare function atleastnd( ndims: number, arrays: ArrayLike<any> ): Array<ndarray>;
46+
47+
48+
// EXPORTS //
49+
50+
export = atleastnd;

‎lib/node_modules/@stdlib/ndarray/base/atleastnd/docs/types/test.ts‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2026 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
import zeros = require( '@stdlib/ndarray/zeros' );
20+
import atleastnd = require( './index' );
21+
22+
23+
// TESTS //
24+
25+
// The function returns an array of ndarrays...
26+
{
27+
const x = zeros( [ 2, 2 ] );
28+
const y = zeros( [ 2, 2, 2 ] );
29+
30+
atleastnd( 3, [ x ] ); // $ExpectType ndarray[]
31+
atleastnd( 3, [ x, y ] ); // $ExpectType ndarray[]
32+
atleastnd( 3, [ x, y, x ] ); // $ExpectType ndarray[]
33+
}
34+
35+
// The compiler throws an error if the function is provided a first argument which is not a number...
36+
{
37+
const x = zeros( [ 2, 2 ] );
38+
const y = zeros( [ 2, 2, 2 ] );
39+
40+
atleastnd( '5', [ x, y ] ); // $ExpectError
41+
atleastnd( true, [ x, y ] ); // $ExpectError
42+
atleastnd( false, [ x, y ] ); // $ExpectError
43+
atleastnd( null, [ x, y ] ); // $ExpectError
44+
atleastnd( {}, [ x, y ] ); // $ExpectError
45+
atleastnd( [ '5' ], [ x, y ] ); // $ExpectError
46+
atleastnd( ( x: number ): number => x, [ x, y ] ); // $ExpectError
47+
}
48+
49+
// The compiler throws an error if the function is provided a second argument which is not an array ...
50+
{
51+
atleastnd( 3, 5 ); // $ExpectError
52+
atleastnd( 3, true ); // $ExpectError
53+
atleastnd( 3, false ); // $ExpectError
54+
atleastnd( 3, null ); // $ExpectError
55+
atleastnd( 3, {} ); // $ExpectError
56+
atleastnd( 3, ( x: number ): number => x ); // $ExpectError
57+
}
58+
59+
// The compiler throws an error if the function is provided an unsupported number of arguments...
60+
{
61+
const x = zeros( [ 2, 2 ] );
62+
const y = zeros( [ 2, 2, 2 ] );
63+
64+
atleastnd(); // $ExpectError
65+
atleastnd( 3 ); // $ExpectError
66+
atleastnd( 3, [ x, y ], {} ); // $ExpectError
67+
}

0 commit comments

Comments
 (0)