spreadDimensions

Expand the shape of an array to a specified dimensionality by spreading its dimensions to specified dimension indices and inserting dimensions of size one for the remaining dimensions.

Installation

npm install @stdlib/ndarray-base-spread-dimensions

Usage

var spreadDimensions = require( '@stdlib/ndarray-base-spread-dimensions' );

spreadDimensions( ndims, x, dims, writable )

Expands the shape of an array to a specified dimensionality by spreading its dimensions to specified dimension indices and inserting dimensions of size one for the remaining dimensions.

var ndarray2array = require( '@stdlib/ndarray-to-array' );
var array = require( '@stdlib/ndarray-array' );

// Create a 2x2 ndarray:
var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>

// Prepend a singleton dimension:
var y = spreadDimensions( 3, x, [ 1, 2 ], false );
// returns <ndarray>

var sh = y.shape;
// returns [ 1, 2, 2 ]

var a = ndarray2array( y );
// returns [ [ [ 1, 2 ], [ 3, 4 ] ] ]

// Append a singleton dimension:
y = spreadDimensions( 3, x, [ 0, 1 ], false );
// returns <ndarray>

sh = y.shape;
// returns [ 2, 2, 1 ]

a = ndarray2array( y );
// returns [ [ [ 1 ], [ 2 ] ], [ [ 3 ], [ 4 ] ] ]

// Insert a singleton dimension:
y = spreadDimensions( 3, x, [ 0, 2 ], false );
// returns <ndarray>

sh = y.shape;
// returns [ 2, 1, 2 ]

a = ndarray2array( y );
// returns [ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]

The function accepts the following arguments:

• ndims: number of dimensions in the output ndarray. Must be greater than or equal to the number of dimensions in the input ndarray.
• x: input ndarray.
• dims: dimension indices specifying where to place the dimensions of the input ndarray. Must resolve to normalized indices arranged in ascending order.
• writable: boolean indicating whether a returned ndarray should be writable.

Notes

• Each provided dimension index must reside on the interval [-ndims, ndims-1]. If provided a negative dimension index, the position at which to place a respective dimension is computed as ndims + index.
• Provided dimension indices must resolve to normalized dimension indices arranged in ascending order.
• The writable parameter only applies to ndarray constructors supporting read-only instances.

Examples

var array = require( '@stdlib/ndarray-array' );
var numel = require( '@stdlib/ndarray-base-numel' );
var ind2sub = require( '@stdlib/ndarray-ind2sub' );
var spreadDimensions = require( '@stdlib/ndarray-base-spread-dimensions' );

// Create a 2-dimensional array:
var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
    'order': 'column-major'
});
// returns <ndarray>

// Spread dimensions:
var y = spreadDimensions( 5, x, [ 1, 3 ], false );
// returns <ndarray>

// Retrieve the shape:
var sh = y.shape;
// returns [ 1, 2, 1, 2, 1 ]

// Retrieve the number of elements:
var N = numel( sh );

// Loop through the array elements...
var i;
for ( i = 0; i < N; i++ ) {
    console.log( 'Y[%s] = %d', ind2sub( sh, i ).join( ', ' ), y.iget( i ) );
}

Notice

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

Community

License

See LICENSE.

Copyright

Copyright © 2016-2026. The Stdlib Authors.