refactor: apply suggestions from code review

Author: headlessNode

lib/node_modules/@stdlib/ndarray/flatten-by/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # flattenBy
 
-> Apply a callback to elements in an input [ndarray][@stdlib/ndarray/ctor] and return a flattened output [ndarray][@stdlib/ndarray/ctor].
+> Flatten an [ndarray][@stdlib/ndarray/ctor] according to a callback function.
 
 <section class="intro">
 
@@ -38,7 +38,7 @@ var flattenBy = require( '@stdlib/ndarray/flatten-by' );
 
 #### flattenBy( x\[, options], fcn[, thisArg] )
 
-Applies a callback to elements in an input [ndarray][@stdlib/ndarray/ctor] and returns a flattened output [ndarray][@stdlib/ndarray/ctor].
+Flattens an [ndarray][@stdlib/ndarray/ctor] according to a callback function.
 
 ```javascript
 var array = require( '@stdlib/ndarray/array' );

lib/node_modules/@stdlib/ndarray/flatten-by/docs/repl.txt

@@ -1,7 +1,6 @@
 
 {{alias}}( x[, options], fcn[, thisArg] )
-    Applies a callback to elements in an input ndarray and returns a flattened
-    output ndarray.
+    Flattens an ndarray according to a callback function.
 
     Parameters
     ----------

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

@@ -100,7 +100,7 @@ interface Options {
 }
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -133,7 +133,7 @@ interface Options {
 declare function flattenBy<W = unknown>( x: float64ndarray, fcn: Callback<number, float64ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, float64ndarray, number, W>> ): float64ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -166,7 +166,7 @@ declare function flattenBy<W = unknown>( x: float64ndarray, fcn: Callback<number
 declare function flattenBy<W = unknown>( x: float32ndarray, fcn: Callback<number, float32ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, float32ndarray, number, W>> ): float32ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -196,7 +196,7 @@ declare function flattenBy<W = unknown>( x: float32ndarray, fcn: Callback<number
 declare function flattenBy<W = unknown>( x: complex64ndarray, fcn: Callback<Complex64, complex64ndarray, ComplexLike, W>, thisArg?: ThisParameterType<Callback<Complex64, complex64ndarray, ComplexLike, W>> ): complex64ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -226,7 +226,7 @@ declare function flattenBy<W = unknown>( x: complex64ndarray, fcn: Callback<Comp
 declare function flattenBy<W = unknown>( x: complex128ndarray, fcn: Callback<Complex128, complex128ndarray, ComplexLike, W>, thisArg?: ThisParameterType<Callback<Complex128, complex128ndarray, ComplexLike, W>> ): complex128ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -259,7 +259,7 @@ declare function flattenBy<W = unknown>( x: complex128ndarray, fcn: Callback<Com
 declare function flattenBy<W = unknown>( x: int32ndarray, fcn: Callback<number, int32ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, int32ndarray, number, W>> ): int32ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -292,7 +292,7 @@ declare function flattenBy<W = unknown>( x: int32ndarray, fcn: Callback<number,
 declare function flattenBy<W = unknown>( x: int16ndarray, fcn: Callback<number, int16ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, int16ndarray, number, W>> ): int16ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -325,7 +325,7 @@ declare function flattenBy<W = unknown>( x: int16ndarray, fcn: Callback<number,
 declare function flattenBy<W = unknown>( x: int8ndarray, fcn: Callback<number, int8ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, int8ndarray, number, W>> ): int8ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -358,7 +358,7 @@ declare function flattenBy<W = unknown>( x: int8ndarray, fcn: Callback<number, i
 declare function flattenBy<W = unknown>( x: uint32ndarray, fcn: Callback<number, uint32ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint32ndarray, number, W>> ): uint32ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -391,7 +391,7 @@ declare function flattenBy<W = unknown>( x: uint32ndarray, fcn: Callback<number,
 declare function flattenBy<W = unknown>( x: uint16ndarray, fcn: Callback<number, uint16ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint16ndarray, number, W>> ): uint16ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -424,7 +424,7 @@ declare function flattenBy<W = unknown>( x: uint16ndarray, fcn: Callback<number,
 declare function flattenBy<W = unknown>( x: uint8ndarray, fcn: Callback<number, uint8ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint8ndarray, number, W>> ): uint8ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -457,7 +457,7 @@ declare function flattenBy<W = unknown>( x: uint8ndarray, fcn: Callback<number,
 declare function flattenBy<W = unknown>( x: uint8cndarray, fcn: Callback<number, uint8cndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint8cndarray, number, W>> ): uint8cndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -490,7 +490,7 @@ declare function flattenBy<W = unknown>( x: uint8cndarray, fcn: Callback<number,
 declare function flattenBy<W = unknown>( x: boolndarray, fcn: Callback<boolean, boolndarray, boolean, W>, thisArg?: ThisParameterType<Callback<boolean, boolndarray, boolean, W>> ): boolndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param fcn - callback function
@@ -522,7 +522,7 @@ declare function flattenBy<W = unknown>( x: boolndarray, fcn: Callback<boolean,
 declare function flattenBy<T = unknown, V = unknown, W = unknown>( x: genericndarray<T>, fcn: Callback<T, genericndarray<T>, V, W>, thisArg?: ThisParameterType<Callback<T, genericndarray<T>, V, W>> ): genericndarray<V>;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -562,7 +562,7 @@ declare function flattenBy<T = unknown, V = unknown, W = unknown>( x: genericnda
 declare function flattenBy<W = unknown>( x: float64ndarray, options: Options, fcn: Callback<number, float64ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, float64ndarray, number, W>> ): float64ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -602,7 +602,7 @@ declare function flattenBy<W = unknown>( x: float64ndarray, options: Options, fc
 declare function flattenBy<W = unknown>( x: float32ndarray, options: Options, fcn: Callback<number, float32ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, float32ndarray, number, W>> ): float32ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -639,7 +639,7 @@ declare function flattenBy<W = unknown>( x: float32ndarray, options: Options, fc
 declare function flattenBy<W = unknown>( x: complex64ndarray, options: Options, fcn: Callback<Complex64, complex64ndarray, ComplexLike, W>, thisArg?: ThisParameterType<Callback<Complex64, complex64ndarray, ComplexLike, W>> ): complex64ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -676,7 +676,7 @@ declare function flattenBy<W = unknown>( x: complex64ndarray, options: Options,
 declare function flattenBy<W = unknown>( x: complex128ndarray, options: Options, fcn: Callback<Complex128, complex128ndarray, ComplexLike, W>, thisArg?: ThisParameterType<Callback<Complex128, complex128ndarray, ComplexLike, W>> ): complex128ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -716,7 +716,7 @@ declare function flattenBy<W = unknown>( x: complex128ndarray, options: Options,
 declare function flattenBy<W = unknown>( x: int32ndarray, options: Options, fcn: Callback<number, int32ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, int32ndarray, number, W>> ): int32ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -756,7 +756,7 @@ declare function flattenBy<W = unknown>( x: int32ndarray, options: Options, fcn:
 declare function flattenBy<W = unknown>( x: int16ndarray, options: Options, fcn: Callback<number, int16ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, int16ndarray, number, W>> ): int16ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -796,7 +796,7 @@ declare function flattenBy<W = unknown>( x: int16ndarray, options: Options, fcn:
 declare function flattenBy<W = unknown>( x: int8ndarray, options: Options, fcn: Callback<number, int8ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, int8ndarray, number, W>> ): int8ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -836,7 +836,7 @@ declare function flattenBy<W = unknown>( x: int8ndarray, options: Options, fcn:
 declare function flattenBy<W = unknown>( x: uint32ndarray, options: Options, fcn: Callback<number, uint32ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint32ndarray, number, W>> ): uint32ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -876,7 +876,7 @@ declare function flattenBy<W = unknown>( x: uint32ndarray, options: Options, fcn
 declare function flattenBy<W = unknown>( x: uint16ndarray, options: Options, fcn: Callback<number, uint16ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint16ndarray, number, W>> ): uint16ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -916,7 +916,7 @@ declare function flattenBy<W = unknown>( x: uint16ndarray, options: Options, fcn
 declare function flattenBy<W = unknown>( x: uint8ndarray, options: Options, fcn: Callback<number, uint8ndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint8ndarray, number, W>> ): uint8ndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -956,7 +956,7 @@ declare function flattenBy<W = unknown>( x: uint8ndarray, options: Options, fcn:
 declare function flattenBy<W = unknown>( x: uint8cndarray, options: Options, fcn: Callback<number, uint8cndarray, number, W>, thisArg?: ThisParameterType<Callback<number, uint8cndarray, number, W>> ): uint8cndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options
@@ -996,7 +996,7 @@ declare function flattenBy<W = unknown>( x: uint8cndarray, options: Options, fcn
 declare function flattenBy<W = unknown>( x: boolndarray, options: Options, fcn: Callback<boolean, boolndarray, boolean, W>, thisArg?: ThisParameterType<Callback<boolean, boolndarray, boolean, W>> ): boolndarray;
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param x - input ndarray
 * @param options - function options

lib/node_modules/@stdlib/ndarray/flatten-by/lib/index.js

@@ -19,10 +19,10 @@
 'use strict';
 
 /**
-* Apply a callback to elements in an input ndarray and return a flattened output ndarray.
+* Flatten an ndarray according to a callback function.
 *
 * @module @stdlib/ndarray/flatten-by
-*
+*s
 * @example
 * var array = require( '@stdlib/ndarray/array' );
 * var ndarray2array = require( '@stdlib/ndarray/to-array' );

lib/node_modules/@stdlib/ndarray/flatten-by/lib/main.js

@@ -23,15 +23,28 @@
 var isPlainObject = require( '@stdlib/assert/is-plain-object' );
 var isFunction = require( '@stdlib/assert/is-function' );
 var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
-var map = require( '@stdlib/ndarray/map' );
-var flatten = require( '@stdlib/ndarray/flatten' );
+var hasOwnProp = require( '@stdlib/assert/has-own-property' );
+var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' );
+var isNonNegativeInteger = require( '@stdlib/assert/is-nonnegative-integer' );
+var isOrder = require( '@stdlib/ndarray/base/assert/is-order' );
+var getShape = require( '@stdlib/ndarray/shape' );
+var getOrder = require( '@stdlib/ndarray/order' );
+var getStrides = require( '@stdlib/ndarray/strides' );
+var getData = require( '@stdlib/ndarray/base/data-buffer' );
+var getDType = require( '@stdlib/ndarray/base/dtype' );
+var shape2strides = require( '@stdlib/ndarray/base/shape2strides' );
+var strides2order = require( '@stdlib/ndarray/base/strides2order' );
+var flattenShape = require( '@stdlib/ndarray/base/flatten-shape' );
+var map = require( '@stdlib/ndarray/base/map' );
+var emptyLike = require( '@stdlib/ndarray/empty-like' );
+var ndarray = require( '@stdlib/ndarray/ctor' );
 var format = require( '@stdlib/string/format' );
 
 
 // MAIN //
 
 /**
-* Applies a callback to elements in an input ndarray and returns a flattened output ndarray.
+* Flattens an ndarray according to a callback function.
 *
 * @param {ndarray} x - input ndarray
 * @param {Options} [options] - function options
@@ -71,33 +84,80 @@ function flattenBy( x, options, fcn, thisArg ) {
 	if ( !isndarrayLike( x ) ) {
 		throw new TypeError( format( 'invalid argument. First argument must be an ndarray-like object. Value: `%s`.', x ) );
 	}
-	opts = {};
-	if ( arguments.length < 3 ) { // Case: flattenBy( x, fcn )
+	nargs = arguments.length;
+	xsh = getShape( x );
+
+	// 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)
+	};
+
+	if ( nargs <= 2 ) { // Case: flattenBy( x, fcn )
 		cb = options;
-	} else if ( arguments.length === 3 ) {
+	} else if ( nargs <= 3 ) {
 		if ( isFunction( options ) ) { // Case: flattenBy( x, fcn, thisArg )
 			cb = options;
 			ctx = fcn;
 		} else { // Case: flattenBy( x, options, fcn )
 			if ( !isPlainObject( options ) ) {
 				throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
 			}
-			opts = options;
 			cb = fcn;
 		}
-	} else {
+	} else { // Case: flattenBy( x, options, fcn, thisArg )
 		if ( !isPlainObject( options ) ) {
 			throw new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
 		}
-		opts = options;
 		cb = fcn;
 		ctx = thisArg;
 	}
 	if ( !isFunction( cb ) ) {
 		throw new TypeError( format( 'invalid argument. Callback argument must be a function. Value: `%s`.', cb ) );
 	}
-	y = map( x, cb, ctx );
-	return flatten( y, opts );
+	if ( hasOwnProp( options, 'depth' ) ) {
+		if ( !isNonNegativeInteger( options.depth ) ) {
+			throw new TypeError( format( 'invalid option. `%s` option must be a nonnegative integer. Option: `%s`.', options.depth ) );
+		}
+		opts.depth = options.depth;
+	}
+	if ( hasOwnProp( options, 'order' ) ) {
+		if ( options.order === 'any' ) {
+			// When 'any', we want to flatten according to the physical layout of the data in memory...
+			o = strides2order( getStrides( x ) );
+			if ( o === 1 ) {
+				// Data is currently arranged in row-major order:
+				opts.order = ROW_MAJOR;
+			} else if ( o === 2 ) {
+				// Data is currently arranged in column-major order:
+				opts.order = COL_MAJOR;
+			} else { // o === 0 || o === 3 (i.e., neither row- nor column-major || both row- and column-major
+				// When the data is either both row- and column-major (e.g., a one-dimensional ndarray) or neither row- nor column-major (e.g., unordered strides), fallback to flattening according to the stated order of the input ndarray:
+				opts.order = getOrder( x );
+			}
+		} else if ( options.order === 'same' ) {
+			// When 'same', we want to flatten according to the stated order of the input ndarray:
+			opts.order = getOrder( x );
+		} else if ( isOrder( options.order ) ) {
+			// When provided a specific order, flatten according to that order regardless of the order of the input ndarray:
+			opts.order = options.order;
+		} else {
+			throw new TypeError( format( 'invalid option. `%s` option must be a recognized order. Option: `%s`.', 'order', options.order ) );
+		}
+	}
+	// Create an output ndarray having contiguous memory:
+	y = emptyLike( x, {
+		'shape': flattenShape( xsh, opts.depth ),
+		'order': opts.order
+	});
+
+	// 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 );
+
+	// Transform and assign elements to the output ndarray:
+	map( [ x, view ], cb, ctx );
+	return y;
 }