feat: add writable parameter to ndarray/base/prepend-singleton-dimensions

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

@@ -42,7 +42,7 @@ limitations under the License.
 var prependSingletonDimensions = require( '@stdlib/ndarray/base/prepend-singleton-dimensions' );
 ```
 
-#### prependSingletonDimensions( x, n )
+#### prependSingletonDimensions( x, n, writable )
 
 Returns an ndarray with a specified number of prepended singleton dimensions (i.e., dimensions whose size is equal to `1`).
 
@@ -53,16 +53,19 @@ 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 singleton dimensions:
-var y = prependSingletonDimensions( x, 3 );
-// returns <ndarray>
-
-var sh = y.shape;
-// returns [ 1, 1, 1, 2, 2 ]
+var y = prependSingletonDimensions( x, 3, false );
+// returns <ndarray>[ [ [ [ 1, 2 ] ], [ [ 3, 4 ] ] ] ]
 ```
 
+The function accepts the following arguments:
+
+-   **x**: input ndarray.
+-   **n**: number of singleton dimensions to prepend.
+-   **writable**: boolean indicating whether a returned ndarray should be writable.
+
 </section>
 
 <!-- /.usage -->
@@ -86,31 +89,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 prependSingletonDimensions = require( '@stdlib/ndarray/base/prepend-singleton-dimensions' );
 
