diff --git a/lib/node_modules/@stdlib/ndarray/flatten/README.md b/lib/node_modules/@stdlib/ndarray/flatten/README.md index 156801cd8799..b956b26039e0 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten/README.md +++ b/lib/node_modules/@stdlib/ndarray/flatten/README.md @@ -72,6 +72,8 @@ The function accepts the following options: - **depth**: maximum number of input [ndarray][@stdlib/ndarray/ctor] dimensions to flatten. +- **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having the same [data type][@stdlib/ndarray/dtypes] as a provided input [ndarray][@stdlib/ndarray/ctor]. + By default, the function flattens all dimensions of the input [ndarray][@stdlib/ndarray/ctor]. To flatten to a desired depth, specify the `depth` option. ```javascript @@ -108,6 +110,28 @@ var arr = ndarray2array( y ); // returns [ 1.0, 3.0, 5.0, 2.0, 4.0, 6.0 ] ``` +By default, the output ndarray [data type][@stdlib/ndarray/dtypes] is inferred from the input [ndarray][@stdlib/ndarray/ctor]. To return an ndarray with a different [data type][@stdlib/ndarray/dtypes], specify the `dtype` option. + +```javascript +var array = require( '@stdlib/ndarray/array' ); +var dtype = require( '@stdlib/ndarray/dtype' ); +var ndarray2array = require( '@stdlib/ndarray/to-array' ); + +var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] ); +// returns + +var y = flatten( x, { + 'dtype': 'float32' +}); +// returns + +var dt = dtype( y ); +// returns 'float32' + +var arr = ndarray2array( y ); +// returns [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] +``` + @@ -164,6 +188,8 @@ console.log( ndarray2array( y ) ); [@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/ctor +[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/dtypes + [@stdlib/ndarray/orders]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/orders diff --git a/lib/node_modules/@stdlib/ndarray/flatten/docs/repl.txt b/lib/node_modules/@stdlib/ndarray/flatten/docs/repl.txt index 4e2e4208667e..c9647f66f732 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten/docs/repl.txt +++ b/lib/node_modules/@stdlib/ndarray/flatten/docs/repl.txt @@ -29,6 +29,10 @@ Default: 'row-major'. + options.dtype: string (optional) + Output ndarray data type. By default, the function returns an ndarray + having the same data type as the provided input ndarray. + Returns ------- out: ndarray diff --git a/lib/node_modules/@stdlib/ndarray/flatten/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/flatten/docs/types/index.d.ts index e993af9cd32d..788645b37e08 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/ndarray/flatten/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { ndarray, Order } from '@stdlib/types/ndarray'; +import { ndarray, Order, DataType } from '@stdlib/types/ndarray'; /** * Interface defining function options. @@ -50,6 +50,15 @@ interface Options { * - Default: 'row-major'. */ order?: Order | 'same' | 'any'; + + /** + * Output ndarray data type. + * + * ## Notes + * + * - By default, the function returns an ndarray having the same data type as a provided input ndarray. + */ + dtype?: DataType; } /** diff --git a/lib/node_modules/@stdlib/ndarray/flatten/docs/types/test.ts b/lib/node_modules/@stdlib/ndarray/flatten/docs/types/test.ts index bc9d1cf920bc..3c6b702eeb74 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten/docs/types/test.ts +++ b/lib/node_modules/@stdlib/ndarray/flatten/docs/types/test.ts @@ -128,6 +128,30 @@ import flatten = require( './index' ); flatten( zeros( 'generic', [ 2, 2, 2 ], 'row-major' ), { 'order': ( x: number ): number => x } ); // $ExpectError } +// The compiler throws an error if the function is provided a second argument with invalid `dtype` option... +{ + flatten( zeros( 'float64', [ 2, 2, 2 ], 'row-major' ), { 'dtype': '5' } ); // $ExpectError + flatten( zeros( 'float64', [ 2, 2, 2 ], 'row-major' ), { 'dtype': true } ); // $ExpectError + flatten( zeros( 'float64', [ 2, 2, 2 ], 'row-major' ), { 'dtype': false } ); // $ExpectError + flatten( zeros( 'float64', [ 2, 2, 2 ], 'row-major' ), { 'dtype': null } ); // $ExpectError + flatten( zeros( 'float64', [ 2, 2, 2 ], 'row-major' ), { 'dtype': [ 1 ] } ); // $ExpectError + flatten( zeros( 'float64', [ 2, 2, 2 ], 'row-major' ), { 'dtype': ( x: number ): number => x } ); // $ExpectError + + flatten( zeros( 'complex128', [ 2, 2, 2 ], 'row-major' ), { 'dtype': '5' } ); // $ExpectError + flatten( zeros( 'complex128', [ 2, 2, 2 ], 'row-major' ), { 'dtype': true } ); // $ExpectError + flatten( zeros( 'complex128', [ 2, 2, 2 ], 'row-major' ), { 'dtype': false } ); // $ExpectError + flatten( zeros( 'complex128', [ 2, 2, 2 ], 'row-major' ), { 'dtype': null } ); // $ExpectError + flatten( zeros( 'complex128', [ 2, 2, 2 ], 'row-major' ), { 'dtype': [ 1 ] } ); // $ExpectError + flatten( zeros( 'complex128', [ 2, 2, 2 ], 'row-major' ), { 'dtype': ( x: number ): number => x } ); // $ExpectError + + flatten( zeros( 'generic', [ 2, 2, 2 ], 'row-major' ), { 'dtype': '5' } ); // $ExpectError + flatten( zeros( 'generic', [ 2, 2, 2 ], 'row-major' ), { 'dtype': true } ); // $ExpectError + flatten( zeros( 'generic', [ 2, 2, 2 ], 'row-major' ), { 'dtype': false } ); // $ExpectError + flatten( zeros( 'generic', [ 2, 2, 2 ], 'row-major' ), { 'dtype': null } ); // $ExpectError + flatten( zeros( 'generic', [ 2, 2, 2 ], 'row-major' ), { 'dtype': [ 1 ] } ); // $ExpectError + flatten( zeros( 'generic', [ 2, 2, 2 ], 'row-major' ), { 'dtype': ( x: number ): number => x } ); // $ExpectError +} + // The compiler throws an error if the function is provided an unsupported number of arguments... { const x = zeros( 'float64', [ 2, 2, 2 ], 'row-major' ); diff --git a/lib/node_modules/@stdlib/ndarray/flatten/lib/main.js b/lib/node_modules/@stdlib/ndarray/flatten/lib/main.js index 9b728c85dc72..53a5f2436d51 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten/lib/main.js +++ b/lib/node_modules/@stdlib/ndarray/flatten/lib/main.js @@ -54,6 +54,7 @@ var COL_MAJOR = 'column-major'; * @param {Options} [options] - function options * @param {NonNegativeInteger} [options.depth] - maximum number of dimensions to flatten * @param {string} [options.order='row-major'] - order in which input ndarray elements should be flattened +* @param {*} [options.dtype] - output ndarray data type * @throws {TypeError} first argument must be an ndarray-like object * @throws {TypeError} options argument must be an object * @throws {TypeError} must provide valid options @@ -296,8 +297,9 @@ function flatten( x, options ) { // Define default options: opts = { - 'depth': xsh.length, // by default, flatten to a one-dimensional ndarray - 'order': ROW_MAJOR // by default, flatten in lexicographic order (i.e., trailing dimensions first; e.g., if `x` is a matrix, flatten row-by-row) + 'depth': xsh.length, // by default, flatten to a one-dimensional ndarray + 'order': ROW_MAJOR, // by default, flatten in lexicographic order (i.e., trailing dimensions first; e.g., if `x` is a matrix, flatten row-by-row) + 'dtype': getDType( x ) }; // Resolve function options... @@ -335,16 +337,21 @@ function flatten( x, options ) { throw new TypeError( format( 'invalid option. `%s` option must be a recognized order. Option: `%s`.', 'order', options.order ) ); } } + if ( hasOwnProp( options, 'dtype' ) ) { + // Delegate `dtype` validation to `emptyLike` during output array creation: + opts.dtype = options.dtype; + } } // Create an output ndarray having contiguous memory: y = emptyLike( x, { 'shape': flattenShape( xsh, opts.depth ), - 'order': opts.order + 'order': opts.order, + 'dtype': opts.dtype }); // Create a view on top of output ndarray having the same shape as the input ndarray: st = ( xsh.length > 0 ) ? shape2strides( xsh, opts.order ) : [ 0 ]; - view = ndarray( getDType( y ), getData( y ), xsh, st, 0, opts.order ); + view = ndarray( opts.dtype, getData( y ), xsh, st, 0, opts.order ); // Copy elements to the output ndarray: assign( [ x, view ] ); diff --git a/lib/node_modules/@stdlib/ndarray/flatten/test/test.js b/lib/node_modules/@stdlib/ndarray/flatten/test/test.js index 02a079145248..2a4331d84ade 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten/test/test.js +++ b/lib/node_modules/@stdlib/ndarray/flatten/test/test.js @@ -191,6 +191,39 @@ tape( 'the function throws an error if provided an invalid `order` option', func } }); +tape( 'the function throws an error if provided an invalid `dtype` option', function test( t ) { + var values; + var i; + + values = [ + 'foo', + 'bar', + 1, + NaN, + true, + false, + void 0, + null, + [], + {}, + function noop() {} + ]; + + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[i] ), TypeError, 'throws an error when provided '+ values[i] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + var opts = { + 'dtype': value + }; + flatten( zeros( [ 2 ] ), opts ); + }; + } +}); + tape( 'by default, the function flattens all dimensions of a provided input ndarray in lexicographic order (row-major, contiguous)', function test( t ) { var expected; var xbuf;