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

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`.
 
@@ -49,29 +49,18 @@ var array = require( '@stdlib/ndarray/array' );
 
 // Create a 2x2 ndarray:
 var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
-// returns <ndarray>
+// returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
 
 // Prepend a singleton dimension:
-var y = expandDimensions( x, 0 );
-// returns <ndarray>
-
-var sh = y.shape;
-// returns [ 1, 2, 2 ]
-
-// Append a singleton dimension:
-y = expandDimensions( x, 2 );
-// returns <ndarray>
-
-sh = y.shape;
-// returns [ 2, 2, 1 ]
+var y = expandDimensions( x, 0, false );
+// returns <ndarray>[ [ [ 1, 2 ], [ 3, 4 ] ] ]
+```
 
-// Insert a singleton dimension:
-y = expandDimensions( x, 1 );
-// returns <ndarray>
+The function accepts the following arguments:
 
-sh = y.shape;
-// returns [ 2, 1, 2 ]
-```
+-   **x**: input ndarray.
+-   **axis**: axis at which to insert a singleton dimension
+-   **writable**: boolean indicating whether a returned ndarray should be writable.
 
 </section>
 
@@ -84,6 +73,7 @@ sh = y.shape;
 ## 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>
 
@@ -108,7 +98,7 @@ var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 // returns <ndarray>
 
 // Insert a singleton dimension:
-var y = expandDimensions( x, 1 );
+var y = expandDimensions( x, 1, false );
 // returns <ndarray>
 
 // Retrieve the shape:

lib/node_modules/@stdlib/ndarray/base/expand-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 = expandDimensions( values[ i%values.length ], 1 );
+		out = expandDimensions( 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 = 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 @@
 
 		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' );
 			}
@@ -87,7 +87,7 @@
 
 	for ( i = min; i <= max; i++ ) {
 		f = createBenchmark( i );
 		bench( pkg+'::ndarray:ndims='+i, f );
 	}
 }
 

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.
 
@@ -19,6 +19,9 @@
     axis: integer
         Axis at which to insert a singleton dimension.
 
+    writable: boolean
+        Boolean indicating whether a returned ndarray should be writable.
+
     Returns
     -------
     out: ndarray
@@ -30,7 +33,7 @@
     <ndarray>
     > var sh = x.shape
     [ 2, 2 ]
-    > var y = {{alias}}( x, 1 )
+    > var y = {{alias}}( x, 1, false )
     <ndarray>
     > sh = y.shape
     [ 2, 1, 2 ]

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

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

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

@@ -26,32 +26,43 @@ import expandDimensions = require( './index' );
 {
 	const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 
-	expandDimensions( x, 1 ); // $ExpectType ndarray
+	expandDimensions( x, 1, false ); // $ExpectType ndarray
 }
 
 // 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( 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 = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 
-	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, 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 = array( [ [ 1, 2 ], [ 3, 4 ] ] );
+
+	expandDimensions( x, 1, '5' ); // $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 +71,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, [ 2, 3 ] ); // $ExpectError
 }

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

@@ -28,7 +28,7 @@ var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 // returns <ndarray>
 
 // Insert a singleton dimension:
-var y = expandDimensions( x, 1 );
+var y = expandDimensions( x, 1, false );
 // returns <ndarray>
 
 // Retrieve the shape:

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

@@ -28,28 +28,10 @@
 * var expandDimensions = require( '@stdlib/ndarray/base/expand-dimensions' );
 *
 * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
-* // returns <ndarray>
+* // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
 *
-* var shx = x.shape;
-* // returns [ 2, 2 ]
-*
-* var y = expandDimensions( x, 1 );
-* // returns <ndarray>
-*
-* var shy = y.shape;
-* // returns [ 2, 1, 2 ]
-*
-* var v = y.get( 0, 0, 0 );
-* // returns 1
-*
-* v = y.get( 0, 0, 1 );
-* // returns 2
-*
-* v = y.get( 1, 0, 0 );
-* // returns 3
-*
-* v = y.get( 1, 0, 1 );
-* // returns 4
+* var y = expandDimensions( x, 1, false );
+* // returns <ndarray>[ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
 */
 
 // 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,37 +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 a returned array should be writable
 * @throws {RangeError} must provide a valid axis
 * @returns {ndarray} output array
 *
 * @example
 * var array = require( '@stdlib/ndarray/array' );
 *
 * var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
-* // returns <ndarray>
+* // returns <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
 *
-* var shx = x.shape;
-* // returns [ 2, 2 ]
-*
-* var y = expandDimensions( x, 1 );
-* // returns <ndarray>
-*
-* var shy = y.shape;
-* // returns [ 2, 1, 2 ]
-*
-* var v = y.get( 0, 0, 0 );
-* // returns 1
-*
-* v = y.get( 0, 0, 1 );
-* // returns 2
-*
-* v = y.get( 1, 0, 0 );
-* // returns 3
-*
-* v = y.get( 1, 0, 1 );
-* // returns 4
+* var y = expandDimensions( x, 1, false );
+* // returns <ndarray>[ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ]
 */
-function expandDimensions( x, axis ) {
+function expandDimensions( x, axis, writable ) {
 	var strides;
 	var shape;
 	var isrm;
@@ -143,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
+	});
 }