refactor: add writable parameter to ndarray/base/spread-dimensions

lib/node_modules/@stdlib/ndarray/any-by/lib/main.js

@@ -180,7 +180,7 @@ function anyBy( x, options, predicate, thisArg ) {
 
 	// Check whether we need to reinsert singleton dimensions which can be useful for broadcasting the returned output array to the shape of the original input array...
 	if ( opts.keepdims ) {
-		y = spreadDimensions( N, y, idx );
+		y = spreadDimensions( N, y, idx, false );
 	}
 	return y;
 }

lib/node_modules/@stdlib/ndarray/any/lib/main.js

@@ -127,7 +127,7 @@ function any( x, options ) {
 
 	// Check whether we need to reinsert singleton dimensions which can be useful for broadcasting the returned output array to the shape of the original input array...
 	if ( opts.keepdims ) {
-		y = spreadDimensions( N, y, idx );
+		y = spreadDimensions( N, y, idx, false );
 	}
 	return y;
 }

lib/node_modules/@stdlib/ndarray/base/binary-reduce-strided1d-dispatch/lib/main.js

@@ -133,7 +133,7 @@
 		throw new TypeError( format( 'invalid argument. First argument must be an object having a "types" property whose associated value is an array-like object.' ) );
 	}
 	if ( hasProp( table, 'fcns' ) && !isFunctionArray( table.fcns ) && !isEmptyCollection( table.fcns ) ) {
 		throw new TypeError( format( 'invalid argument. First argument must be an object having a "fcns" property whose associated value is an array-like object containing functions.' ) );
 	}
 	if ( !isCollection( idtypes ) ) {
 		throw new TypeError( format( 'invalid argument. Second argument must be an array-like object. Value: `%s`.', idtypes ) );
@@ -364,7 +364,7 @@
 
 	// Check whether we need to reinsert singleton dimensions which can be useful for broadcasting the returned output array to the shape of the original input array...
 	if ( opts.keepdims ) {
-		z = spreadDimensions( N, z, idx );
+		z = spreadDimensions( N, z, idx, false );
 	}
 	return z;
 });
@@ -416,7 +416,7 @@
 * var y = new ndarray( 'generic', ybuf, [ ybuf.length ], [ 1 ], 0, 'row-major' );
 *
 * var zbuf = [ 0.0 ];
 * var z = new ndarray( 'generic', zbuf, [], [ 0 ], 0, 'row-major' );
 *
 * var out = dot.assign( x, y, z );
 * // returns <ndarray>

lib/node_modules/@stdlib/ndarray/base/spread-dimensions/README.md

