Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -4,12 +4,13 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2026-01-06)
+## Unreleased (2026-01-09)
 
 <section class="features">
 
 ### Features
 
+-   [`f475c84`](https://github.com/stdlib-js/stdlib/commit/f475c843a4b1579eef6533e464e4c16766d7ecdd) - add writable parameter to `ndarray/base/expand-dimensions` [(#9476)](https://github.com/stdlib-js/stdlib/pull/9476)
 -   [`f40ccb7`](https://github.com/stdlib-js/stdlib/commit/f40ccb75929e92538b8c366145589addccdaafbe) - add `ndarray/base/ternary-loop-interchange-order` [(#9499)](https://github.com/stdlib-js/stdlib/pull/9499)
 -   [`1f79854`](https://github.com/stdlib-js/stdlib/commit/1f798549409c47de0261c5396dccf64012e54a9c) - add `ndarray/base/ternary-tiling-block-size` [(#9495)](https://github.com/stdlib-js/stdlib/pull/9495)
 -   [`327cda9`](https://github.com/stdlib-js/stdlib/commit/327cda9b2dda086b20da9ce256df388573486946) - update `ndarray` TypeScript declarations [(#9508)](https://github.com/stdlib-js/stdlib/pull/9508)
@@ -628,6 +629,10 @@
 
 ### BREAKING CHANGES
 
+-   [`f475c84`](https://github.com/stdlib-js/stdlib/commit/f475c843a4b1579eef6533e464e4c16766d7ecdd): add `writable` parameter
+
+    -   To migrate, users should explicitly provide a third argument indicating whether to return a read-only ndarray. To preserve prior behavior, users should provide a boolean based on whether an input ndarray is read-only.
+
 -   [`327cda9`](https://github.com/stdlib-js/stdlib/commit/327cda9b2dda086b20da9ce256df388573486946): move `dim` argument to option
 
     -   To migrate, users wanting to specify a dimension along which to concatenate input arrays should provide an object containing a `dim` property.
@@ -689,6 +694,7 @@ A total of 40 issues were closed in this release:
 
 <details>
 
+-   [`f475c84`](https://github.com/stdlib-js/stdlib/commit/f475c843a4b1579eef6533e464e4c16766d7ecdd) - **feat:** add writable parameter to `ndarray/base/expand-dimensions` [(#9476)](https://github.com/stdlib-js/stdlib/pull/9476) _(by Muhammad Haris, Athan Reines)_
 -   [`da6ecc9`](https://github.com/stdlib-js/stdlib/commit/da6ecc96d7f503e03007eef616703fc7a71587b8) - **chore:** fix JavaScript lint errors [(#9572)](https://github.com/stdlib-js/stdlib/pull/9572) _(by Shreelaxmi Hegde, Athan Reines)_
 -   [`ed3afe7`](https://github.com/stdlib-js/stdlib/commit/ed3afe7252708109f1a8350c15bcdabcc96f6e0a) - **chore:** fix C lint errors [(#9571)](https://github.com/stdlib-js/stdlib/pull/9571) _(by Geo Daoyu)_
 -   [`46c47ec`](https://github.com/stdlib-js/stdlib/commit/46c47ec0c92f9a3608290ef8a6ca5cf0e9258866) - **refactor:** update paths _(by Neeraj Pathak)_

NOTICE

@@ -1 +1 @@
-Copyright (c) 2016-2025 The Stdlib Authors.
+Copyright (c) 2016-2026 The Stdlib Authors.

base/expand-dimensions/README.md

@@ -40,7 +40,7 @@ limitations under the License.
 var expandDimensions = require( '@stdlib/ndarray/base/expand-dimensions' );
 ```
 
-#### expandDimensions( x, axis )
+#### expandDimensions( x, axis, writable )
 
 Expands the shape of an array `x` by inserting a new dimension of size one at a specified `axis`.
 
@@ -53,27 +53,33 @@ var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
 
 // Prepend a singleton dimension:
-var y = expandDimensions( x, 0 );
+var y = expandDimensions( x, 0, false );
 // returns <ndarray>[ [ [ 1, 2 ], [ 3, 4 ] ] ]
 
 var sh = getShape( y );
 // returns [ 1, 2, 2 ]
 
 // Append a singleton dimension:
-y = expandDimensions( x, 2 );
+y = expandDimensions( x, 2, false );
 // returns <ndarray>[ [ [ 1 ], [ 2 ] ], [ [ 3 ], [ 4 ] ] ]
 
 sh = getShape( y );
 // returns [ 2, 2, 1 ]
 
 // Insert a singleton dimension:
-y = expandDimensions( x, 1 );
+y = expandDimensions( x, 1, false );
 // returns <ndarray>[ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
 
 sh = getShape( y );
 // returns [ 2, 1, 2 ]
 ```
 
+The function accepts the following arguments:
+
+-   **x**: input ndarray.
+-   **axis**: axis at which to insert a singleton dimension
+-   **writable**: boolean indicating whether a returned ndarray should be writable.
+
 </section>
 
 <!-- /.usage -->
@@ -85,6 +91,7 @@ sh = getShape( y );
 ## Notes
 
 -   A provided axis must reside on the interval `[-N-1, N]`, where `N` is the rank (i.e., number of dimensions) of the provided input array. If provided a negative `axis`, the axis position at which to insert a singleton dimension is computed as `N + axis + 1`. Hence, if provided `-1`, the resolved axis position is `N` (i.e., a singleton dimension is appended to the input array).
+-   The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
 
 </section>
 
@@ -99,32 +106,15 @@ sh = getShape( y );
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var array = require( '@stdlib/ndarray/array' );
-var numel = require( '@stdlib/ndarray/base/numel' );
-var ind2sub = require( '@stdlib/ndarray/ind2sub' );
-var getShape = require( '@stdlib/ndarray/shape' );
+var uniform = require( '@stdlib/random/uniform' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var expandDimensions = require( '@stdlib/ndarray/base/expand-dimensions' );
 
-// Create a 2-dimensional array:
-var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
-// returns <ndarray>
-
-// Insert a singleton dimension:
-var y = expandDimensions( x, 1 );
-// returns <ndarray>
-
-// Retrieve the shape:
-var sh = getShape( y );
-// returns [ 2, 1, 2 ]
-
-// Retrieve the number of elements:
-var N = numel( sh );
+var x = uniform( [ 3, 3, 3 ], -10.0, 10.0 );
+console.log( ndarray2array( x ) );
 
-// 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 ) );
-}
+var y = expandDimensions( x, 1, false );
+console.log( ndarray2array( y ) );
 ```
 
 </section>

base/expand-dimensions/benchmark/benchmark.js

@@ -59,7 +59,7 @@ bench( pkg+'::base_ndarray,2d', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = expandDimensions( values[ i%values.length ], 1 );
+		out = expandDimensions( values[ i%values.length ], 1, false );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}
@@ -100,7 +100,7 @@ bench( pkg+'::ndarray,2d', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = expandDimensions( values[ i%values.length ], 1 );
+		out = expandDimensions( values[ i%values.length ], 1, false );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}

base/expand-dimensions/benchmark/benchmark.ndims.js

@@ -54,7 +54,7 @@ function createBenchmark( ndims ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			out = expandDimensions( x, i%(ndims-1) );
+			out = expandDimensions( x, i%(ndims-1), false );
 			if ( typeof out !== 'object' ) {
 				b.fail( 'should return an object' );
 			}

base/expand-dimensions/docs/repl.txt

@@ -1,5 +1,5 @@
 
-{{alias}}( x, axis )
+{{alias}}( x, axis, writable )
     Expands the shape of an array by inserting a new dimension of size one at a
     specified axis.
 
@@ -11,6 +11,9 @@
     the resolved axis position is `N` (i.e., a singleton dimension is appended
     to the input array).
 
+    The `writable` parameter only applies to ndarray constructors supporting
+    read-only instances.
+
     Parameters
     ----------
     x: ndarray
@@ -19,6 +22,9 @@
     axis: integer
         Axis at which to insert a singleton dimension.
 
+    writable: boolean
+        Boolean indicating whether the returned ndarray should be writable.
+
     Returns
     -------
     out: ndarray
@@ -28,12 +34,8 @@
     --------
     > var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ] )
     <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
-    > var sh = {{alias:@stdlib/ndarray/shape}}( x )
-    [ 2, 2 ]
-    > var y = {{alias}}( x, 1 )
+    > var y = {{alias}}( x, 1, false )
     <ndarray>[ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
-    > sh = {{alias:@stdlib/ndarray/shape}}( y )
-    [ 2, 1, 2 ]
 
     See Also
     --------

base/expand-dimensions/docs/types/index.d.ts

@@ -31,25 +31,19 @@ import { typedndarray } from '@stdlib/types/ndarray';
 *
 * @param x - input array
 * @param axis - axis at which to insert a singleton dimension
+* @param writable - boolean indicating whether the returned ndarray should be writable
 * @returns output array
 *
 * @example
-* var getShape = require( '@stdlib/ndarray/shape' );
 * var array = require( '@stdlib/ndarray/array' );
 *
 * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 * // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
 *
-* var shx = getShape( x );
-* // returns [ 2, 2 ]
-*
-* var y = expandDimensions( x, 1 );
+* var y = expandDimensions( x, 1, false );
 * // returns <ndarray>[ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
-*
-* var shy = getShape( y );
-* // returns [ 2, 1, 2 ]
 */
-declare function expandDimensions<T = unknown>( x: typedndarray<T>, axis: number ): typedndarray<T>;
+declare function expandDimensions<T = unknown>( x: typedndarray<T>, axis: number, writable: boolean ): typedndarray<T>;
 
 
 // EXPORTS //

base/expand-dimensions/docs/types/test.ts

@@ -26,32 +26,47 @@ import expandDimensions = require( './index' );
 {
 	const x = zeros( [ 2, 2 ] );
 
-	expandDimensions( x, 1 ); // $ExpectType typedndarray<number>
+	expandDimensions( x, 1, false ); // $ExpectType typedndarray<number>
 }
 
 // The compiler throws an error if the function is not provided a first argument which is an ndarray...
 {
-	expandDimensions( '5', 1 ); // $ExpectError
-	expandDimensions( 5, 1 ); // $ExpectError
-	expandDimensions( true, 1 ); // $ExpectError
-	expandDimensions( false, 1 ); // $ExpectError
-	expandDimensions( null, 1 ); // $ExpectError
-	expandDimensions( {}, 1 ); // $ExpectError
-	expandDimensions( [ '5' ], 1 ); // $ExpectError
-	expandDimensions( ( x: number ): number => x, 1 ); // $ExpectError
+	expandDimensions( '5', 1, false ); // $ExpectError
+	expandDimensions( 5, 1, false ); // $ExpectError
+	expandDimensions( true, 1, false ); // $ExpectError
+	expandDimensions( false, 1, false ); // $ExpectError
+	expandDimensions( void 0, 1, false ); // $ExpectError
+	expandDimensions( null, 1, false ); // $ExpectError
+	expandDimensions( {}, 1, false ); // $ExpectError
+	expandDimensions( [ '5' ], 1, false ); // $ExpectError
+	expandDimensions( ( x: number ): number => x, 1, false ); // $ExpectError
 }
 
 // The compiler throws an error if the function is not provided a second argument which is a number...
 {
 	const x = zeros( [ 2, 2 ] );
 
-	expandDimensions( x, '5' ); // $ExpectError
-	expandDimensions( x, true ); // $ExpectError
-	expandDimensions( x, false ); // $ExpectError
-	expandDimensions( x, null ); // $ExpectError
-	expandDimensions( x, {} ); // $ExpectError
-	expandDimensions( x, [ '5' ] ); // $ExpectError
-	expandDimensions( x, ( x: number ): number => x ); // $ExpectError
+	expandDimensions( x, '5', false ); // $ExpectError
+	expandDimensions( x, true, false ); // $ExpectError
+	expandDimensions( x, false, false ); // $ExpectError
+	expandDimensions( x, void 0, false ); // $ExpectError
+	expandDimensions( x, null, false ); // $ExpectError
+	expandDimensions( x, {}, false ); // $ExpectError
+	expandDimensions( x, [ '5' ], false ); // $ExpectError
+	expandDimensions( x, ( x: number ): number => x, false ); // $ExpectError
+}
+
+// The compiler throws an error if the function is not provided a third argument which is a boolean...
+{
+	const x = zeros( [ 2, 2 ] );
+
+	expandDimensions( x, 1, '5' ); // $ExpectError
+	expandDimensions( x, 1, 5 ); // $ExpectError
+	expandDimensions( x, 1, void 0 ); // $ExpectError
+	expandDimensions( x, 1, null ); // $ExpectError
+	expandDimensions( x, 1, {} ); // $ExpectError
+	expandDimensions( x, 1, [ '5' ] ); // $ExpectError
+	expandDimensions( x, 1, ( x: number ): number => x ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided an unsupported number of arguments...
@@ -60,5 +75,6 @@ import expandDimensions = require( './index' );
 
 	expandDimensions(); // $ExpectError
 	expandDimensions( x ); // $ExpectError
-	expandDimensions( x, 1, [ 1, 2, 3 ], [ 2, 3 ] ); // $ExpectError
+	expandDimensions( x, 1 ); // $ExpectError
+	expandDimensions( x, 1, false, [ 1, 2, 3 ] ); // $ExpectError
 }

base/expand-dimensions/examples/index.js

@@ -18,29 +18,12 @@
 
 'use strict';
 
-var array = require( './../../../array' );
-var numel = require( './../../../base/numel' );
-var ind2sub = require( './../../../ind2sub' );
-var getShape = require( './../../../shape' );
+var uniform = require( '@stdlib/random/uniform' );
+var ndarray2array = require( './../../../to-array' );
 var expandDimensions = require( './../lib' );
 
-// Create a 2-dimensional array:
-var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
-// returns <ndarray>
+var x = uniform( [ 3, 3, 3 ], -10.0, 10.0 );
+console.log( ndarray2array( x ) );
 
-// Insert a singleton dimension:
-var y = expandDimensions( x, 1 );
-// returns <ndarray>
-
-// Retrieve the shape:
-var sh = getShape( y );
-// returns [ 2, 1, 2 ]
-
-// 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 ) );
-}
+var y = expandDimensions( x, 1, false );
+console.log( ndarray2array( y ) );

base/expand-dimensions/lib/index.js

@@ -24,21 +24,14 @@
 * @module @stdlib/ndarray/base/expand-dimensions
 *
 * @example
-* var getShape = require( '@stdlib/ndarray/shape' );
 * var array = require( '@stdlib/ndarray/array' );
 * var expandDimensions = require( '@stdlib/ndarray/base/expand-dimensions' );
 *
 * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 * // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
 *
-* var shx = getShape( x );
-* // returns [ 2, 2 ]
-*
-* var y = expandDimensions( x, 1 );
+* var y = expandDimensions( x, 1, false );
 * // returns <ndarray>[ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
-*
-* var shy = getShape( y );
-* // returns [ 2, 1, 2 ]
 */
 
 // MODULES //