feat: add dtype option support in ndarray/flatten

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

Author: headlessNode

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 <ndarray>
+
+var y = flatten( x, {
+    'dtype': 'float32'
+});
+// returns <ndarray>
+
+var dt = dtype( y );
+// returns 'float32'
+
+var arr = ndarray2array( y );
+// returns [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ]
+```
+
 </section>
 
 <!-- /.usage -->
@@ -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
 
 <!-- <related-links> -->

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

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

@@ -20,7 +20,7 @@
 
 /// <reference types="@stdlib/types"/>
 
-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;
 }
 
 /**

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

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

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;