@@ -40,7 +40,7 @@ limitations under the License.
 var spreadDimensions = require( '@stdlib/ndarray/base/spread-dimensions' );
 ```
 
-#### spreadDimensions( ndims, x, dims )
+#### 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.
 
@@ -53,7 +53,7 @@ var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 // returns <ndarray>
 
 // Prepend a singleton dimension:
-var y = spreadDimensions( 3, x, [ 1, 2 ] );
+var y = spreadDimensions( 3, x, [ 1, 2 ], false );
 // returns <ndarray>
 
 var sh = y.shape;
@@ -63,7 +63,7 @@ var a = ndarray2array( y );
 // returns [ [ [ 1, 2 ], [ 3, 4 ] ] ]
 
 // Append a singleton dimension:
-y = spreadDimensions( 3, x, [ 0, 1 ] );
+y = spreadDimensions( 3, x, [ 0, 1 ], false );
 // returns <ndarray>
 
 sh = y.shape;
@@ -73,7 +73,7 @@ a = ndarray2array( y );
 // returns [ [ [ 1 ], [ 2 ] ], [ [ 3 ], [ 4 ] ] ]
 
 // Insert a singleton dimension:
-y = spreadDimensions( 3, x, [ 0, 2 ] );
+y = spreadDimensions( 3, x, [ 0, 2 ], false );
 // returns <ndarray>
 
 sh = y.shape;
@@ -83,6 +83,13 @@ 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.
+
 </section>
 
 <!-- /.usage -->
@@ -95,6 +102,7 @@ a = ndarray2array( y );
 
 -   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.
 
 </section>
 
@@ -121,7 +129,7 @@ var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
 // returns <ndarray>
 
 // Spread dimensions:
-var y = spreadDimensions( 5, x, [ 1, 3 ] );
+var y = spreadDimensions( 5, x, [ 1, 3 ], false );
 // returns <ndarray>
 
 // Retrieve the shape:

lib/node_modules/@stdlib/ndarray/base/spread-dimensions/benchmark/benchmark.js

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

lib/node_modules/@stdlib/ndarray/base/spread-dimensions/benchmark/benchmark.ndims.js

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

lib/node_modules/@stdlib/ndarray/base/spread-dimensions/docs/repl.txt

@@ -1,5 +1,5 @@
 
-{{alias}}( ndims, x, dims )
+{{alias}}( 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.
@@ -22,6 +22,11 @@
         Dimension indices specifying where to place the dimensions of the input
         array. Must resolve to normalized indices arranged in ascending order.
 
+    writable: boolean
+        Boolean indicating whether a returned ndarray should be writable. This
+        parameter only applies to ndarray constructors which support read-only
+        instances.
+
     Returns
     -------
     out: ndarray
@@ -33,7 +38,7 @@
     <ndarray>
     > var sh = x.shape
     [ 2, 2 ]
-    > var y = {{alias}}( 5, x, [ 1, 3 ] )
+    > var y = {{alias}}( 5, x, [ 1, 3 ], false )
     <ndarray>
     > sh = y.shape
     [ 1, 2, 1, 2, 1 ]

lib/node_modules/@stdlib/ndarray/base/spread-dimensions/docs/types/index.d.ts

@@ -34,6 +34,7 @@ import { Collection } from '@stdlib/types/array';
 * @param ndims - number of dimensions in the output array
 * @param x - input array
 * @param dims - dimension indices
+* @param writable - boolean indicating whether a returned array should be writable
 * @returns output array
 *
 * @example
@@ -45,7 +46,7 @@ import { Collection } from '@stdlib/types/array';
 * var shx = x.shape;
 * // returns [ 2, 2 ]
 *
-* var y = spreadDimensions( 5, x, [ 1, 3 ] );
+* var y = spreadDimensions( 5, x, [ 1, 3 ], false );
 * // returns <ndarray>
 *
 * var shy = y.shape;
@@ -63,7 +64,7 @@ import { Collection } from '@stdlib/types/array';
 * v = y.get( 0, 1, 0, 1, 0 );
 * // returns 4
 */
-declare function spreadDimensions<T extends ndarray>( ndims: number, x: T, dims: Collection<number> ): T;
+declare function spreadDimensions<T extends ndarray>( ndims: number, x: T, dims: Collection<number>, writable: boolean ): T;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/ndarray/base/spread-dimensions/docs/types/test.ts

@@ -27,52 +27,67 @@ import spreadDimensions = require( './index' );
 {
 	const x = zeros( [ 2, 2 ] );
 
-	spreadDimensions( 5, x, [ 1, 3 ] ); // $ExpectType float64ndarray
+	spreadDimensions( 5, x, [ 1, 3 ], false ); // $ExpectType float64ndarray
 }
 
-// The compiler throws an error if the function is not provided a first argument which is a number...
+// The compiler throws an error if the function is provided a first argument which is not a number...
 {
 	const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 
-	spreadDimensions( '5', x, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( true, x, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( false, x, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( null, x, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( {}, x, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( [ '5' ], x, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( ( x: number ): number => x, x, [ 1, 3 ] ); // $ExpectError
+	spreadDimensions( '5', x, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( true, x, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( false, x, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( null, x, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( {}, x, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( [ '5' ], x, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( ( x: number ): number => x, x, [ 1, 3 ], false ); // $ExpectError
 }
 
-// The compiler throws an error if the function is not provided a second argument which is an ndarray...
+// The compiler throws an error if the function is provided a second argument which is not an ndarray...
 {
-	spreadDimensions( 5, '5', [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( 5, 5, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( 5, true, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( 5, false, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( 5, null, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( 5, {}, [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( 5, [ '5' ], [ 1, 3 ] ); // $ExpectError
-	spreadDimensions( 5, ( x: number ): number => x, [ 1, 3 ] ); // $ExpectError
+	spreadDimensions( 5, '5', [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( 5, 5, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( 5, true, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( 5, false, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( 5, null, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( 5, {}, [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( 5, [ '5' ], [ 1, 3 ], false ); // $ExpectError
+	spreadDimensions( 5, ( x: number ): number => x, [ 1, 3 ], false ); // $ExpectError
 }
 
-// The compiler throws an error if the function is not provided a third argument which is an array of numbers...
+// The compiler throws an error if the function is provided a third argument which is not an array of numbers...
 {
 	const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 
-	spreadDimensions( 5, x, '5' ); // $ExpectError
-	spreadDimensions( 5, x, true ); // $ExpectError
-	spreadDimensions( 5, x, false ); // $ExpectError
-	spreadDimensions( 5, x, null ); // $ExpectError
-	spreadDimensions( 5, x, {} ); // $ExpectError
-	spreadDimensions( 5, x, [ '5' ] ); // $ExpectError
-	spreadDimensions( 5, x, ( x: number ): number => x ); // $ExpectError
+	spreadDimensions( 5, x, '5', false ); // $ExpectError
+	spreadDimensions( 5, x, true, false ); // $ExpectError
+	spreadDimensions( 5, x, false, false ); // $ExpectError
+	spreadDimensions( 5, x, null, false ); // $ExpectError
+	spreadDimensions( 5, x, {}, false ); // $ExpectError
+	spreadDimensions( 5, x, [ '5' ], false ); // $ExpectError
+	spreadDimensions( 5, x, ( x: number ): number => x, false ); // $ExpectError
 }
 
+// The compiler throws an error if the function is provided a fourth argument which is not a boolean...
+{
+	const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
+
+	spreadDimensions( 5, x, '5', false ); // $ExpectError
+	spreadDimensions( 5, x, true, false ); // $ExpectError
+	spreadDimensions( 5, x, false, false ); // $ExpectError
+	spreadDimensions( 5, x, null, false ); // $ExpectError
+	spreadDimensions( 5, x, {}, false ); // $ExpectError
+	spreadDimensions( 5, x, [ '5' ], false ); // $ExpectError
+	spreadDimensions( 5, x, ( x: number ): number => x, false ); // $ExpectError
+}
+
+
 // The compiler throws an error if the function is provided an unsupported number of arguments...
 {
 	const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 
 	spreadDimensions(); // $ExpectError
 	spreadDimensions( 5, x ); // $ExpectError
-	spreadDimensions( 5, x, [ 1, 3 ], {} ); // $ExpectError
+	spreadDimensions( 5, x, [ 1, 3 ] ); // $ExpectError
+	spreadDimensions( 5, x, [ 1, 3 ], false, {} ); // $ExpectError
 }

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

@@ -30,7 +30,7 @@ var x = array( [ [ 1, 2 ], [ 3, 4 ] ], {
 // returns <ndarray>
 
 // Spread dimensions:
-var y = spreadDimensions( 5, x, [ 1, 3 ] );
+var y = spreadDimensions( 5, x, [ 1, 3 ], false );
 // returns <ndarray>
 
 // Retrieve the shape:

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

@@ -33,7 +33,7 @@
 * var shx = x.shape;
 * // returns [ 2, 2 ]
 *
-* var y = spreadDimensions( 5, x, [ 1, 3 ] );
+* var y = spreadDimensions( 5, x, [ 1, 3 ], false );
 * // returns <ndarray>
 *
 * var shy = y.shape;

lib/node_modules/@stdlib/ndarray/base/spread-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 isSortedAscending = require( '@stdlib/array/base/assert/is-sorted-ascending' );
 var toNormalizedIndices = require( '@stdlib/ndarray/base/to-unique-normalized-indices' );
 var getDType = require( '@stdlib/ndarray/base/dtype' );
@@ -48,6 +47,7 @@ var format = require( '@stdlib/string/format' );
 * @param {NonNegativeInteger} ndims - number of dimensions in the output array
 * @param {ndarray} x - input array
 * @param {IntegerArray} dims - dimension indices at which to spread array dimensions
+* @param {boolean} writable - boolean indicating whether a returned array should be writable
 * @throws {RangeError} first argument must be greater than or equal to the number of dimensions in the input array
 * @throws {RangeError} must provide the same number of dimension indices as the number of dimensions in the input array
 * @throws {RangeError} must provide valid dimension indices
@@ -64,7 +64,7 @@ var format = require( '@stdlib/string/format' );
 * var shx = x.shape;
 * // returns [ 2, 2 ]
 *
-* var y = spreadDimensions( 5, x, [ 1, 3 ] );
+* var y = spreadDimensions( 5, x, [ 1, 3 ], false );
 * // returns <ndarray>
 *
 * var shy = y.shape;
@@ -82,7 +82,7 @@ var format = require( '@stdlib/string/format' );
 * v = y.get( 0, 1, 0, 1, 0 );
 * // returns 4
 */
-function spreadDimensions( ndims, x, dims ) {
+function spreadDimensions( ndims, x, dims, writable ) {
 	var strides;
 	var shape;
 	var isrm;
@@ -151,13 +151,9 @@ function spreadDimensions( ndims, x, dims ) {
 			strides.push( s );
 		}
 	}
-	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
+	});
 }