Auto-generated commit

base/flatten/lib/main.js

@@ -107,6 +107,8 @@ function flattenColexicographic( out, x, ndims, shape ) {
 	var j;
 	var i;
 
+	// Note that, in contrast to lexicographic iteration, we cannot readily define a straightforward recursive definition for colexicographic iteration. Accordingly, we have to perform a workaround in which we first flatten in lexicographic order and then perform an out-of-place transposition to return an array in colexicographic order.
+
 	// For input arrays having an arbitrary number of dimensions, first flatten in lexicographic order:
 	tmp = recurseLexicographic( [], x, ndims, shape, 0 );
 

base/flatten2d/README.md

@@ -50,6 +50,26 @@ var out = flatten2d( x, [ 2, 2 ], true );
 // returns [ 1, 3, 2, 4 ]
 ```
 
+#### flatten2d.assign( x, shape, colexicographic, out, stride, offset )
+
+Flattens a two-dimensional nested array and assigns elements to a provide output array.
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+
+var x = [ [ 1, 2 ], [ 3, 4 ] ];
+var out = new Float64Array( 4 );
+
+var y = flatten2d.assign( x, [ 2, 2 ], false, out, 1, 0 );
+// returns <Float64Array>[ 1, 2, 3, 4 ]
+
+var bool = ( y === out );
+// returns true
+
+y = flatten2d.assign( x, [ 2, 2 ], true, out, 1, 0 );
+// returns <Float64Array>[ 1, 3, 2, 4 ]
+```
+
 </section>
 
 <!-- /.usage -->

base/flatten2d/benchmark/benchmark.js

@@ -22,8 +22,10 @@
 
 var bench = require( '@stdlib/bench' );
 var isArray = require( '@stdlib/assert/is-array' );
+var isFloat64Array = require( '@stdlib/assert/is-float64array' );
 var zeroTo = require( './../../../base/zero-to' );
 var filled = require( './../../../base/filled' );
+var Float64Array = require( './../../../float64' );
 var pkg = require( './../package.json' ).name;
 var flatten2d = require( './../lib' );
 
@@ -73,3 +75,51 @@ bench( pkg+':size=100,colexicographic', function benchmark( b ) {
 	b.pass( 'benchmark finished' );
 	b.end();
 });
+
+bench( pkg+':assign:size=100,lexicographic', function benchmark( b ) {
+	var out;
+	var x;
+	var i;
+	var v;
+
+	out = new Float64Array( 100 );
+	x = filled( zeroTo( 10 ), 10 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = flatten2d.assign( x, [ 10, 10 ], false, out, 1, 0 );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return a Float64Array' );
+		}
+	}
+	b.toc();
+	if ( !isFloat64Array( v ) ) {
+		b.fail( 'should return a Float64Array' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+':assign:size=100,colexicographic', function benchmark( b ) {
+	var out;
+	var x;
+	var i;
+	var v;
+
+	out = new Float64Array( 100 );
+	x = filled( zeroTo( 10 ), 10 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = flatten2d.assign( x, [ 10, 10 ], true, out, 1, 0 );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return a Float64Array' );
+		}
+	}
+	b.toc();
+	if ( !isFloat64Array( v ) ) {
+		b.fail( 'should return a Float64Array' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

base/flatten2d/docs/repl.txt

@@ -29,6 +29,52 @@
     > out = {{alias}}( x, [ 2, 2 ], true )
     [ 1, 3, 2, 4 ]
 
+
+{{alias}}.assign( x, shape, colexicographic, out, stride, offset )
+    Flattens a two-dimensional nested array and assigns elements to a provided
+    output array.
+
+    The function assumes that all nested arrays have the same length (i.e., the
+    input array is *not* a ragged array).
+
+    Parameters
+    ----------
+    x: Array
+        Input array.
+
+    shape: Array<integer>
+        Array shape.
+
+    colexicographic: boolean
+        Specifies whether to flatten array values in colexicographic order.
+
+    out: Collection
+        Output array.
+
+    stride: integer
+        Output array stride.
+
+    offset: integer
+        Output array index offset.
+
+    Returns
+    -------
+    out: Array
+        Output array.
+
+    Examples
+    --------
+    > var x = [ [ 1, 2 ], [ 3, 4 ] ];
+    > var out = [ 0, 0, 0, 0 ];
+    > var v = {{alias}}.assign( x, [ 2, 2 ], false, out, 1, 0 )
+    [ 1, 2, 3, 4 ]
+    > var bool = ( v === out )
+    true
+    > out = [ 0, 0, 0, 0 ];
+    > {{alias}}.assign( x, [ 2, 2 ], true, out, 1, 0 );
+    > out
+    [ 1, 3, 2, 4 ]
+
     See Also
     --------
 

base/flatten2d/docs/types/index.d.ts

@@ -27,6 +27,71 @@ import { Collection } from '@stdlib/types/object';
 */
 type Array2D<T> = Array<Collection<T>>;
 
+/**
+* Interface describing `flatten2d`.
+*/
+interface Flatten2d {
+	/**
+	* Flattens a two-dimensional nested array.
+	*
+	* ## Notes
+	*
+	* -   The function assumes that all nested arrays have the same length (i.e., the input array is **not** a ragged array).
+	*
+	* @param x - input array
+	* @param shape - array shape
+	* @param colexicographic - specifies whether to flatten array values in colexicographic order
+	* @returns flattened array
+	*
+	* @example
+	* var x = [ [ 1, 2 ], [ 3, 4 ] ];
+	*
+	* var out = flatten2d( x, [ 2, 2 ], false );
+	* // returns [ 1, 2, 3, 4 ]
+	*
+	* @example
+	* var x = [ [ 1, 2 ], [ 3, 4 ] ];
+	*
+	* var out = flatten2d( x, [ 2, 2 ], true );
+	* // returns [ 1, 3, 2, 4 ]
+	*/
+	<T = unknown>( x: Array2D<T>, shape: Collection<number>, colexicographic: boolean ): Array<T>;
+
+
+	/**
+	* Flattens a two-dimensional nested array and assigns elements to a provided output array.
+	*
+	* ## Notes
+	*
+	* -   The function assumes that all nested arrays have the same length (i.e., the input array is **not** a ragged array).
+	*
+	* @param x - input array
+	* @param shape - array shape
+	* @param colexicographic - specifies whether to flatten array values in colexicographic order
+	* @param out - output array
+	* @param stride - output array stride
+	* @param offset - output array index offset
+	* @returns output array
+	*
+	* @example
+	* var Float64Array = require( `@stdlib/array/float64` );
+	*
+	* var x = [ [ 1, 2 ], [ 3, 4 ] ];
+	*
+	* var out = flatten2d.assign( x, [ 2, 2 ], false, new Float64Array( 4 ), 1, 0 );
+	* // returns <Float64Array>[ 1, 2, 3, 4 ]
+	*
+	* @example
+	* var Float64Array = require( `@stdlib/array/float64` );
+	*
+	* var x = [ [ 1, 2 ], [ 3, 4 ] ];
+	*
+	* var out = flatten2d.assign( x, [ 2, 2 ], true, new Float64Array( 4 ), 1, 0 );
+	* // returns <Float64Array>[ 1, 3, 2, 4 ]
+	*/
+	assign<T = unknown, U = unknown>( x: Array2D<T>, shape: Collection<number>, colexicographic: boolean, out: Collection<U>, stride: number, offset: number ): Collection<T | U>;
+}
+
 /**
 * Flattens a two-dimensional nested array.
 *
@@ -51,7 +116,7 @@ type Array2D<T> = Array<Collection<T>>;
 * var out = flatten2d( x, [ 2, 2 ], true );
 * // returns [ 1, 3, 2, 4 ]
 */
-declare function flatten2d<T = unknown>( x: Array2D<T>, shape: Collection<number>, colexicographic: boolean ): Array<T>;
+declare var flatten2d: Flatten2d;
 
 
 // EXPORTS //

base/flatten2d/docs/types/test.ts

@@ -82,3 +82,118 @@ import flatten2d = require( './index' );
 	flatten2d( x, [ 2, 2 ] ); // $ExpectError
 	flatten2d( x, [ 2, 2 ], false, {} ); // $ExpectError
 }
+
+// Attached to the main export is an `assign` method which returns a collection...
+{
+	const x = [ [ 1, 2 ], [ 3, 4 ] ];
+
+	const out1 = [ 0, 0, 0, 0 ];
+
+	flatten2d.assign( x, [ 2, 2 ], false, out1, 1, 0 ); // $ExpectType Collection<number>
+	flatten2d.assign( x, [ 2, 2 ], true, out1, 1, 0 ); // $ExpectType Collection<number>
+
+	flatten2d.assign<number, number>( x, [ 2, 2 ], false, out1, 1, 0 ); // $ExpectType Collection<number>
+	flatten2d.assign<number, number>( x, [ 2, 2 ], true, out1, 1, 0 ); // $ExpectType Collection<number>
+
+	const out2 = [ '', '', '', '' ];
+
+	flatten2d.assign<string, string>( [ [ '1', '2' ], [ '3', '4' ] ], [ 2, 2 ], false, out2, 1, 0 ); // $ExpectType Collection<string>
+	flatten2d.assign<string, string>( [ [ '1', '2' ], [ '3', '4' ] ], [ 2, 2 ], true, out2, 1, 0 ); // $ExpectType Collection<string>
+}
+
+// The compiler throws an error if the `assign` method is provided a first argument which is not an array-like object...
+{
+	const out = [ 0, 0, 0, 0 ];
+
+	flatten2d.assign( 1, [ 2, 2 ], false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( true, [ 2, 2 ], false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( false, [ 2, 2 ], false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( null, [ 2, 2 ], false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( void 0, [ 2, 2 ], false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( {}, [ 2, 2 ], false, out, 1, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided a second argument which is not an array-like object containing numbers...
+{
+	const x = [ [ 1, 2 ], [ 3, 4 ] ];
+	const out = [ 0, 0, 0, 0 ];
+
+	flatten2d.assign( x, '', false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, 1, false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, true, false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, false, false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, null, false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, void 0, false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, {}, false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 1, '2', 3 ], false, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, ( x: number ): number => x, false, out, 1, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided a third argument which is not a boolean...
+{
+	const x = [ [ 1, 2 ], [ 3, 4 ] ];
+	const out = [ 0, 0, 0, 0 ];
+
+	flatten2d.assign( x, [ 2, 2 ], '', out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], 1, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], null, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], void 0, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], {}, out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], [], out, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], ( x: number ): number => x, out, 1, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided a fourth argument which is not an array-like object...
+{
+	const x = [ [ 1, 2 ], [ 3, 4 ] ];
+
+	flatten2d.assign( x, [ 2, 2 ], false, 1, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, true, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, false, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, null, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, void 0, 1, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, {}, 1, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided a fifth argument which is not a number...
+{
+	const x = [ [ 1, 2 ], [ 3, 4 ] ];
+	const out = [ 0, 0, 0, 0 ];
+
+	flatten2d.assign( x, [ 2, 2 ], false, out, '1', 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, true, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, false, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, null, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, void 0, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, {}, 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, [], 0 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, ( x: number ): number => x, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided a sixth argument which is not a number...
+{
+	const x = [ [ 1, 2 ], [ 3, 4 ] ];
+	const out = [ 0, 0, 0, 0 ];
+
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, '1'; // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, true; // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, false; // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, null; // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, void 0; // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, {}; // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, []; // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, ( x: number ): number => x; // $ExpectError
+}
+
+// The compiler throws an error if the `assign` method is provided an unsupported number of arguments...
+{
+	const x = [ [ 1, 2 ], [ 3, 4 ] ];
+	const out = [ 0, 0, 0, 0 ];
+
+	flatten2d.assign(); // $ExpectError
+	flatten2d.assign( x ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ] ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1 ); // $ExpectError
+	flatten2d.assign( x, [ 2, 2 ], false, out, 1, 0, {} ); // $ExpectError
+}