feat: add dtype option support in ndarray/flatten-by

PR-URL: #8094
Closes: stdlib-js/metr-issue-tracker#80
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]>

Author: headlessNode

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 <ndarray>
+
+var opts = {
+    'dtype': 'float32'
+};
+var y = flattenBy( x, opts, scale );
+// returns <ndarray>
+
+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`.
 
 <!-- eslint-disable no-invalid-this, max-len -->
@@ -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
 
 </section>

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.
 

lib/node_modules/@stdlib/ndarray/flatten-by/docs/types/index.d.ts

@@ -20,7 +20,7 @@
 
 /// <reference types="@stdlib/types"/>
 
-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<T, U, V, ThisArg> = ( this: ThisArg, value: T, indices: Array<numbe
 type Callback<T, U, V, ThisArg> = Nullary<V, ThisArg> | Unary<T, V, ThisArg> | Binary<T, V, ThisArg> | Ternary<T, U, V, ThisArg>;
 
 /**
-* 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<U> = BaseOptions & {
+	/**
+	* Output ndarray data type.
+	*/
+	dtype: U;
+};
+
 /**
 * Flattens an ndarray according to a callback function.
 *
@@ -232,6 +242,7 @@ declare function flattenBy<T = unknown, U extends genericndarray<T> = 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<T = unknown, U extends genericndarray<T> = genericnda
 * var arr = ndarray2array( y );
 * // returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ]
 */
-declare function flattenBy<T extends typedndarray<number> = typedndarray<number>, ThisArg = unknown>( x: T, options: Options, fcn: Callback<number, T, number, ThisArg>, thisArg?: ThisParameterType<Callback<number, T, number, ThisArg>> ): T;
+declare function flattenBy<T extends typedndarray<number> = typedndarray<number>, ThisArg = unknown>( x: T, options: BaseOptions, fcn: Callback<number, T, number, ThisArg>, thisArg?: ThisParameterType<Callback<number, T, number, ThisArg>> ): T;
 
 /**
 * Flattens an ndarray according to a callback function.
@@ -272,6 +283,7 @@ declare function flattenBy<T extends typedndarray<number> = typedndarray<number>
 * @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<T extends typedndarray<number> = typedndarray<number>
 * var y = flattenBy( x, opts, identity );
 * // returns <ndarray>
 */
-declare function flattenBy<T extends ComplexLike = ComplexLike, U extends typedndarray<T> = typedndarray<T>, ThisArg = unknown>( x: U, options: Options, fcn: Callback<T, U, T, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, T, ThisArg>> ): U;
+declare function flattenBy<T extends ComplexLike = ComplexLike, U extends typedndarray<T> = typedndarray<T>, ThisArg = unknown>( x: U, options: BaseOptions, fcn: Callback<T, U, T, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, T, ThisArg>> ): U;
 
 /**
 * Flattens an ndarray according to a callback function.
@@ -309,6 +321,7 @@ declare function flattenBy<T extends ComplexLike = ComplexLike, U extends typedn
 * @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
@@ -340,7 +353,7 @@ declare function flattenBy<T extends ComplexLike = ComplexLike, U extends typedn
 * var arr = ndarray2array( y );
 * // returns [ false, true, false, true, false, true ]
 */
-declare function flattenBy<T extends typedndarray<boolean> = typedndarray<boolean>, ThisArg = unknown>( x: T, options: Options, fcn: Callback<boolean, T, boolean, ThisArg>, thisArg?: ThisParameterType<Callback<boolean, T, boolean, ThisArg>> ): T;
+declare function flattenBy<T extends typedndarray<boolean> = typedndarray<boolean>, ThisArg = unknown>( x: T, options: BaseOptions, fcn: Callback<boolean, T, boolean, ThisArg>, thisArg?: ThisParameterType<Callback<boolean, T, boolean, ThisArg>> ): T;
 
 /**
 * Flattens an ndarray according to a callback function.
@@ -349,6 +362,7 @@ declare function flattenBy<T extends typedndarray<boolean> = typedndarray<boolea
 * @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
@@ -379,7 +393,48 @@ declare function flattenBy<T extends typedndarray<boolean> = typedndarray<boolea
 * var arr = ndarray2array( y );
 * // returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ]
 */
-declare function flattenBy<T = unknown, U extends genericndarray<T> = genericndarray<T>, V = unknown, W extends genericndarray<V> = genericndarray<V>, ThisArg = unknown>( x: U, options: Options, fcn: Callback<T, U, V, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, V, ThisArg>> ): W;
+declare function flattenBy<T = unknown, U extends genericndarray<T> = genericndarray<T>, V = unknown, W extends genericndarray<V> = genericndarray<V>, ThisArg = unknown>( x: U, options: BaseOptions, fcn: Callback<T, U, V, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, V, ThisArg>> ): 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 <ndarray>
+*
+* var opts = {
+*      'depth': 2
+* };
+*
+* var y = flattenBy( x, opts, scale );
+* // returns <ndarray>
+*
+* var arr = ndarray2array( y );
+* // returns [ 2.0, 4.0, 6.0, 8.0, 10.0, 12.0 ]
+*/
+declare function flattenBy<T = unknown, U extends typedndarray<T> | genericndarray<T> = typedndarray<T>, V = unknown, W extends keyof DataTypeMap<T> = 'generic', ThisArg = unknown>( x: U, options: Options<W>, fcn: Callback<T, U, V, ThisArg>, thisArg?: ThisParameterType<Callback<T, U, V, ThisArg>> ): DataTypeMap<V>[W];
 
 
 // EXPORTS //

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<number>
 	flattenBy( zeros( 'generic', sh, ord ), identity, {} ); // $ExpectType genericndarray<number>
 	flattenBy( zeros( 'generic', sh, ord ), {}, identity, {} ); // $ExpectType genericndarray<number>
+
+	flattenBy( zeros( 'float64', sh, ord ), { 'dtype': 'float32' }, identity ); // $ExpectType float32ndarray
+	flattenBy( zeros( 'float64', sh, ord ), { 'dtype': 'generic' }, identity ); // $ExpectType genericndarray<any>
+	flattenBy( zeros( 'generic', sh, ord ), { 'dtype': 'float64' }, identity ); // $ExpectType float64ndarray
+	flattenBy( zeros( 'generic', sh, ord ), { 'dtype': 'generic' }, identity ); // $ExpectType genericndarray<any>
 }
 
 // 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' );

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 );

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;