diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/README.md b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/README.md index b4140d94c29b..d011628becb9 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/README.md +++ b/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 +// returns [ [ 1, 2 ], [ 3, 4 ] ] // Prepend singleton dimensions: -var y = prependSingletonDimensions( x, 3 ); -// returns - -var sh = y.shape; -// returns [ 1, 1, 1, 2, 2 ] +var y = prependSingletonDimensions( x, 3, false ); +// returns [ [ [ [ 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. + @@ -86,31 +89,15 @@ var sh = y.shape; ```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 - -// Prepend singleton dimensions: -var y = prependSingletonDimensions( x, 3 ); -// returns - -// 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 ) ); ``` diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/benchmark/benchmark.js b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/benchmark/benchmark.js index 1e948e8293bd..f04ab31ed533 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-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 = prependSingletonDimensions( values[ i%values.length ], 1 ); + out = prependSingletonDimensions( 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 = prependSingletonDimensions( values[ i%values.length ], 1 ); + out = prependSingletonDimensions( values[ i%values.length ], 1, false ); if ( typeof out !== 'object' ) { b.fail( 'should return an object' ); } diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/benchmark/benchmark.ndims.js b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/benchmark/benchmark.ndims.js index 0cbe77b68f04..b6fb8b97de2f 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/benchmark/benchmark.ndims.js +++ b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/benchmark/benchmark.ndims.js @@ -52,7 +52,7 @@ function createBenchmark( ndims ) { 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' ); } diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/repl.txt b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/repl.txt index c4304fe10df2..7ef71c014209 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/repl.txt +++ b/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 ] ] ) - - > var sh = x.shape - [ 2, 2 ] - > var y = {{alias}}( x, 3 ) - - > 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 + [ [ 1, 2 ], [ 3, 4 ] ] + > var y = {{alias}}( x, 3, false ) + [ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ] See Also -------- diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/types/index.d.ts index ccf1ef622a4e..2fde4ed37896 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/types/index.d.ts +++ b/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 +* // returns [ [ 1, 2 ], [ 3, 4 ] ] * -* var shx = x.shape; -* // returns [ 2, 2 ] -* -* var y = prependSingletonDimensions( x, 3 ); -* // returns -* -* 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 [ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ] */ -declare function prependSingletonDimensions( x: ndarray, n: number ): ndarray; +declare function prependSingletonDimensions( x: ndarray, n: number, writable: boolean ): ndarray; // EXPORTS // diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/types/test.ts b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/types/test.ts index 38350b3b6844..8546d3eeda00 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/docs/types/test.ts +++ b/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 } diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/examples/index.js b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/examples/index.js index e54ce33f5978..6102ead4500c 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/examples/index.js +++ b/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 +var x = uniform( [ 3, 3, 3 ], -10.0, 10.0 ); +console.log( ndarray2array( x ) ); -// Prepend singleton dimensions: -var y = prependSingletonDimensions( x, 3 ); -// returns - -// 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 ) ); diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/lib/index.js b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/lib/index.js index c58ef690fc43..eb0c03e9604a 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/lib/index.js +++ b/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 +* // returns [ [ 1, 2 ], [ 3, 4 ] ] * -* var shx = x.shape; -* // returns [ 2, 2 ] -* -* var y = prependSingletonDimensions( x, 3 ); -* // returns -* -* 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 [ [ [ [ [ 1, 2 ], [ 3, 4 ] ] ] ] ] */ // MODULES // diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/lib/main.js b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/lib/main.js index be6dace6c1ce..9b2bb36c06ae 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/lib/main.js +++ b/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 +* // returns [ [ 1, 2 ], [ 3, 4 ] ] * -* var shx = x.shape; -* // returns [ 2, 2 ] -* -* var y = prependSingletonDimensions( x, 3 ); -* // returns -* -* 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 [ [ [ [ [ 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 + }); } diff --git a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/test/test.js b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/test/test.js index 2bcaf8e8b443..2ae2230b8b06 100644 --- a/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/test/test.js +++ b/lib/node_modules/@stdlib/ndarray/base/prepend-singleton-dimensions/test/test.js @@ -41,11 +41,19 @@ tape( 'the function prepends singleton dimensions', function test( t ) { x = array( [ [ 1, 2 ], [ 3, 4 ] ] ); - y = prependSingletonDimensions( x, 3 ); + y = prependSingletonDimensions( x, 3, false ); t.notEqual( y, x, 'returns expected value' ); t.deepEqual( y.shape, [ 1, 1, 1, 2, 2 ], 'returns expected value' ); t.strictEqual( y.data, x.data, 'returns expected value' ); + t.strictEqual( isReadOnly( y ), true, 'returns expected value' ); + + y = prependSingletonDimensions( x, 3, true ); + + t.notEqual( y, x, 'returns expected value' ); + t.deepEqual( y.shape, [ 1, 1, 1, 2, 2 ], 'returns expected value' ); + t.strictEqual( y.data, x.data, 'returns expected value' ); + t.strictEqual( isReadOnly( y ), false, 'returns expected value' ); t.end(); }); @@ -55,7 +63,7 @@ tape( 'the function prepends singleton dimensions (base; row-major)', function t var y; x = ndarray( 'generic', [ 1, 2, 3, 4 ], [ 2, 1, 2 ], [ 2, 2, 1 ], 0, 'row-major' ); - y = prependSingletonDimensions( x, 3 ); + y = prependSingletonDimensions( x, 3, false ); t.notEqual( y, x, 'returns expected value' ); t.deepEqual( y.shape, [ 1, 1, 1, 2, 1, 2 ], 'returns expected value' ); @@ -70,7 +78,7 @@ tape( 'the function prepends singleton dimensions (base; column-major)', functio var y; x = ndarray( 'generic', [ 1, 2, 3, 4 ], [ 2, 1, 2 ], [ 1, 2, 2 ], 0, 'column-major' ); - y = prependSingletonDimensions( x, 3 ); + y = prependSingletonDimensions( x, 3, false ); t.notEqual( y, x, 'returns expected value' ); t.deepEqual( y.shape, [ 1, 1, 1, 2, 1, 2 ], 'returns expected value' ); @@ -79,56 +87,3 @@ tape( 'the function prepends singleton dimensions (base; column-major)', functio t.end(); }); - -tape( 'if provided a read-only array, the function returns a read-only array', function test( t ) { - var x; - var y; - - x = array( [ 1, 2, 3, 4 ], { - 'shape': [ 2, 1, 2 ], - 'readonly': true - }); - - y = prependSingletonDimensions( x, 2 ); - - t.notEqual( y, x, 'returns expected value' ); - t.deepEqual( y.shape, [ 1, 1, 2, 1, 2 ], 'returns expected value' ); - t.strictEqual( y.data, x.data, 'returns expected value' ); - t.strictEqual( isReadOnly( y ), true, 'returns expected value' ); - - t.end(); -}); - -tape( 'if provided a writable array, the function returns a writable array', function test( t ) { - var x; - var y; - - x = array( [ 1, 2, 3, 4 ], { - 'shape': [ 2, 1, 2 ], - 'readonly': false - }); - - y = prependSingletonDimensions( x, 1 ); - - t.notEqual( y, x, 'returns expected value' ); - t.deepEqual( y.shape, [ 1, 2, 1, 2 ], 'returns expected value' ); - t.strictEqual( y.data, x.data, 'returns expected value' ); - t.strictEqual( isReadOnly( y ), false, 'returns expected value' ); - - t.end(); -}); - -tape( 'if provided a writable array, the function returns a writable array (base)', function test( t ) { - var x; - var y; - - x = ndarray( 'generic', [ 1, 2, 3, 4 ], [ 2, 1, 2 ], [ 2, 2, 1 ], 0, 'row-major' ); - y = prependSingletonDimensions( x, 4 ); - - t.notEqual( y, x, 'returns expected value' ); - t.deepEqual( y.shape, [ 1, 1, 1, 1, 2, 1, 2 ], 'returns expected value' ); - t.strictEqual( y.data, x.data, 'returns expected value' ); - t.strictEqual( isReadOnly( y ), false, 'returns expected value' ); - - t.end(); -});