feat: add support for single-precision floating-point arithmetic emulation

Author: kgryte

lib/node_modules/@stdlib/math/base/tools/evalrational-compile/README.md

@@ -36,9 +36,9 @@ limitations under the License.
 var compile = require( '@stdlib/math/base/tools/evalrational-compile' );
 ```
 
-#### compile( P, Q )
+#### compile( P, Q\[, options] )
 
-Compiles a module `string` containing an exported function which evaluates a [rational function][@stdlib/math/base/tools/evalrational] having coefficients `P` and `Q`.
+Compiles a module string containing an exported function which evaluates a [rational function][@stdlib/math/base/tools/evalrational] having coefficients `P` and `Q`.
 
 ```javascript
 var P = [ 3.0, 2.0, 1.0 ];
@@ -48,7 +48,11 @@ var str = compile( P, Q );
 // returns <string>
 ```
 
-In the example above, the output `string` would correspond to the following module:
+The function supports the following `options`:
+
+-   **dtype**: input argument floating-point data type (e.g., `float64` or `float32`). Default: `'float64'`.
+
+In the example above, the output string would correspond to the following module:
 
 <!-- eslint-disable no-unused-expressions -->
 
@@ -84,12 +88,12 @@ function evalrational( x ) {
         ax = x;
     }
     if ( ax <= 1.0 ) {
-        s1 = 3.0 + (x * (2.0 + (x * 1.0))); // eslint-disable-line max-len
-        s2 = -1.0 + (x * (-2.0 + (x * -3.0))); // eslint-disable-line max-len
+        s1 = 3.0 + (x * (2.0 + (x * 1.0)));
+        s2 = -1.0 + (x * (-2.0 + (x * -3.0)));
     } else {
         x = 1.0 / x;
-        s1 = 1.0 + (x * (2.0 + (x * 3.0))); // eslint-disable-line max-len
-        s2 = -3.0 + (x * (-2.0 + (x * -1.0))); // eslint-disable-line max-len
+        s1 = 1.0 + (x * (2.0 + (x * 3.0)));
+        s2 = -3.0 + (x * (-2.0 + (x * -1.0)));
     }
     return s1 / s2;
 }
@@ -102,6 +106,75 @@ module.exports = evalrational;
 
 The coefficients should be ordered in **ascending** degree, thus matching summation notation.
 
+By default, the function assumes double-precision floating-point arithmetic. To emulate single-precision floating-point arithmetic, set the `dtype` option to `'float32'`.
+
+```javascript
+var P = [ 3.0, 2.0, 1.0 ];
+var Q = [ -1.0, -2.0, -3.0 ];
+
+var str = compile( P, Q, {
+    'dtype': 'float32'
+});
+// returns <string>
+```
+
+In the previous example, the output string would correspond to the following module:
+
+<!-- eslint-disable no-unused-expressions -->
+
+```javascript
+'use strict';
+
+// MODULES //
+
+var float64ToFloat32 = require( '@stdlib/number/float64/base/to-float32' );
+
+
+// MAIN //
+
+/**
+* Evaluates a rational function (i.e., the ratio of two polynomials described by the coefficients stored in \\(P\\) and \\(Q\\)).
+*
+* ## Notes
+*
+* -   Coefficients should be sorted in ascending degree.
+* -   The implementation uses [Horner's rule][horners-method] for efficient computation.
+*
+* [horners-method]: https://en.wikipedia.org/wiki/Horner%27s_method
+*
+* @private
+* @param {number} x - value at which to evaluate the rational function
+* @returns {number} evaluated rational function
+*/
+function evalrational( x ) {
+    var ax;
+    var s1;
+    var s2;
+    if ( x === 0.0 ) {
+        return -3.0;
+    }
+    if ( x < 0.0 ) {
+        ax = -x;
+    } else {
+        ax = x;
+    }
+    if ( ax <= 1.0 ) {
+        s1 = float64ToFloat32(3.0 + float64ToFloat32(x * float64ToFloat32(2.0 + float64ToFloat32(x * 1.0)))); // eslint-disable-line max-len
+        s2 = float64ToFloat32(-1.0 + float64ToFloat32(x * float64ToFloat32(-2.0 + float64ToFloat32(x * -3.0)))); // eslint-disable-line max-len
+    } else {
+        x = float64ToFloat32( 1.0 / x );
+        s1 = float64ToFloat32(1.0 + float64ToFloat32(x * float64ToFloat32(2.0 + float64ToFloat32(x * 3.0)))); // eslint-disable-line max-len
+        s2 = float64ToFloat32(-3.0 + float64ToFloat32(x * float64ToFloat32(-2.0 + float64ToFloat32(x * -1.0)))); // eslint-disable-line max-len
+    }
+    return float64ToFloat32( s1 / s2 );
+}
+
+
+// EXPORTS //
+
+module.exports = evalrational;
+```
+
 </section>
 
 <!-- /.usage -->
@@ -123,32 +196,15 @@ The coefficients should be ordered in **ascending** degree, thus matching summat
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var randu = require( '@stdlib/random/base/randu' );
-var round = require( '@stdlib/math/base/special/round' );
-var Float64Array = require( '@stdlib/array/float64' );
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var compile = require( '@stdlib/math/base/tools/evalrational-compile' );
 
-var sign;
-var str;
-var P;
-var Q;
-var i;
-
-// Create two arrays of random coefficients...
-P = new Float64Array( 10 );
-Q = new Float64Array( 10 );
-for ( i = 0; i < P.length; i++ ) {
-    if ( randu() < 0.5 ) {
-        sign = -1.0;
-    } else {
-        sign = 1.0;
-    }
-    P[ i ] = sign * round( randu()*100.0 );
-    Q[ i ] = sign * round( randu()*100.0 );
-}
+// Create arrays of random coefficients:
+var P = discreteUniform( 10, -100, 100 );
+var Q = discreteUniform( 10, -100, 100 );
 
 // Compile a module for evaluating a rational function:
-str = compile( P, Q );
+var str = compile( P, Q );
 console.log( str );
 ```
 

