<!--

@license Apache-2.0

Copyright (c) 2026 The Stdlib Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

-->

# atleastnd

> Convert a list of values (scalars and/or ndarrays) to ndarrays having at least a specified number of dimensions.

<section class="intro">

</section>

<!-- /.intro -->

<section class="usage">

## Usage

```javascript
var atleastnd = require( '@stdlib/ndarray/base/atleastnd' );
```

#### atleastnd( ndims, arrays )

Converts a list of values (scalars and/or ndarrays) to ndarrays having at least a specified number of dimensions.

```javascript
var array = require( '@stdlib/ndarray/array' );

var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ] );
// returns <ndarray>[ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ] ]

var y = array( [ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ] );
// returns <ndarray>[ [ 5.0, 6.0 ], [ 7.0, 8.0 ] ]

var out = atleastnd( 3, [ x, y ] );
// returns [ <ndarray>, <ndarray> ]
```

The function accepts the following arguments:

-   **ndims**: minimum number of dimensions.
-   **arrays**: array-like object containing a list of scalars and/or ndarrays.

</section>

<!-- /.usage -->

<section class="notes">

## Notes

-   If a provided ndarray has fewer dimensions than `ndims`, the function prepends singleton dimensions, and the returned ndarray is a view on the input ndarray data buffer.

-   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.

-   If provided a scalar value (i.e., a non-ndarray) and that value

    -   is a number, the returned ndarray will have the [default][@stdlib/ndarray/defaults] real-valued floating-point data type.
    -   is a boolean, the returned ndarray will have the [default][@stdlib/ndarray/defaults] boolean data type.
    -   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.
    -   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.
    -   is any other value type, the returned ndarray will have a `'generic'` data type.

</section>

<!-- /.notes -->

<section class="examples">

## Examples

<!-- eslint no-undef: "error" -->

```javascript
var discreteUniform = require( '@stdlib/random/discrete-uniform' );
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var atleastnd = require( '@stdlib/ndarray/base/atleastnd' );

var x = discreteUniform( [ 2, 2, 2 ], -100, 100 );
// returns <ndarray>

var y = discreteUniform( [ 5, 2 ], -100, 100 );
// returns <ndarray>

var out = atleastnd( 3, [ x, y ] );
// returns [ <ndarray>, <ndarray> ]

console.log( ndarray2array( out[ 0 ] ) );
console.log( ndarray2array( out[ 1 ] ) );
```

</section>

<!-- /.examples -->

<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->

<section class="related">

</section>

<!-- /.related -->

<section class="links">

[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray/tree/main/ctor

[@stdlib/ndarray/base/ctor]: https://github.com/stdlib-js/ndarray/tree/main/base/ctor

[@stdlib/ndarray/defaults]: https://github.com/stdlib-js/ndarray/tree/main/defaults

</section>

<!-- /.links -->
