Skip to content

Commit 97c00e6

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 07c28da commit 97c00e6

File tree

11 files changed

+780
-1
lines changed

11 files changed

+780
-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 (2026-02-27)
7+
## Unreleased (2026-02-28)
88

99
<section class="features">
1010

1111
### Features
1212

13+
- [`53caca8`](https://github.com/stdlib-js/stdlib/commit/53caca808d0b9aad069992056c6fe64b0c780e8f) - add `ndarray/base/atleastnd` [(#10422)](https://github.com/stdlib-js/stdlib/pull/10422)
1314
- [`9221bdb`](https://github.com/stdlib-js/stdlib/commit/9221bdb56bac8544a387c8b8f74ae69ae5ec2961) - add `toTransposed` to namespace
1415
- [`5606366`](https://github.com/stdlib-js/stdlib/commit/560636601a3ebbc74e58ba18752ba832c3548215) - add `ndarray/base/to-transposed` [(#10499)](https://github.com/stdlib-js/stdlib/pull/10499)
1516
- [`01a25b3`](https://github.com/stdlib-js/stdlib/commit/01a25b340fc172d9754d027cc09330e0be32babb) - add `unflattenShape` to namespace
@@ -758,6 +759,7 @@ A total of 44 issues were closed in this release:
758759

759760
<details>
760761

762+
- [`53caca8`](https://github.com/stdlib-js/stdlib/commit/53caca808d0b9aad069992056c6fe64b0c780e8f) - **feat:** add `ndarray/base/atleastnd` [(#10422)](https://github.com/stdlib-js/stdlib/pull/10422) _(by Muhammad Haris, Athan Reines)_
761763
- [`8e51991`](https://github.com/stdlib-js/stdlib/commit/8e519911fa82286c82b696e058c5da2fba071c3e) - **style:** revert style changes _(by Athan Reines)_
762764
- [`965c4b9`](https://github.com/stdlib-js/stdlib/commit/965c4b9341f4a3b721a06bfd5c48e1393b5ab59d) - **chore:** fix JavaScript lint errors [(#10380)](https://github.com/stdlib-js/stdlib/pull/10380) _(by Bhargav Dabhade)_
763765
- [`7eb18f2`](https://github.com/stdlib-js/stdlib/commit/7eb18f24166f78119540ec88e652e5643a5d2518) - **chore:** minor clean-up _(by Philipp Burckhardt)_

‎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/ndarray/tree/main/ctor
124+
125+
[@stdlib/ndarray/base/ctor]: https://github.com/stdlib-js/ndarray/tree/main/base/ctor
126+
127+
[@stdlib/ndarray/defaults]: https://github.com/stdlib-js/ndarray/tree/main/defaults
128+
129+
</section>
130+
131+
<!-- /.links -->

‎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( './../../../base/ctor' );
26+
var ndarray = require( './../../../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+
});

‎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+
--------

‎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;

0 commit comments

Comments
 (0)