Add support for providing an output array

Author: kgryte

lib/node_modules/@stdlib/math/base/complex/round/README.md

@@ -10,7 +10,7 @@
 var cround = require( '@stdlib/math/base/complex/round' );
 ```
 
-#### cround( re, im )
+#### cround( \[out,] re, im )
 
 Rounds a `complex` number comprised of a **real** component `re` and an **imaginary** component `im` to the nearest integer.
 
@@ -28,6 +28,18 @@ v = cround( NaN, NaN );
 // returns [ NaN, NaN ]
 ```
 
+By default, the function returns real and imaginary components as a two-element `array`. To avoid unnecessary memory allocation, the function supports providing an output (destination) object.
+
+```javascript
+var out = new Float64Array( 2 );
+
+var v = cround( out, -4.2, 5.5 );
+// returns <Float64Array>[ -4.0, 6.0 ]
+
+var bool = ( v === out );
+// returns true
+```
+
 </section>
 
 <!-- /.usage -->

lib/node_modules/@stdlib/math/base/complex/round/benchmark/benchmark.js

@@ -35,6 +35,32 @@ bench( pkg, function benchmark( b ) {
 	b.end();
 });
 
+bench( pkg+'::memory_reuse', function benchmark( b ) {
+	var out;
+	var re;
+	var im;
+	var y;
+	var i;
+
+	out = new Array( 2 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		re = ( randu()*1000.0 ) - 500.0;
+		im = ( randu()*1000.0 ) - 500.0;
+		y = cround( out, re, im );
+		if ( y.length === 0 ) {
+			b.fail( 'should not be empty' );
+		}
+	}
+	b.toc();
+	if ( isnan( y ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
 bench( pkg+'::built-in', function benchmark( b ) {
 	var re;
 	var im;
@@ -57,3 +83,29 @@ bench( pkg+'::built-in', function benchmark( b ) {
 	b.pass( 'benchmark finished' );
 	b.end();
 });
+
+bench( pkg+'::built-in,memory_reuse', function benchmark( b ) {
+	var re;
+	var im;
+	var y;
+	var i;
+
+	y = new Array( 2 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		re = ( randu()*1000.0 ) - 500.0;
+		im = ( randu()*1000.0 ) - 500.0;
+		y[ 0 ] = round( re );
+		y[ 1 ] = round( im );
+		if ( y.length === 0 ) {
+			b.fail( 'should not be empty' );
+		}
+	}
+	b.toc();
+	if ( isnan( y ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/math/base/complex/round/docs/repl.txt

@@ -1,9 +1,12 @@
 
-{{alias}}( re, im )
+{{alias}}( [out,] re, im )
     Rounds a complex number to the nearest integer.
 
     Parameters
     ----------
+    out: Array|TypedArray|Object (optional)
+        Output array.
+
     re: number
         Real component.
 
@@ -12,14 +15,21 @@
 
     Returns
     -------
-    out: Array<number>
+    out: Array|TypedArray|Object
         Rounded components.
 
     Examples
     --------
     > var out = {{alias}}( 5.5, 3.3 )
     [ 6.0, 3.0 ]
 
+    // Provide an output array:
+    > out = new Float64Array( 2 );
+    > var v = {{alias}}( out, 5.5, 3.3 )
+    <Float64Array>[ 6.0, 3.0 ]
+    > var bool = ( v === out )
+    true
+
     See Also
     --------
 

lib/node_modules/@stdlib/math/base/complex/round/lib/cround.js

@@ -10,15 +10,26 @@ var round = require( '@stdlib/math/base/special/round' );
 /**
 * Rounds a complex number to the nearest integer.
 *
+* @private
+* @param {(Array|TypedArray|Object)} out - output array
 * @param {number} re - real component
 * @param {number} im - imaginary component
-* @returns {Array<number>} rounded components
+* @returns {(Array|TypedArray|Object)} rounded components
 *
 * @example
 * var v = cround( -4.2, 5.5 );
 * // returns [ -4.0, 6.0 ]
 *
 * @example
+* var out = new Array( 2 );
+*
+* var v = cround( out, -4.2, 5.5 );
+* // returns [ -4.0, 6.0 ]
+*
+* var bool = ( v === out );
+* // returns true
+*
+* @example
 * var v = cround( 9.99999, 0.1 );
 * // returns [ 10.0, 0.0 ]
 *
@@ -30,8 +41,10 @@ var round = require( '@stdlib/math/base/special/round' );
 * var v = cround( NaN, NaN );
 * // returns [ NaN, NaN ]
 */
-function cround( re, im ) {
-	return [ round( re ), round( im ) ];
+function cround( out, re, im ) {
+	out[ 0 ] = round( re );
+	out[ 1 ] = round( im );
+	return out;
 } // end FUNCTION cround()
 
 

lib/node_modules/@stdlib/math/base/complex/round/lib/index.js

@@ -19,11 +19,22 @@
 *
 * v = cround( NaN, NaN );
 * // returns [ NaN, NaN ]
+*
+* @example
+* var cround = require( '@stdlib/math/base/complex/round' );
+*
+* var out = new Array( 2 );
+*
+* var v = cround( out, -4.2, 5.5 );
+* // returns [ -5.0, 6.0 ]
+*
+* var bool = ( v === out );
+* // returns true
 */
 
 // MODULES //
 
-var cround = require( './cround.js' );
+var cround = require( './main.js' );
 
 
 // EXPORTS //

lib/node_modules/@stdlib/math/base/complex/round/lib/main.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// MODULES //
+
+var round = require( './cround.js' );
+
+
+// MAIN //
+
+/**
+* Rounds a complex number to the nearest integer.
+*
+* @param {(Array|TypedArray|Object)} [out] - output array
+* @param {number} re - real component
+* @param {number} im - imaginary component
+* @returns {(Array|TypedArray|Object)} rounded components
+*
+* @example
+* var v = cround( -4.2, 5.5 );
+* // returns [ -4.0, 6.0 ]
+*
+* @example
+* var out = new Array( 2 );
+*
+* var v = cround( out, -4.2, 5.5 );
+* // returns [ -4.0, 6.0 ]
+*
+* var bool = ( v === out );
+* // returns true
+*
+* @example
+* var v = cround( 9.99999, 0.1 );
+* // returns [ 10.0, 0.0 ]
+*
+* @example
+* var v = cround( 0.0, 0.0 );
+* // returns [ 0.0, 0.0 ]
+*
+* @example
+* var v = cround( NaN, NaN );
+* // returns [ NaN, NaN ]
+*/
+function cround( out, re, im ) {
+	if ( arguments.length === 2 ) {
+		return round( new Array( 2 ), out, re );
+	}
+	return round( out, re, im );
+} // end FUNCTION cround()
+
+
+// EXPORTS //
+
+module.exports = cround;

lib/node_modules/@stdlib/math/base/complex/round/test/test.js

@@ -8,6 +8,7 @@ var NINF = require( '@stdlib/math/constants/float64-ninf' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var isNegativeZero = require( '@stdlib/math/base/assert/is-negative-zero' );
 var isPositiveZero = require( '@stdlib/math/base/assert/is-positive-zero' );
+var Float64Array = require( '@stdlib/types/array/float64' ); // eslint-disable-line no-redeclare
 var cround = require( './../lib' );
 
 
@@ -19,7 +20,7 @@ tape( 'main export is a function', function test( t ) {
 	t.end();
 });
 
-tape( 'the function rounds real and imaginary components to the nearest integer.', function test( t ) {
+tape( 'the function rounds real and imaginary components to the nearest integer', function test( t ) {
 	var expected;
 	var actual;
 
@@ -38,6 +39,57 @@ tape( 'the function rounds real and imaginary components to the nearest integer.
 	t.end();
 });
 
+tape( 'the function rounds real and imaginary components to the nearest integer (output array)', function test( t ) {
+	var expected;
+	var actual;
+	var out;
+
+	out = new Array( 2 );
+	actual = cround( out, -4.2, 5.5 );
+
+	expected = [ -4.0, 6.0 ];
+
+	t.deepEqual( actual, expected, 'returns expected value' );
+	t.strictEqual( actual, out, 'returns output value' );
+
+	t.end();
+});
+
+tape( 'the function rounds real and imaginary components to the nearest integer (output typed array)', function test( t ) {
+	var expected;
+	var actual;
+	var out;
+
+	out = new Float64Array( 2 );
+	actual = cround( out, 9.99999, 0.1 );
+
+	expected = new Float64Array( [ 10.0, 0.0 ] );
+
+	t.deepEqual( actual, expected, 'returns expected value' );
+	t.strictEqual( actual, out, 'returns output value' );
+
+	t.end();
+});
+
+tape( 'the function rounds real and imaginary components to the nearest integer (output object)', function test( t ) {
+	var expected;
+	var actual;
+	var out;
+
+	out = {};
+	actual = cround( out, 0.0, 0.0 );
+
+	expected = {
+		'0': 0.0,
+		'1': 0.0
+	};
+
+	t.deepEqual( actual, expected, 'returns expected value' );
+	t.strictEqual( actual, out, 'returns output value' );
+
+	t.end();
+});
+
 tape( 'the function returns a `NaN` if provided a `NaN`', function test( t ) {
 	var val = cround( NaN, NaN );
 	t.strictEqual( isnan( val[ 0 ] ), true, 'returns expected value' );