Auto-generated commit

Author: stdlib-bot

.github/.keepalive

@@ -2,6 +2,64 @@
 
 > Package changelog.
 
+<section class="release" id="unreleased">
+
+## Unreleased (2026-02-28)
+
+<section class="features">
+
+### Features
+
+-   [`e947540`](https://github.com/stdlib-js/stdlib/commit/e947540a4e87841d7bf140094e20b2768250de11) - add writable parameter to `ndarray/base/remove-singleton-dimensions` [(#9667)](https://github.com/stdlib-js/stdlib/pull/9667)
+
+</section>
+
+<!-- /.features -->
+
+<section class="breaking-changes">
+
+### BREAKING CHANGES
+
+-   [`e947540`](https://github.com/stdlib-js/stdlib/commit/e947540a4e87841d7bf140094e20b2768250de11): add writable parameter and always return a new view
+
+    -   To migrate, in order to preserve prior writable behavior, users should set the final parameter equal to a boolean indicating whether the input ndarray is writable. If not, pass `false`; if yes, pass `true`.
+        To preserve prior behavior in which the input ndarray is returned if it does not have singleton dimensions, use `ndarray/base/maybe-remove-singleton-dimensions`.
+
+</section>
+
+<!-- /.breaking-changes -->
+
+<section class="commits">
+
+### Commits
+
+<details>
+
+-   [`e947540`](https://github.com/stdlib-js/stdlib/commit/e947540a4e87841d7bf140094e20b2768250de11) - **feat:** add writable parameter to `ndarray/base/remove-singleton-dimensions` [(#9667)](https://github.com/stdlib-js/stdlib/pull/9667) _(by Muhammad Haris, Athan Reines)_
+
+</details>
+
+</section>
+
+<!-- /.commits -->
+
+<section class="contributors">
+
+### Contributors
+
+A total of 2 people contributed to this release. Thank you to the following contributors:
+
+-   Athan Reines
+-   Muhammad Haris
+
+</section>
+
+<!-- /.contributors -->
+
+</section>
+
+<!-- /.release -->
+
 <section class="release" id="v0.2.3">
 
 ## 0.2.3 (2026-02-08)

CHANGELOG.md

@@ -73,7 +73,7 @@ To view installation and usage instructions specific to each branch build, be su
 var removeSingletonDimensions = require( '@stdlib/ndarray-base-remove-singleton-dimensions' );
 ```
 
-#### removeSingletonDimensions( x )
+#### removeSingletonDimensions( x, writable )
 
 Returns an ndarray without singleton dimensions (i.e., dimensions whose size is equal to `1`).
 
@@ -82,16 +82,18 @@ var array = require( '@stdlib/ndarray-array' );
 
 // Create a 1x2x2 ndarray:
 var x = array( [ [ [ 1, 2 ], [ 3, 4 ] ] ] );
-// returns <ndarray>
+// returns <ndarray>[ [ [ 1, 2 ], [ 3, 4 ] ] ]
 
 // Remove singleton dimensions:
-var y = removeSingletonDimensions( x );
-// returns <ndarray>
-
-var sh = y.shape;
-// returns [ 2, 2 ]
+var y = removeSingletonDimensions( x, false );
+// returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
 ```
 
+The function accepts the following arguments:
+
+-   **x**: input ndarray.
+-   **writable**: boolean indicating whether a returned ndarray should be writable.
+
 </section>
 
 <!-- /.usage -->
@@ -102,8 +104,8 @@ var sh = y.shape;
 
 ## Notes
 
--   If a provided ndarray does not have any singleton dimensions, the function returns the provided ndarray unchanged.
--   If a provided ndarray does have singleton dimensions, the function returns a new ndarray view.
+-   The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
+-   The function **always** returns a new ndarray instance even if the input ndarray does not contain any singleton dimensions.
 
 </section>
 
@@ -118,33 +120,15 @@ var sh = y.shape;
 <!-- 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 uniform = require( '@stdlib/random-uniform' );
+var ndarray2array = require( '@stdlib/ndarray-to-array' );
 var removeSingletonDimensions = require( '@stdlib/ndarray-base-remove-singleton-dimensions' );
 
-// Create a 5-dimensional array:
-var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
-    'ndmin': 5
-});
-// returns <ndarray>
-
-// Remove singleton dimensions:
-var y = removeSingletonDimensions( x );
-// returns <ndarray>
-
-// Retrieve the shape:
-var sh = y.shape;
-// returns [ 2, 2 ]
-
-// Retrieve the number of elements:
-var N = numel( sh );
+var x = uniform( [ 1, 1, 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 = removeSingletonDimensions( x, false );
+console.log( ndarray2array( y ) );
 ```
 
 </section>

README.md

@@ -25,13 +25,14 @@ var Float64Array = require( '@stdlib/array-float64' );
 var ndarrayBase = require( '@stdlib/ndarray-base-ctor' );
 var ndarray = require( '@stdlib/ndarray-ctor' );
 var isndarrayLike = require( '@stdlib/assert-is-ndarray-like' );
+var format = require( '@stdlib/string-format' );
 var pkg = require( './../package.json' ).name;
 var removeSingletonDimensions = require( './../lib' );
 
 
 // MAIN //
 
-bench( pkg+'::base_ndarray,2d', function benchmark( b ) {
+bench( format( '%s::base_ndarray,2d', pkg ), function benchmark( b ) {
 	var strides;
 	var values;
 	var buffer;
@@ -59,7 +60,7 @@ bench( pkg+'::base_ndarray,2d', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = removeSingletonDimensions( values[ i%values.length ] );
+		out = removeSingletonDimensions( values[ i%values.length ], false );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}
@@ -72,7 +73,7 @@ bench( pkg+'::base_ndarray,2d', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base_ndarray,2d,no_singleton_dimensions', function benchmark( b ) {
+bench( format( '%s::base_ndarray,2d,no_singleton_dimensions', pkg ), function benchmark( b ) {
 	var strides;
 	var values;
 	var buffer;
@@ -100,7 +101,7 @@ bench( pkg+'::base_ndarray,2d,no_singleton_dimensions', function benchmark( b )
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = removeSingletonDimensions( values[ i%values.length ] );
+		out = removeSingletonDimensions( values[ i%values.length ], false );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}
@@ -113,7 +114,7 @@ bench( pkg+'::base_ndarray,2d,no_singleton_dimensions', function benchmark( b )
 	b.end();
 });
 
-bench( pkg+'::ndarray,2d', function benchmark( b ) {
+bench( format( '%s::ndarray,2d', pkg ), function benchmark( b ) {
 	var strides;
 	var values;
 	var buffer;
@@ -141,7 +142,7 @@ bench( pkg+'::ndarray,2d', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = removeSingletonDimensions( values[ i%values.length ] );
+		out = removeSingletonDimensions( values[ i%values.length ], false );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}
@@ -154,7 +155,7 @@ bench( pkg+'::ndarray,2d', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::ndarray,2d,no_singleton_dimensions', function benchmark( b ) {
+bench( format( '%s::ndarray,2d,no_singleton_dimensions', pkg ), function benchmark( b ) {
 	var strides;
 	var values;
 	var buffer;
@@ -182,7 +183,7 @@ bench( pkg+'::ndarray,2d,no_singleton_dimensions', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		out = removeSingletonDimensions( values[ i%values.length ] );
+		out = removeSingletonDimensions( values[ i%values.length ], false );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}

benchmark/benchmark.js

@@ -23,6 +23,7 @@
 var bench = require( '@stdlib/bench-harness' );
 var array = require( '@stdlib/ndarray-array' );
 var isndarrayLike = require( '@stdlib/assert-is-ndarray-like' );
+var format = require( '@stdlib/string-format' );
 var pkg = require( './../package.json' ).name;
 var removeSingletonDimensions = require( './../lib' );
 
@@ -54,7 +55,7 @@ function createBenchmark( ndims ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			out = removeSingletonDimensions( x );
+			out = removeSingletonDimensions( x, false );
 			if ( typeof out !== 'object' ) {
 				b.fail( 'should return an object' );
 			}
@@ -87,7 +88,7 @@ function main() {
 
 	for ( i = min; i <= max; i++ ) {
 		f = createBenchmark( i );
-		bench( pkg+'::ndarray,2d:singleton_dimensions='+i, f );
+		bench( format( '%s::ndarray,2d:singleton_dimensions=%d', pkg, i ), f );
 	}
 }