<!--

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

-->

# unitspace

> Return a new [ndarray][@stdlib/ndarray/ctor] filled with linearly spaced numeric elements which increment by `1` starting from a specified value along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.

<section class="usage">

## Usage

```javascript
var unitspace = require( '@stdlib/blas/ext/unitspace' );
```

#### unitspace( shape, start\[, options] )

Returns a new [ndarray][@stdlib/ndarray/ctor] filled with linearly spaced numeric elements which increment by `1` starting from a specified value along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.

```javascript
var x = unitspace( [ 4 ], 1.0 );
// returns <ndarray>[ 1.0, 2.0, 3.0, 4.0 ]
```

The function has the following parameters:

-   **shape**: array shape.
-   **start**: starting value. May be either a number, a complex number, or an [ndarray][@stdlib/ndarray/ctor] having a numeric or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the complement of the shape defined by `options.dims`. For example, given the input shape `[2, 3, 4]` and `options.dims=[0]`, a start [ndarray][@stdlib/ndarray/ctor] must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input shape, a start [ndarray][@stdlib/ndarray/ctor] must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor].
-   **options**: function options (_optional_).

The function accepts the following options:

-   **dims**: list of dimensions over which to perform operation. If not provided, the function generates linearly spaced values along the last dimension. Default: `[-1]`.
-   **dtype**: output [ndarray][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes]. Must be a numeric or "generic" [data type][@stdlib/ndarray/dtypes]. If a data type is provided, `start` is cast to the specified data type. If a data type is not provided, the default output array data type is the same as the data type of `start`.
-   **order**: specifies whether an [ndarray][@stdlib/ndarray/ctor] is `'row-major'` (C-style) or `'column-major'` (Fortran-style). If `start` is a scalar value, the default order is `'row-major'`. If `start` is an [ndarray][@stdlib/ndarray/ctor], the default order is the same as the memory layout of `start`.
-   **mode**: specifies how to handle indices which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). Default: `'throw'`.
-   **submode**: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions (see [`ndarray`][@stdlib/ndarray/ctor]). If provided fewer modes than dimensions, the function recycles modes using modulo arithmetic. Default: `[ options.mode ]`.

When provided a scalar or zero-dimensional [ndarray][@stdlib/ndarray/ctor] `start` argument, the value is broadcast across all elements in the shape defined by the complement of those dimensions specified by `options.dims`. To specify separate sub-array starting values, provide a non-zero-dimensional [ndarray][@stdlib/ndarray/ctor] argument.

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

var start = array( [ 1.0, 5.0 ] );
// returns <ndarray>[ 1.0, 5.0 ]

var x = unitspace( [ 2, 3 ], start );
// returns <ndarray>[ [ 1.0, 2.0, 3.0 ], [ 5.0, 6.0, 7.0 ] ]
```

By default, the function generates linearly spaced values along the last dimension of an output [ndarray][@stdlib/ndarray/ctor]. To perform the operation over specific dimensions, provide a `dims` option.

```javascript
var x = unitspace( [ 2, 2 ], 1.0, {
    'dims': [ 0, 1 ]
});
// returns <ndarray>[ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ]
```

To specify the output [ndarray][@stdlib/ndarray/ctor] [data type][@stdlib/ndarray/dtypes], provide a `dtype` option.

```javascript
var x = unitspace( [ 4 ], 1.0, {
    'dtype': 'float32'
});
// returns <ndarray>[ 1.0, 2.0, 3.0, 4.0 ]
```

#### unitspace.assign( x, start\[, options] )

Fills an [ndarray][@stdlib/ndarray/ctor] with linearly spaced numeric elements which increment by `1` starting from a specified value along one or more [ndarray][@stdlib/ndarray/ctor] dimensions.

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

var x = zeros( [ 4 ] );
// returns <ndarray>[ 0.0, 0.0, 0.0, 0.0 ]

var out = unitspace.assign( x, 1.0 );
// returns <ndarray>[ 1.0, 2.0, 3.0, 4.0 ]

var bool = ( x === out );
// returns true
```

The function has the following parameters:

-   **x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a numeric or "generic" [data type][@stdlib/ndarray/dtypes].
-   **start**: starting value. May be either a number, a complex number, or an [ndarray][@stdlib/ndarray/ctor] having a numeric or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the complement of the shape defined by `options.dims`. For example, given the input shape `[2, 3, 4]` and `options.dims=[0]`, a start [ndarray][@stdlib/ndarray/ctor] must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor], a start [ndarray][@stdlib/ndarray/ctor] must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor].
-   **options**: function options (_optional_).

The function accepts the following options:

-   **dims**: list of dimensions over which to perform operation. If not provided, the function generates linearly spaced values along the last dimension. Default: `[-1]`.

</section>

<!-- /.usage -->

<section class="notes">

## Notes

-   When writing to a complex floating-point output [ndarray][@stdlib/ndarray/ctor], a real-valued `start` value is treated as a complex number having a real component equaling the provided value and having an imaginary component equaling zero.
-   The `start` argument is cast to the data type of the output [ndarray][@stdlib/ndarray/ctor].
-   The function iterates over [ndarray][@stdlib/ndarray/ctor] elements according to the memory layout of an output [ndarray][@stdlib/ndarray/ctor]. Accordingly, performance degradation is possible when operating over multiple dimensions of a large non-contiguous multi-dimensional output [ndarray][@stdlib/ndarray/ctor]. In such scenarios, one may want to copy an output [ndarray][@stdlib/ndarray/ctor] to contiguous memory before filling with linearly spaced values.

</section>

<!-- /.notes -->

<section class="examples">

## Examples

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

```javascript
var ndarray2array = require( '@stdlib/ndarray/to-array' );
var unitspace = require( '@stdlib/blas/ext/unitspace' );

// Create a vector of starting values:
var start = unitspace( [ 5 ], 1 );

// Create a grid:
var out = unitspace( [ 5, 5 ], start );
console.log( ndarray2array( out ) );

// Generate values over multiple dimensions:
out = unitspace( [ 5, 5 ], 1, {
    'dims': [ 0, 1 ]
});
console.log( ndarray2array( out ) );

// Generate values over multiple dimensions in column-major order:
out = unitspace( [ 5, 5 ], 1, {
    'dims': [ 0, 1 ],
    'order': 'column-major'
});
console.log( ndarray2array( out ) );
```

</section>

<!-- /.examples -->

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

<section class="related">

</section>

<!-- /.related -->

<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="links">

[@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray-ctor

[@stdlib/ndarray/dtypes]: https://www.npmjs.com/package/@stdlib/ndarray-dtypes

[@stdlib/ndarray/base/broadcast-shapes]: https://www.npmjs.com/package/@stdlib/ndarray-base-broadcast-shapes

</section>

<!-- /.links -->
