diff --git a/lib/node_modules/@stdlib/ndarray/flatten-by/README.md b/lib/node_modules/@stdlib/ndarray/flatten-by/README.md index f4121b083525..09e2f751e4e3 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten-by/README.md +++ b/lib/node_modules/@stdlib/ndarray/flatten-by/README.md @@ -78,6 +78,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 @@ -126,6 +128,33 @@ var arr = ndarray2array( y ); // returns [ 2.0, 6.0, 10.0, 4.0, 8.0, 12.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' ); + +function scale( value ) { + return value * 2.0; +} + +var x = array( [ [ [ 1.0, 2.0 ] ], [ [ 3.0, 4.0 ] ], [ [ 5.0, 6.0 ] ] ] ); +// returns + +var opts = { + 'dtype': 'float32' +}; +var y = flattenBy( x, opts, scale ); +// returns + +var dt = dtype( y ); +// returns 'float32' + +var arr = ndarray2array( y ); +// returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ] +``` + To set the callback function execution context, provide a `thisArg`. @@ -224,6 +253,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-by/docs/repl.txt b/lib/node_modules/@stdlib/ndarray/flatten-by/docs/repl.txt index f6cae4264419..00c968f90a31 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten-by/docs/repl.txt +++ b/lib/node_modules/@stdlib/ndarray/flatten-by/docs/repl.txt @@ -26,6 +26,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. + fcn: Function Callback function. diff --git a/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/index.d.ts b/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/index.d.ts index a97d0924d204..d51cb80a8c3e 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { typedndarray, genericndarray, Order } from '@stdlib/types/ndarray'; +import { typedndarray, genericndarray, Order, DataTypeMap } from '@stdlib/types/ndarray'; import { ComplexLike } from '@stdlib/types/complex'; /** @@ -68,9 +68,9 @@ type Ternary = ( this: ThisArg, value: T, indices: Array = Nullary | Unary | Binary | Ternary; /** -* Interface defining function options. +* Interface defining "base" function options. */ -interface Options { +interface BaseOptions { /** * Maximum number of dimensions to flatten. * @@ -97,6 +97,16 @@ interface Options { order?: Order | 'same' | 'any'; } +/** +* Function options. +*/ +type Options = BaseOptions & { + /** + * Output ndarray data type. + */ + dtype: U; +}; + /** * Flattens an ndarray according to a callback function. * @@ -232,6 +242,7 @@ declare function flattenBy = genericnda * @param options - function options * @param options.depth - maximum number of dimensions to flatten * @param options.order - order in which input ndarray elements should be flattened +* @param options.dtype - output ndarray data type * @param fcn - callback function * @param thisArg - callback execution context * @returns output ndarray @@ -263,7 +274,7 @@ declare function flattenBy = genericnda * var arr = ndarray2array( y ); * // returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ] */ -declare function flattenBy = typedndarray, ThisArg = unknown>( x: T, options: Options, fcn: Callback, thisArg?: ThisParameterType> ): T; +declare function flattenBy = typedndarray, ThisArg = unknown>( x: T, options: BaseOptions, fcn: Callback, thisArg?: ThisParameterType> ): T; /** * Flattens an ndarray according to a callback function. @@ -272,6 +283,7 @@ declare function flattenBy = typedndarray * @param options - function options * @param options.depth - maximum number of dimensions to flatten * @param options.order - order in which input ndarray elements should be flattened +* @param options.dtype - output ndarray data type * @param fcn - callback function * @param thisArg - callback execution context * @returns output ndarray @@ -300,7 +312,7 @@ declare function flattenBy = typedndarray * var y = flattenBy( x, opts, identity ); * // returns */ -declare function flattenBy = typedndarray, ThisArg = unknown>( x: U, options: Options, fcn: Callback, thisArg?: ThisParameterType> ): U; +declare function flattenBy = typedndarray, ThisArg = unknown>( x: U, options: BaseOptions, fcn: Callback, thisArg?: ThisParameterType> ): U; /** * Flattens an ndarray according to a callback function. @@ -309,6 +321,7 @@ declare function flattenBy = typedndarray, ThisArg = unknown>( x: T, options: Options, fcn: Callback, thisArg?: ThisParameterType> ): T; +declare function flattenBy = typedndarray, ThisArg = unknown>( x: T, options: BaseOptions, fcn: Callback, thisArg?: ThisParameterType> ): T; /** * Flattens an ndarray according to a callback function. @@ -349,6 +362,7 @@ declare function flattenBy = typedndarray = typedndarray = genericndarray, V = unknown, W extends genericndarray = genericndarray, ThisArg = unknown>( x: U, options: Options, fcn: Callback, thisArg?: ThisParameterType> ): W; +declare function flattenBy = genericndarray, V = unknown, W extends genericndarray = genericndarray, ThisArg = unknown>( x: U, options: BaseOptions, fcn: Callback, thisArg?: ThisParameterType> ): W; + +/** +* Flattens an ndarray according to a callback function. +* +* @param x - input ndarray +* @param options - function options +* @param options.depth - maximum number of dimensions to flatten +* @param options.order - order in which input ndarray elements should be flattened +* @param options.dtype - output ndarray data type +* @param fcn - callback function +* @param thisArg - callback execution context +* @returns output ndarray +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var ndarray = require( '@stdlib/ndarray/ctor' ); +* var ndarray2array = require( '@stdlib/ndarray/to-array' ); +* +* function scale( value ) { +* return value * 2.0; +* } +* +* var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* var shape = [ 3, 1, 2 ]; +* var strides = [ 2, 2, 1 ]; +* var offset = 0; +* +* var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' ); +* // return +* +* var opts = { +* 'depth': 2 +* }; +* +* var y = flattenBy( x, opts, scale ); +* // returns +* +* var arr = ndarray2array( y ); +* // returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ] +*/ +declare function flattenBy | genericndarray = typedndarray, V = unknown, W extends keyof DataTypeMap = 'generic', ThisArg = unknown>( x: U, options: Options, fcn: Callback, thisArg?: ThisParameterType> ): DataTypeMap[W]; // EXPORTS // diff --git a/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/test.ts b/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/test.ts index d0eec5992d8c..0cd9cbe320e1 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/test.ts +++ b/lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/test.ts @@ -86,6 +86,11 @@ function identity( x: any ): any { flattenBy( zeros( 'generic', sh, ord ), {}, identity ); // $ExpectType genericndarray flattenBy( zeros( 'generic', sh, ord ), identity, {} ); // $ExpectType genericndarray flattenBy( zeros( 'generic', sh, ord ), {}, identity, {} ); // $ExpectType genericndarray + + flattenBy( zeros( 'float64', sh, ord ), { 'dtype': 'float32' }, identity ); // $ExpectType float32ndarray + flattenBy( zeros( 'float64', sh, ord ), { 'dtype': 'generic' }, identity ); // $ExpectType genericndarray + flattenBy( zeros( 'generic', sh, ord ), { 'dtype': 'float64' }, identity ); // $ExpectType float64ndarray + flattenBy( zeros( 'generic', sh, ord ), { 'dtype': 'generic' }, identity ); // $ExpectType genericndarray } // The compiler throws an error if the function is provided a first argument which is not an ndarray... @@ -178,6 +183,23 @@ function identity( x: any ): any { flattenBy( x, { 'order': [ 1 ] }, identity, {} ); // $ExpectError } +// The compiler throws an error if the function is provided a second argument with invalid `dtype` option... +{ + const x = zeros( 'generic', [ 2, 2, 2 ], 'row-major' ); + + flattenBy( x, { 'dtype': '5' }, identity ); // $ExpectError + flattenBy( x, { 'dtype': true }, identity ); // $ExpectError + flattenBy( x, { 'dtype': false }, identity ); // $ExpectError + flattenBy( x, { 'dtype': null }, identity ); // $ExpectError + flattenBy( x, { 'dtype': [ 1 ] }, identity ); // $ExpectError + + flattenBy( x, { 'dtype': '5' }, identity, {} ); // $ExpectError + flattenBy( x, { 'dtype': true }, identity, {} ); // $ExpectError + flattenBy( x, { 'dtype': false }, identity, {} ); // $ExpectError + flattenBy( x, { 'dtype': null }, identity, {} ); // $ExpectError + flattenBy( x, { 'dtype': [ 1 ] }, identity, {} ); // $ExpectError +} + // The compiler throws an error if the function is provided a callback which is not a function... { const x = zeros( 'generic', [ 2, 2 ], 'row-major' ); diff --git a/lib/node_modules/@stdlib/ndarray/flatten-by/lib/main.js b/lib/node_modules/@stdlib/ndarray/flatten-by/lib/main.js index b06674f4df5a..32d65e55c5db 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten-by/lib/main.js +++ b/lib/node_modules/@stdlib/ndarray/flatten-by/lib/main.js @@ -55,6 +55,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 * @param {Function} fcn - callback function * @param {*} [thisArg] - callback execution context * @throws {TypeError} first argument must be an ndarray-like object @@ -101,8 +102,9 @@ function flattenBy( x, options, fcn, thisArg ) { // 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 ) }; // Case: flattenBy( x, fcn ) @@ -165,16 +167,21 @@ function flattenBy( x, options, fcn, thisArg ) { 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 ); // Transform and assign elements to the output ndarray: map( [ x, view ], cb, ctx ); diff --git a/lib/node_modules/@stdlib/ndarray/flatten-by/test/test.js b/lib/node_modules/@stdlib/ndarray/flatten-by/test/test.js index 9b306deb95f9..8fd480e43237 100644 --- a/lib/node_modules/@stdlib/ndarray/flatten-by/test/test.js +++ b/lib/node_modules/@stdlib/ndarray/flatten-by/test/test.js @@ -24,9 +24,11 @@ var tape = require( 'tape' ); var isSameFloat64Array = require( '@stdlib/assert/is-same-float64array' ); +var isSameFloat32Array = require( '@stdlib/assert/is-same-float32array' ); var zeros = require( '@stdlib/ndarray/zeros' ); var ndarray = require( '@stdlib/ndarray/ctor' ); var Float64Array = require( '@stdlib/array/float64' ); +var Float32Array = require( '@stdlib/array/float32' ); var identity = require( '@stdlib/number/float64/base/identity' ); var getDType = require( '@stdlib/ndarray/dtype' ); var getShape = require( '@stdlib/ndarray/shape' ); @@ -272,6 +274,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 + }; + flattenBy( zeros( [ 2 ] ), opts, identity ); + }; + } +}); + tape( 'the function throws an error if provided a callback argument which is not a function', function test( t ) { var values; var i; @@ -1534,6 +1569,55 @@ tape( 'the function supports flattening a one-dimensional input ndarray (order=a t.end(); }); +tape( 'the function supports specifying the output ndarray data type', function test( t ) { + var expected; + var xbuf; + var opts; + var ord; + var sh; + var st; + var dt; + var o; + var x; + var y; + + dt = 'float64'; + ord = 'row-major'; + sh = [ 2, 2, 2 ]; + st = shape2strides( sh, ord ); + o = strides2offset( sh, st ); + + /* + * [ + * [ + * [ 1.0, 2.0 ], + * [ 3.0, 4.0 ] + * ], + * [ + * [ 5.0, 6.0 ], + * [ 7.0, 8.0 ] + * ] + * ] + */ + xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + x = new ndarray( dt, xbuf, sh, st, o, ord ); + + opts = { + 'dtype': 'float32' + }; + y = flattenBy( x, opts, identity ); + expected = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + + t.notEqual( y, x, 'returns expected value' ); + t.notEqual( getData( y ), xbuf, 'returns expected value' ); + t.strictEqual( isSameFloat32Array( getData( y ), expected ), true, 'returns expected value' ); + t.deepEqual( getShape( y ), [ 8 ], 'returns expected value' ); + t.strictEqual( getDType( y ), 'float32', 'returns expected value' ); + t.strictEqual( getOrder( y ), ord, 'returns expected value' ); + + t.end(); +}); + tape( 'the function supports specifying the callback execution context (row-major)', function test( t ) { var expected; var indices;