-// Create a 2-dimensional array:
-var x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
-// returns <ndarray>
-
-// Prepend singleton dimensions:
-var y = prependSingletonDimensions( x, 3 );
-// returns <ndarray>
-
-// Retrieve the shape:
-var sh = y.shape;
-// returns [ 1, 1, 1, 2, 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 = prependSingletonDimensions( x, 3, false );
+console.log( ndarray2array( y ) );
 ```
 
 </section>

lib/node_modules/@stdlib/ndarray/base/prepend-singleton-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 = prependSingletonDimensions( values[ i%values.length ], 1 );
+		out = prependSingletonDimensions( 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 = prependSingletonDimensions( values[ i%values.length ], 1 );
+		out = prependSingletonDimensions( values[ i%values.length ], 1, false );
 		if ( typeof out !== 'object' ) {
 			b.fail( 'should return an object' );
 		}

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

@@ -52,7 +52,7 @@
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			out = prependSingletonDimensions( x, ndims );
+			out = prependSingletonDimensions( x, ndims, false );
 			if ( typeof out !== 'object' ) {
 				b.fail( 'should return an object' );
 			}
@@ -85,7 +85,7 @@
 
 	for ( i = min; i <= max; i++ ) {
 		f = createBenchmark( i );
 		bench( pkg+'::ndarray,2d:singleton_dimensions='+i, f );
 	}
 }
 

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

@@ -1,5 +1,5 @@
 
-{{alias}}( x, n )
+{{alias}}( x, n, writable )
     Returns an array with a specified number of prepended singleton dimensions.
 
     Parameters
@@ -10,6 +10,9 @@
     n: integer
         Number of singleton dimensions to prepend.
 
+    writable: boolean
+        Boolean indicating whether a returned array should be writable.
+
     Returns
     -------
     out: ndarray
@@ -18,21 +21,9 @@
     Examples
     --------
     > var x = {{alias:@stdlib/ndarray/array}}( [ [ 1, 2 ], [ 3, 4 ] ] )
-    <ndarray>
-    > var sh = x.shape
-    [ 2, 2 ]
-    > var y = {{alias}}( x, 3 )
-    <ndarray>
-    > sh = y.shape
-    [ 1, 1, 1, 2, 2 ]
-    > var v = y.get( 0, 0, 0, 0, 0 )
-    1
-    > v = y.get( 0, 0, 0, 0, 1 )
-    2
-    > v = y.get( 0, 0, 0, 1, 0 )
-    3
-    > v = y.get( 0, 0, 0, 1, 1 )
-    4
+    <ndarray>[ [ 1, 2 ], [ 3, 4 ] ]
+    > var y = {{alias}}( x, 3, false )
+    <ndarray>[ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ]
 
     See Also
     --------

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

@@ -27,36 +27,19 @@ import { ndarray } from '@stdlib/types/ndarray';
 *
 * @param x - input array
 * @param n - number of singleton dimensions to prepend
+* @param writable - boolean indicating whether a returned array 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 = prependSingletonDimensions( x, 3 );
-* // returns <ndarray>
-*
-* var shy = y.shape;
-* // returns [ 1, 1, 1, 2, 2 ]
-*
-* var v = y.get( 0, 0, 0, 0, 0 );
-* // returns 1
-*
-* v = y.get( 0, 0, 0, 0, 1 );
-* // returns 2
-*
-* v = y.get( 0, 0, 0, 1, 0 );
-* // returns 3
-*
-* v = y.get( 0, 0, 0, 1, 1 );
-* // returns 4
+* var y = prependSingletonDimensions( x, 3, false );
+* // returns <ndarray>[ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ]
 */
-declare function prependSingletonDimensions( x: ndarray, n: number ): ndarray;
+declare function prependSingletonDimensions( x: ndarray, n: number, writable: boolean ): ndarray;
 
 
 // EXPORTS //

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

@@ -26,32 +26,44 @@ import prependSingletonDimensions = require( './index' );
 {
 	const x = array( [ [ 1, 2 ], [ 3, 4 ] ] );
 
-	prependSingletonDimensions( x, 3 ); // $ExpectType ndarray
+	prependSingletonDimensions( x, 3, false ); // $ExpectType ndarray
 }
 
 // The compiler throws an error if the function is not provided a first argument which is an ndarray...
 {
-	prependSingletonDimensions( '5', 3 ); // $ExpectError
-	prependSingletonDimensions( 5, 3 ); // $ExpectError
-	prependSingletonDimensions( true, 3 ); // $ExpectError
-	prependSingletonDimensions( false, 3 ); // $ExpectError
-	prependSingletonDimensions( null, 3 ); // $ExpectError
-	prependSingletonDimensions( {}, 3 ); // $ExpectError
-	prependSingletonDimensions( [ '5' ], 3 ); // $ExpectError
-	prependSingletonDimensions( ( x: number ): number => x, 3 ); // $ExpectError
+	prependSingletonDimensions( '5', 3, false ); // $ExpectError
+	prependSingletonDimensions( 5, 3, false ); // $ExpectError
+	prependSingletonDimensions( true, 3, false ); // $ExpectError
+	prependSingletonDimensions( false, 3, false ); // $ExpectError
+	prependSingletonDimensions( null, 3, false ); // $ExpectError
+	prependSingletonDimensions( {}, 3, false ); // $ExpectError
+	prependSingletonDimensions( [ '5' ], 3, false ); // $ExpectError
+	prependSingletonDimensions( ( x: number ): number => x, 3, 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 ] ] );
 
-	prependSingletonDimensions( x, '5' ); // $ExpectError
-	prependSingletonDimensions( x, true ); // $ExpectError
-	prependSingletonDimensions( x, false ); // $ExpectError
-	prependSingletonDimensions( x, null ); // $ExpectError
-	prependSingletonDimensions( x, {} ); // $ExpectError
-	prependSingletonDimensions( x, [ '5' ] ); // $ExpectError
-	prependSingletonDimensions( x, ( x: number ): number => x ); // $ExpectError
+	prependSingletonDimensions( x, '5', false ); // $ExpectError
+	prependSingletonDimensions( x, true, false ); // $ExpectError
+	prependSingletonDimensions( x, false, false ); // $ExpectError
+	prependSingletonDimensions( x, null, false ); // $ExpectError
+	prependSingletonDimensions( x, {}, false ); // $ExpectError
+	prependSingletonDimensions( x, [ '5' ], false ); // $ExpectError
+	prependSingletonDimensions( 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 ] ] );
+
+	prependSingletonDimensions( x, 3, '5' ); // $ExpectError
+	prependSingletonDimensions( x, 3, 5 ); // $ExpectError
+	prependSingletonDimensions( x, 3, null ); // $ExpectError
+	prependSingletonDimensions( x, 3, {} ); // $ExpectError
+	prependSingletonDimensions( x, 3, [ '5' ] ); // $ExpectError
+	prependSingletonDimensions( x, 3, ( x: number ): number => x ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided an unsupported number of arguments...
@@ -60,5 +72,6 @@ import prependSingletonDimensions = require( './index' );
 
 	prependSingletonDimensions(); // $ExpectError
 	prependSingletonDimensions( x ); // $ExpectError
-	prependSingletonDimensions( x, 3, [ 1, 2, 3 ], [ 2, 3 ] ); // $ExpectError
+	prependSingletonDimensions( x, 3 ); // $ExpectError
+	prependSingletonDimensions( x, 3, false, [ 1, 2, 3 ], [ 2, 3 ] ); // $ExpectError
 }

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

@@ -18,28 +18,12 @@
 
 'use strict';
 
-var array = require( '@stdlib/ndarray/array' );
-var numel = require( '@stdlib/ndarray/base/numel' );
-var ind2sub = require( '@stdlib/ndarray/ind2sub' );
-var prependSingletonDimensions = require( './../lib' ); // eslint-disable-line id-length
+var uniform = require( '@stdlib/random/uniform' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var prependSingletonDimensions = 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 ) );
 
-// Prepend singleton dimensions:
-var y = prependSingletonDimensions( x, 3 );
-// returns <ndarray>
-
-// Retrieve the shape:
-var sh = y.shape;
-// returns [ 1, 1, 1, 2, 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 = prependSingletonDimensions( x, 3, false );
+console.log( ndarray2array( y ) );

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

@@ -28,28 +28,10 @@
 * var prependSingletonDimensions = require( '@stdlib/ndarray/base/prepend-singleton-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 = prependSingletonDimensions( x, 3 );
-* // returns <ndarray>
-*
-* var shy = y.shape;
-* // returns [ 1, 1, 1, 2, 2 ]
-*
-* var v = y.get( 0, 0, 0, 0, 0 );
-* // returns 1
-*
-* v = y.get( 0, 0, 0, 0, 1 );
-* // returns 2
-*
-* v = y.get( 0, 0, 0, 1, 0 );
-* // returns 3
-*
-* v = y.get( 0, 0, 0, 1, 1 );
-* // returns 4
+* var y = prependSingletonDimensions( x, 3, false );
+* // returns <ndarray>[ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ]
 */
 
 // MODULES //

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

@@ -20,7 +20,6 @@
 
 // MODULES //
 
-var isReadOnly = require( '@stdlib/ndarray/base/assert/is-read-only' );
 var getDType = require( '@stdlib/ndarray/base/dtype' );
 var getShape = require( '@stdlib/ndarray/base/shape' );
 var getStrides = require( '@stdlib/ndarray/base/strides' );
@@ -36,36 +35,19 @@ var getData = require( '@stdlib/ndarray/base/data-buffer' );
 *
 * @param {ndarray} x - input array
 * @param {NonNegativeInteger} n - number of singleton dimensions to prepend
+* @param {boolean} writable - boolean indicating whether a returned array should be writable
 * @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 = prependSingletonDimensions( x, 3 );
-* // returns <ndarray>
-*
-* var shy = y.shape;
-* // returns [ 1, 1, 1, 2, 2 ]
-*
-* var v = y.get( 0, 0, 0, 0, 0 );
-* // returns 1
-*
-* v = y.get( 0, 0, 0, 0, 1 );
-* // returns 2
-*
-* v = y.get( 0, 0, 0, 1, 0 );
-* // returns 3
-*
-* v = y.get( 0, 0, 0, 1, 1 );
-* // returns 4
+* var y = prependSingletonDimensions( x, 3, false );
+* // returns <ndarray>[ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ]
 */
-function prependSingletonDimensions( x, n ) { // eslint-disable-line id-length
+function prependSingletonDimensions( x, n, writable ) { // eslint-disable-line id-length
 	var strides;
 	var shape;
 	var sh;
@@ -90,13 +72,9 @@ function prependSingletonDimensions( x, n ) { // eslint-disable-line id-length
 		shape.push( sh[ i ] );
 		strides.push( st[ i ] );
 	}
-	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 ), getOrder( x ), { // eslint-disable-line max-len
-			'readonly': true
-		});
-	}
-	return new x.constructor( getDType( x ), getData( x ), shape, strides, getOffset( x ), getOrder( x ) ); // eslint-disable-line max-len
+	return new x.constructor( getDType( x ), getData( x ), shape, strides, getOffset( x ), getOrder( x ), { // eslint-disable-line max-len
+		'readonly': !writable
+	});
 }