feat!: add writable parameter to ndarray/base/expand-dimensions

This commit adds a writable parameter to `expandDimensions` to explicitly support indicating whether a returned ndarray should be read-only. Previously, we only returned a read-only ndarray is an input ndarray was read-only. This now pushes responsibility for determining whether an output ndarray is read-only to the user.

BREAKING CHANGE: 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.

PR-URL: #9476
Closes: stdlib-js/metr-issue-tracker#138
Co-authored-by: Athan Reines <kgryte@gmail.com>
Reviewed-by: Athan Reines <kgryte@gmail.com>

Author: headlessNode

lib/node_modules/@stdlib/ndarray/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>

lib/node_modules/@stdlib/ndarray/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' );
 		}

lib/node_modules/@stdlib/ndarray/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' );
 			}

lib/node_modules/@stdlib/ndarray/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
     --------

lib/node_modules/@stdlib/ndarray/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 //

lib/node_modules/@stdlib/ndarray/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
 }

lib/node_modules/@stdlib/ndarray/base/expand-dimensions/examples/index.js

@@ -18,29 +18,12 @@
 
 'use strict';
 
-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( './../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 ) );

lib/node_modules/@stdlib/ndarray/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 //

lib/node_modules/@stdlib/ndarray/base/expand-dimensions/lib/main.js

@@ -21,7 +21,6 @@
 // MODULES //
 
 var isRowMajor = require( '@stdlib/ndarray/base/assert/is-row-major-string' );
-var isReadOnly = require( '@stdlib/ndarray/base/assert/is-read-only' );
 var normalizeIndex = require( '@stdlib/ndarray/base/normalize-index' );
 var getDType = require( '@stdlib/ndarray/base/dtype' );
 var getShape = require( '@stdlib/ndarray/base/shape' );
@@ -43,26 +42,20 @@ var format = require( '@stdlib/string/format' );
 *
 * @param {ndarray} x - input array
 * @param {integer} axis - axis at which to insert a singleton dimension
+* @param {boolean} writable - boolean indicating whether the returned ndarray should be writable
 * @throws {RangeError} must provide a valid axis
 * @returns {ndarray} 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 ]
 */
-function expandDimensions( x, axis ) {
+function expandDimensions( x, axis, writable ) {
 	var strides;
 	var shape;
 	var isrm;
@@ -132,13 +125,9 @@ function expandDimensions( x, axis ) {
 			}
 		}
 	}
-	if ( isReadOnly( x ) ) {
-		// If provided a read-only view, the returned array should also be read-only...
-		return new x.constructor( getDType( x ), getData( x ), shape, strides, getOffset( x ), ord, { // eslint-disable-line max-len
-			'readonly': true
-		});
-	}
-	return new x.constructor( getDType( x ), getData( x ), shape, strides, getOffset( x ), ord ); // eslint-disable-line max-len
+	return new x.constructor( getDType( x ), getData( x ), shape, strides, getOffset( x ), ord, { // eslint-disable-line max-len
+		'readonly': !writable
+	});
 }