feat!: add writable parameter support to ndarray/base/transpose

lib/node_modules/@stdlib/ndarray/base/transpose/README.md

@@ -40,32 +40,29 @@ limitations under the License.
 var transpose = require( '@stdlib/ndarray/base/transpose' );
 ```
 
-#### transpose( x )
+#### transpose( x, writable )
 
 Transposes a matrix (or a stack of matrices) `x`.
 
 ```javascript
+var getData = require( '@stdlib/ndarray/data-buffer' );
 var array = require( '@stdlib/ndarray/array' );
 
 var x = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] );
-// returns <ndarray>
+// returns <ndarray>[ [ 1, 2, 3 ], [ 4, 5, 6 ] ]
 
-var sh = x.shape;
-// returns [ 2, 3 ]
+var y = transpose( x, false );
+// returns <ndarray>[ [ 1, 4 ], [ 2, 5 ], [ 3, 6 ] ]
 
-var y = transpose( x );
-// returns <ndarray>
-
-sh = y.shape;
-// returns [ 3, 2 ]
-
-var bool = ( x.data === y.data );
-// returns true
-
-bool = ( x.get( 0, 1 ) === y.get( 1, 0 ) );
+var bool = ( getData( x ) === getData( y ) );
 // returns true
 ```
 
+The function accepts the following arguments:
+
+-   **x**: input ndarray.
+-   **writable**: boolean indicating whether a returned ndarray should be writable.
+
 </section>
 
 <!-- /.usage -->
@@ -76,8 +73,9 @@ bool = ( x.get( 0, 1 ) === y.get( 1, 0 ) );
 
 ## Notes
 
--   The returned ndarray is a **view** of the input ndarray. Accordingly, writing to the original ndarray will **mutate** the returned ndarray and vice versa. While powerful, this can lead to subtle bugs. In general, one should handle the returned ndarray as **read-only**.
+-   The returned ndarray is a **view** of the input ndarray. Accordingly, writing to the original ndarray will **mutate** the returned ndarray and vice versa.
 -   If provided an ndarray with fewer than two dimensions, the function raises an exception.
+-   The `writable` parameter **only** applies to ndarray constructors supporting **read-only** instances.
 
 </section>
 
@@ -133,7 +131,7 @@ var buf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
 var x = new ndarray( 'float64', buf, [ 2, 2, 3 ], [ 0, 3, 1 ], 0, 'row-major' );
 
 // Transpose the stack of matrices:
-var y = transpose( x );
+var y = transpose( x, false );
 
 // Print the stacks:
 console.log( '' );

lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.js

@@ -23,13 +23,14 @@
 var bench = require( '@stdlib/bench' );
 var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
 var zeros = require( '@stdlib/ndarray/base/zeros' );
+var format = require( '@stdlib/string/format' );
 var pkg = require( './../package.json' ).name;
 var transpose = require( './../lib' );
 
 
 // MAIN //
 
-bench( pkg+'::base:dtype=float64', function benchmark( b ) {
+bench( format( '%s::base:dtype=float64', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -38,7 +39,7 @@ bench( pkg+'::base:dtype=float64', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -51,7 +52,7 @@ bench( pkg+'::base:dtype=float64', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=float32', function benchmark( b ) {
+bench( format( '%s::base:dtype=float32', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -60,7 +61,7 @@ bench( pkg+'::base:dtype=float32', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -73,7 +74,7 @@ bench( pkg+'::base:dtype=float32', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=complex128', function benchmark( b ) {
+bench( format( '%s::base:dtype=complex128', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -82,7 +83,7 @@ bench( pkg+'::base:dtype=complex128', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -95,7 +96,7 @@ bench( pkg+'::base:dtype=complex128', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=complex64', function benchmark( b ) {
+bench( format( '%s::base:dtype=complex64', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -104,7 +105,7 @@ bench( pkg+'::base:dtype=complex64', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -117,7 +118,7 @@ bench( pkg+'::base:dtype=complex64', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=int32', function benchmark( b ) {
+bench( format( '%s::base:dtype=int32', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -126,7 +127,7 @@ bench( pkg+'::base:dtype=int32', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -139,7 +140,7 @@ bench( pkg+'::base:dtype=int32', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=uint32', function benchmark( b ) {
+bench( format( '%s::base:dtype=uint32', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -148,7 +149,7 @@ bench( pkg+'::base:dtype=uint32', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -161,7 +162,7 @@ bench( pkg+'::base:dtype=uint32', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=int16', function benchmark( b ) {
+bench( format( '%s::base:dtype=int16', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -170,7 +171,7 @@ bench( pkg+'::base:dtype=int16', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -183,7 +184,7 @@ bench( pkg+'::base:dtype=int16', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=uint16', function benchmark( b ) {
+bench( format( '%s::base:dtype=uint16', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -192,7 +193,7 @@ bench( pkg+'::base:dtype=uint16', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -205,7 +206,7 @@ bench( pkg+'::base:dtype=uint16', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=int8', function benchmark( b ) {
+bench( format( '%s::base:dtype=int8', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -214,7 +215,7 @@ bench( pkg+'::base:dtype=int8', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -227,7 +228,7 @@ bench( pkg+'::base:dtype=int8', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=uint8', function benchmark( b ) {
+bench( format( '%s::base:dtype=uint8', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -236,7 +237,7 @@ bench( pkg+'::base:dtype=uint8', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -249,7 +250,7 @@ bench( pkg+'::base:dtype=uint8', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=uint8c', function benchmark( b ) {
+bench( format( '%s::base:dtype=uint8c', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -258,7 +259,7 @@ bench( pkg+'::base:dtype=uint8c', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}
@@ -271,7 +272,7 @@ bench( pkg+'::base:dtype=uint8c', function benchmark( b ) {
 	b.end();
 });
 
-bench( pkg+'::base:dtype=generic', function benchmark( b ) {
+bench( format( '%s::base:dtype=generic', pkg ), function benchmark( b ) {
 	var x;
 	var y;
 	var i;
@@ -280,7 +281,7 @@ bench( pkg+'::base:dtype=generic', function benchmark( b ) {
 
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		y = transpose( x );
+		y = transpose( x, false );
 		if ( y.length !== 4 ) {
 			b.fail( 'should have expected length' );
 		}

lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.complex128.js

@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
 var zeros = require( '@stdlib/ndarray/base/zeros' );
+var format = require( '@stdlib/string/format' );
 var pkg = require( './../package.json' ).name;
 var transpose = require( './../lib' );
 
@@ -53,7 +54,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			arr = transpose( x );
+			arr = transpose( x, false );
 			if ( arr.length !== len ) {
 				b.fail( 'unexpected length' );
 			}
@@ -88,7 +89,7 @@ function main() {
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
 		f = createBenchmark( len );
-		bench( pkg+'::base:dtype=complex128,size='+len, f );
+		bench( format( '%s::base:dtype=complex128,size=%d', pkg, len ), f );
 	}
 }
 

lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.complex64.js

@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
 var zeros = require( '@stdlib/ndarray/base/zeros' );
+var format = require( '@stdlib/string/format' );
 var pkg = require( './../package.json' ).name;
 var transpose = require( './../lib' );
 
@@ -53,7 +54,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			arr = transpose( x );
+			arr = transpose( x, false );
 			if ( arr.length !== len ) {
 				b.fail( 'unexpected length' );
 			}
@@ -88,7 +89,7 @@ function main() {
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
 		f = createBenchmark( len );
-		bench( pkg+'::base:dtype=complex64,size='+len, f );
+		bench( format( '%s::base:dtype=complex64,size=%d', pkg, len ), f );
 	}
 }
 

lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.float32.js

@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
 var zeros = require( '@stdlib/ndarray/base/zeros' );
+var format = require( '@stdlib/string/format' );
 var pkg = require( './../package.json' ).name;
 var transpose = require( './../lib' );
 
@@ -53,7 +54,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			arr = transpose( x );
+			arr = transpose( x, false );
 			if ( arr.length !== len ) {
 				b.fail( 'unexpected length' );
 			}
@@ -88,7 +89,7 @@ function main() {
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
 		f = createBenchmark( len );
-		bench( pkg+'::base:dtype=float32,size='+len, f );
+		bench( format( '%s::base:dtype=float32,size=%d', pkg, len ), f );
 	}
 }
 

lib/node_modules/@stdlib/ndarray/base/transpose/benchmark/benchmark.size.float64.js

@@ -24,6 +24,7 @@ var bench = require( '@stdlib/bench' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
 var zeros = require( '@stdlib/ndarray/base/zeros' );
+var format = require( '@stdlib/string/format' );
 var pkg = require( './../package.json' ).name;
 var transpose = require( './../lib' );
 
@@ -53,7 +54,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			arr = transpose( x );
+			arr = transpose( x, false );
 			if ( arr.length !== len ) {
 				b.fail( 'unexpected length' );
 			}
@@ -88,7 +89,7 @@ function main() {
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
 		f = createBenchmark( len );
-		bench( pkg+'::base:dtype=float64,size='+len, f );
+		bench( format( '%s::base:dtype=float64,size=%d', pkg, len ), f );
 	}
 }