Add support for providing an output array

Author: kgryte

lib/node_modules/@stdlib/math/base/special/modf/README.md

@@ -10,7 +10,7 @@
 var modf = require( '@stdlib/math/base/special/modf' );
 ```
 
-#### modf( x )
+#### modf( \[out,] x )
 
 Decomposes a [double-precision floating-point number][ieee754] into integral and fractional parts, each having the same type and sign as `x`.
 
@@ -34,7 +34,23 @@ parts = modf( NaN );
 // returns [ NaN, NaN ]
 ```
 
-<section class="usage">
+To avoid unnecessary memory allocation, the function supports providing an output (destination) object.
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+
+var out = new Float64Array( 2 );
+
+var parts = modf( out, 3.14 );
+// returns [ 3.0, 0.14000000000000012 ]
+
+var bool = ( parts === out );
+// returns true
+```
+
+</section>
+
+<!-- /.usage -->
 
 <section class="notes">
 

lib/node_modules/@stdlib/math/base/special/modf/benchmark/benchmark.js

@@ -31,3 +31,27 @@ bench( pkg, function benchmark( b ) {
 	b.pass( 'benchmark finished' );
 	b.end();
 });
+
+bench( pkg+'::memory_reuse', function benchmark( b ) {
+	var out;
+	var x;
+	var y;
+	var i;
+
+	out = [ 0.0, 0.0 ];
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		x = ( randu()*1.0e7 ) - 5.0e6;
+		y = modf( out, x );
+		if ( !isArray( y ) ) {
+			b.fail( 'should return an array' );
+		}
+	}
+	b.toc();
+	if ( !isArray( y ) || y !== out ) {
+		b.fail( 'should return the output array' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/math/base/special/modf/docs/repl.txt

@@ -1,17 +1,20 @@
 
-{{alias}}( x )
+{{alias}}( [out,] x )
     Decomposes a double-precision floating-point number into integral and
     fractional parts, each having the same type and sign as the input value.
 
     Parameters
     ----------
+    out: Array|TypedArray|Object (optional)
+        Output array.
+
     x: number
         Input value.
 
     Returns
     -------
-    parts: Array<double>
-        Array containing integral and fractional parts.
+    parts: Array|TypedArray|Object
+        Integral and fractional parts.
 
     Examples
     --------
@@ -30,6 +33,13 @@
     > parts = {{alias}}( NaN )
     [ NaN, NaN ]
 
+    // Provide an output array:
+    > var out = new {{alias:@stdlib/array/float64}}( 2 );
+    > parts = {{alias}}( 3.14 )
+    <Float64Array>[ 3.0, 0.14000000000000012 ]
+    > var bool = ( parts === out )
+    true
+
     See Also
     --------
 

lib/node_modules/@stdlib/math/base/special/modf/lib/index.js

@@ -10,11 +10,23 @@
 *
 * var parts = modf( 3.14 );
 * // returns [ 3.0, 0.14000000000000012 ]
+*
+* @example
+* var Float64Array = require( '@stdlib/array/float64' );
+* var modf = require( '@stdlib/math/base/special/modf' );
+*
+* var out = new Float64Array( 2 );
+*
+* var parts = modf( out, 3.14 );
+* // returns [ 3.0, 0.14000000000000012 ]
+*
+* var bool = ( parts === out );
+* // returns true
 */
 
 // MODULES //
 
-var modf = require( './modf.js' );
+var modf = require( './main.js' );
 
 
 // EXPORTS //

lib/node_modules/@stdlib/math/base/special/modf/lib/main.js

@@ -0,0 +1,42 @@
+'use strict';
+
+// MODULES //
+
+var fcn = require( './modf.js' );
+
+
+// MAIN //
+
+/**
+* Decomposes a double-precision floating-point number into integral and fractional parts, each having the same type and sign as the input value.
+*
+* @param {(Array|TypedArray|Object)} [out] - output array
+* @param {number} x - input value
+* @returns {(Array|TypedArray|Object)} output array
+*
+* @example
+* var parts = modf( 3.14 );
+* // returns [ 3.0, 0.14000000000000012 ]
+*
+* @example
+* var Float64Array = require( '@stdlib/array/float64' );
+*
+* var out = new Float64Array( 2 );
+*
+* var parts = modf( out, 3.14 );
+* // returns <Float64Array>[ 3.0, 0.14000000000000012 ]
+*
+* var bool = ( parts === out );
+* // returns true
+*/
+function modf( out, x ) {
+	if ( arguments.length === 1 ) {
+		return fcn( new Array( 2 ), out );
+	}
+	return fcn( out, x );
+} // end FUNCTION modf()
+
+
+// EXPORTS //
+
+module.exports = modf;

lib/node_modules/@stdlib/math/base/special/modf/lib/modf.js

@@ -25,15 +25,16 @@ var WORDS = [ 0, 0 ]; // WARNING: not thread safe
 /**
 * Decomposes a double-precision floating-point number into integral and fractional parts, each having the same type and sign as the input value.
 *
+* @private
+* @param {(Array|TypedArray|Object)} out - output array
 * @param {number} x - input value
-* @returns {NumberArray} array containing integral and fractional parts
+* @returns {(Array|TypedArray|Object)} output array
 *
 * @example
-* var parts = modf( 3.14 );
+* var parts = modf( new Array( 2 ), 3.14 );
 * // returns [ 3.0, 0.14000000000000012 ]
 */
-function modf( x ) {
-	var parts;
+function modf( out, x ) {
 	var high;
 	var low;
 	var exp;
@@ -42,21 +43,29 @@ function modf( x ) {
 	// Special cases...
 	if ( x < 1.0 ) {
 		if ( x < 0.0 ) {
-			parts = modf( -x );
-			parts[ 0 ] *= -1.0;
-			parts[ 1 ] *= -1.0;
-			return parts;
+			modf( out, -x );
+			out[ 0 ] *= -1.0;
+			out[ 1 ] *= -1.0;
+			return out;
 		}
-		if ( x === 0.0 ) {
-			return [ x, x ]; // [ +-0, +-0 ]
+		if ( x === 0.0 ) { // [ +-0, +-0 ]
+			out[ 0 ] = x;
+			out[ 1 ] = x;
+			return out;
 		}
-		return [ 0.0, x ];
+		out[ 0 ] = 0.0;
+		out[ 1 ] = x;
+		return out;
 	}
 	if ( isnan( x ) ) {
-		return [ NaN, NaN ];
+		out[ 0 ] = NaN;
+		out[ 1 ] = NaN;
+		return out;
 	}
 	if ( x === PINF ) {
-		return [ PINF, 0.0 ];
+		out[ 0 ] = PINF;
+		out[ 1 ] = 0.0;
+		return out;
 	}
 	// Decompose |x|...
 
@@ -75,7 +84,9 @@ function modf( x ) {
 
 		// Determine if `x` is integral by checking for significand bits which cannot be exponentiated away...
 		if ( ((high&i)|low) === 0 ) {
-			return [ x, 0.0 ];
+			out[ 0 ] = x;
+			out[ 1 ] = 0.0;
+			return out;
 		}
 		// Turn off all the bits which cannot be exponentiated away:
 		high &= (~i);
@@ -84,18 +95,24 @@ function modf( x ) {
 		i = fromWords( high, 0 );
 
 		// The fractional part is whatever is leftover:
-		return [ i, x-i ];
+		out[ 0 ] = i;
+		out[ 1 ] = x - i;
+		return out;
 	}
 	// Check if `x` can even have a fractional part...
 	if ( exp > 51 ) {
 		// `x` is integral:
-		return [ x, 0.0 ];
+		out[ 0 ] = x;
+		out[ 1 ] = 0.0;
+		return out;
 	}
 	i = ALL_ONES >>> (exp-20);
 
 	// Determine if `x` is integral by checking for less significant significand bits which cannot be exponentiated away...
 	if ( (low&i) === 0 ) {
-		return [ x, 0.0 ];
+		out[ 0 ] = x;
+		out[ 1 ] = 0.0;
+		return out;
 	}
 	// Turn off all the bits which cannot be exponentiated away:
 	low &= (~i);
@@ -104,7 +121,9 @@ function modf( x ) {
 	i = fromWords( high, low );
 
 	// The fractional part is whatever is leftover:
-	return [ i, x-i ];
+	out[ 0 ] = i;
+	out[ 1 ] = x - i;
+	return out;
 } // end FUNCTION modf()
 
 

lib/node_modules/@stdlib/math/base/special/modf/test/test.js

@@ -8,6 +8,7 @@ var NINF = require( '@stdlib/constants/math/float64-ninf' );
 var isNegativeZero = require( '@stdlib/math/base/assert/is-negative-zero' );
 var isPositiveZero = require( '@stdlib/math/base/assert/is-positive-zero' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var Float64Array = require( '@stdlib/array/float64' );
 var modf = require( './../lib' );
 
 
@@ -152,3 +153,49 @@ tape( 'if provided `NaN`, the function returns `[NaN,NaN]`', function test( t )
 	t.strictEqual( isnan( parts[1] ), true, 'returns NaN' );
 	t.end();
 });
+
+tape( 'the function supports providing an output array', function test( t ) {
+	var parts;
+	var out;
+
+	out = [ 0.0, 0.0 ];
+	parts = modf( out, 3.14 );
+
+	t.strictEqual( parts, out, 'returns output array' );
+	t.strictEqual( parts[ 0 ], 3.0, 'has expected first element' );
+	t.strictEqual( parts[ 1 ], 0.14000000000000012, 'has expected second element' );
+
+	t.end();
+});
+
+tape( 'the function supports providing an output typed array', function test( t ) {
+	var parts;
+	var out;
+
+	out = new Float64Array( 2 );
+	parts = modf( out, 3.14 );
+
+	t.strictEqual( parts, out, 'returns output typed array' );
+	t.strictEqual( parts[ 0 ], 3.0, 'has expected first element' );
+	t.strictEqual( parts[ 1 ], 0.14000000000000012, 'has expected second element' );
+
+	t.end();
+});
+
+tape( 'the function supports providing an output object', function test( t ) {
+	var parts;
+	var out;
+
+	out = {
+		'length': 2,
+		'0': 0.0,
+		'1': 0.0
+	};
+	parts = modf( out, 3.14 );
+
+	t.strictEqual( parts, out, 'returns output object' );
+	t.strictEqual( parts[ 0 ], 3.0, 'has expected first element' );
+	t.strictEqual( parts[ 1 ], 0.14000000000000012, 'has expected second element' );
+
+	t.end();
+});