lib/node_modules/@stdlib/math/base/tools/evalrational-compile/docs/types/index.d.ts

@@ -18,11 +18,26 @@
 
 // TypeScript Version: 4.1
 
+/// <reference types="@stdlib/types"/>
+
+import { Collection } from '@stdlib/types/array';
+
+/**
+* Interface describing function options.
+*/
+interface Options {
+	/**
+	* Input value floating-point data type (e.g., `float64` or `float32`). Default: `'float64'`.
+	*/
+	dtype?: 'float64' | 'float32';
+}
+
 /**
 * Compiles a module string which exports a function for evaluating a rational function.
 *
 * @param P - numerator polynomial coefficients sorted in ascending degree
 * @param Q - denominator polynomial coefficients sorted in ascending degree
+* @param options - function options
 * @returns module string exporting a function for evaluating a rational function
 *
 * @example
@@ -32,7 +47,7 @@
 * var str = compile( P, Q );
 * // returns <string>
 */
-declare function compile( P: Array<number>, Q: Array<number> ): string;
+declare function compile( P: Collection<number>, Q: Collection<number>, options?: Options ): string;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/math/base/tools/evalrational-compile/docs/types/test.ts

@@ -24,33 +24,75 @@ import compile = require( './index' );
 // The function returns a string...
 {
 	compile( [ -6.0, -5.0 ], [ 3.0, 0.5 ] ); // $ExpectType string
+	compile( [ 3.0, 2.0, 1.0 ], { 'dtype': 'float32' } ); // $ExpectType string
 }
 
 // The compiler throws an error if the function is provided a first argument which is not an array of numbers...
 {
 	const Q = [ 3.0, 0.5 ];
+
 	compile( true, Q ); // $ExpectError
 	compile( false, Q ); // $ExpectError
 	compile( 'abc', Q ); // $ExpectError
 	compile( 123, Q ); // $ExpectError
 	compile( {}, Q ); // $ExpectError
 	compile( ( x: number ): number => x, Q ); // $ExpectError
+
+	compile( true, Q, {} ); // $ExpectError
+	compile( false, Q, {} ); // $ExpectError
+	compile( 'abc', Q, {} ); // $ExpectError
+	compile( 123, Q, {} ); // $ExpectError
+	compile( {}, Q, {} ); // $ExpectError
+	compile( ( x: number ): number => x, Q, {} ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided a second argument which is not an array of numbers...
 {
 	const P = [ -6.0, -5.0 ];
+
 	compile( P, true ); // $ExpectError
 	compile( P, false ); // $ExpectError
 	compile( P, 'abc' ); // $ExpectError
 	compile( P, 123 ); // $ExpectError
 	compile( P, {} ); // $ExpectError
 	compile( P, ( x: number ): number => x ); // $ExpectError
+
+	compile( P, true, {} ); // $ExpectError
+	compile( P, false, {} ); // $ExpectError
+	compile( P, 'abc', {} ); // $ExpectError
+	compile( P, 123, {} ); // $ExpectError
+	compile( P, {}, {} ); // $ExpectError
+	compile( P, ( x: number ): number => x, {} ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided a third argument which is not an object...
+{
+	const P = [ -6.0, -5.0 ];
+	const Q = [ 3.0, 0.5 ];
+
+	compile( P, Q, true ); // $ExpectError
+	compile( P, Q, false ); // $ExpectError
+	compile( P, Q, 'abc' ); // $ExpectError
+	compile( P, Q, 123 ); // $ExpectError
+	compile( P, Q, ( x: number ): number => x ); // $ExpectError
+}
+
+// The compiler throws an error if the function is provided an invalid `dtype` option...
+{
+	const P = [ -6.0, -5.0 ];
+	const Q = [ 3.0, 0.5 ];
+
+	compile( P, Q, { 'dtype': true } ); // $ExpectError
+	compile( P, Q, { 'dtype': false } ); // $ExpectError
+	compile( P, Q, { 'dtype': [] } ); // $ExpectError
+	compile( P, Q, { 'dtype': 123 } ); // $ExpectError
+	compile( P, Q, { 'dtype': ( x: number ): number => x } ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided an insufficient number of arguments...
 {
 	const P = [ -6.0, -5.0 ];
+
 	compile(); // $ExpectError
 	compile( P ); // $ExpectError
 }

lib/node_modules/@stdlib/math/base/tools/evalrational-compile/examples/index.js

@@ -19,9 +19,7 @@
 'use strict';
 
 var resolve = require( 'path' ).resolve;
-var randu = require( '@stdlib/random/base/randu' );
-var round = require( '@stdlib/math/base/special/round' );
-var Float64Array = require( '@stdlib/array/float64' );
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var tryRequire = require( '@stdlib/utils/try-require' );
 
 var compile = tryRequire( resolve( __dirname, '..', 'lib' ) );
@@ -32,26 +30,11 @@ if ( compile instanceof Error ) {
 }
 
 function main() {
-	var sign;
-	var str;
-	var P;
-	var Q;
-	var i;
-
-	// Create two arrays of random coefficients...
-	P = new Float64Array( 10 );
-	Q = new Float64Array( 10 );
-	for ( i = 0; i < P.length; i++ ) {
-		if ( randu() < 0.5 ) {
-			sign = -1.0;
-		} else {
-			sign = 1.0;
-		}
-		P[ i ] = sign * round( randu()*100.0 );
-		Q[ i ] = sign * round( randu()*100.0 );
-	}
+	// Create arrays of random coefficients:
+	var P = discreteUniform( 10, -100, 100 );
+	var Q = discreteUniform( 10, -100, 100 );
 
 	// Compile a module for evaluating a rational function:
-	str = compile( P, Q );
+	var str = compile( P, Q );
 	console.log( str );
 }