refactor!: modify C implementation to accept double instead of int32 in math/base/special/tribonacci

This commit updates the signature of the C API to accept a double rather than int32. The rationale was so that users get the same results/behavior in both JavaScript and C. This arose in the context of ufuncs, where the diverging type signatures meant differences in what dtypes would be permissible. Instead, we decided to unify and ensure the behavior is consistent.

BREAKING CHANGE: update signature to accept doubles

User code should behave similarly in the primary case of providing integer-valued input values. However, no longer will real-values truncate. Now, real-valued inputs will result in `NaN`, which is, arguably, better behavior, as real-to-integer truncation can be a source of silent bugs.

PR-URL: #8031
Co-authored-by: Athan Reines <kgryte@gmail.com>
Reviewed-by: Athan Reines <kgryte@gmail.com>

Author: gunjjoshi

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

@@ -176,19 +176,19 @@ for ( i = 0; i < 64; i++ ) {
 Computes the nth [Tribonacci number][tribonacci-number].
 
 ```c
-double out = stdlib_base_tribonacci( 0 );
-// returns 0
+double out = stdlib_base_tribonacci( 0.0 );
+// returns 0.0
 
-out = stdlib_base_tribonacci( 1 );
-// returns 0
+out = stdlib_base_tribonacci( 1.0 );
+// returns 0.0
 ```
 
 The function accepts the following arguments:
 
--   **n**: `[in] int32_t` input value.
+-   **n**: `[in] double` input value.
 
 ```c
-double stdlib_base_tribonacci( const int32_t n );
+double stdlib_base_tribonacci( const double n );
 ```
 
 </section>
@@ -212,15 +212,14 @@ double stdlib_base_tribonacci( const int32_t n );
 ```c
 #include "stdlib/math/base/special/tribonacci.h"
 #include <stdio.h>
-#include <stdint.h>
 
 int main( void ) {
-    int32_t i;
+    double i;
     double v;
 
-    for ( i = 0; i < 64; i++ ) {
+    for ( i = 0.0; i < 64.0; i++ ) {
         v = stdlib_base_tribonacci( i );
-        printf( "tribonacci(%d) = %lf\n", i, v );
+        printf( "tribonacci(%lf) = %lf\n", i, v );
     }
 }
 ```

lib/node_modules/@stdlib/math/base/special/tribonacci/benchmark/c/native/benchmark.c

@@ -90,14 +90,14 @@ static double rand_double( void ) {
 * @return elapsed time in seconds
 */
 static double benchmark( void ) {
-	int32_t x[ 100 ];
+	double x[ 100 ];
 	double elapsed;
 	double t;
 	double y;
 	int i;
 
 	for ( i = 0; i < 100; i++ ) {
-		x[ i ] = (int32_t)floor( 40.0*rand_double() );
+		x[ i ] = floor( 40.0*rand_double() );
 	}
 
 	t = tic();

lib/node_modules/@stdlib/math/base/special/tribonacci/examples/c/example.c

@@ -18,14 +18,13 @@
 
 #include "stdlib/math/base/special/tribonacci.h"
 #include <stdio.h>
-#include <stdint.h>
 
 int main( void ) {
-	int32_t i;
+	double i;
 	double v;
 
-	for ( i = 0; i < 64; i++ ) {
+	for ( i = 0.0; i < 64.0; i++ ) {
 		v = stdlib_base_tribonacci( i );
-		printf( "tribonacci(%d) = %lf\n", i, v );
+		printf( "tribonacci(%lf) = %lf\n", i, v );
 	}
 }

lib/node_modules/@stdlib/math/base/special/tribonacci/include/stdlib/math/base/special/tribonacci.h

@@ -19,16 +19,14 @@
 #ifndef STDLIB_MATH_BASE_SPECIAL_TRIBONACCI_H
 #define STDLIB_MATH_BASE_SPECIAL_TRIBONACCI_H
 
-#include <stdint.h>
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
 * Computes the nth Tribonacci number.
 */
-double stdlib_base_tribonacci( const int32_t n );
+double stdlib_base_tribonacci( const double n );
 
 #ifdef __cplusplus
 };

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

@@ -21,7 +21,7 @@
 // MODULES //
 
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
-var isInteger = require( '@stdlib/math/base/assert/is-integer' );
+var isNonnegativeInteger = require( '@stdlib/math/base/assert/is-nonnegative-integer' );
 var FLOAT64_MAX_SAFE_NTH_TRIBONACCI = require( '@stdlib/constants/float64/max-safe-nth-tribonacci' ); // eslint-disable-line id-length
 var TRIBONACCI = require( './tribonacci.json' );
 
@@ -77,8 +77,7 @@ var TRIBONACCI = require( './tribonacci.json' );
 function tribonacci( n ) {
 	if (
 		isnan( n ) ||
-		isInteger( n ) === false ||
-		n < 0 ||
+		!isNonnegativeInteger( n ) ||
 		n > FLOAT64_MAX_SAFE_NTH_TRIBONACCI
 	) {
 		return NaN;

lib/node_modules/@stdlib/math/base/special/tribonacci/manifest.json

@@ -37,7 +37,9 @@
       "libpath": [],
       "dependencies": [
         "@stdlib/math/base/napi/unary",
-        "@stdlib/constants/float64/max-safe-nth-tribonacci"
+        "@stdlib/constants/float64/max-safe-nth-tribonacci",
+        "@stdlib/math/base/assert/is-nan",
+        "@stdlib/math/base/assert/is-nonnegative-integer"
       ]
     },
     {
@@ -51,7 +53,9 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
-        "@stdlib/constants/float64/max-safe-nth-tribonacci"
+        "@stdlib/constants/float64/max-safe-nth-tribonacci",
+        "@stdlib/math/base/assert/is-nan",
+        "@stdlib/math/base/assert/is-nonnegative-integer"
       ]
     },
     {
@@ -65,7 +69,9 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
-        "@stdlib/constants/float64/max-safe-nth-tribonacci"
+        "@stdlib/constants/float64/max-safe-nth-tribonacci",
+        "@stdlib/math/base/assert/is-nan",
+        "@stdlib/math/base/assert/is-nonnegative-integer"
       ]
     }
   ]

lib/node_modules/@stdlib/math/base/special/tribonacci/src/addon.c

@@ -19,4 +19,4 @@
 #include "stdlib/math/base/special/tribonacci.h"
 #include "stdlib/math/base/napi/unary.h"
 
-STDLIB_MATH_BASE_NAPI_MODULE_I_D( stdlib_base_tribonacci )
+STDLIB_MATH_BASE_NAPI_MODULE_D_D( stdlib_base_tribonacci )

lib/node_modules/@stdlib/math/base/special/tribonacci/src/main.c

@@ -18,6 +18,10 @@
 
 #include "stdlib/math/base/special/tribonacci.h"
 #include "stdlib/constants/float64/max_safe_nth_tribonacci.h"
+#include "stdlib/math/base/assert/is_nonnegative_integer.h"
+#include "stdlib/math/base/assert/is_nan.h"
+#include <stdlib.h>
+#include <stdint.h>
 
 static const int64_t tribonacci_value[ 64 ] = {
 	0,
@@ -93,12 +97,12 @@ static const int64_t tribonacci_value[ 64 ] = {
 * @return      output value
 *
 * @example
-* double out = stdlib_base_tribonacci( 1 );
-* // returns 0
+* double out = stdlib_base_tribonacci( 1.0 );
+* // returns 0.0
 */
-double stdlib_base_tribonacci( const int32_t n ) {
-	if ( n < 0 || n > STDLIB_CONSTANT_FLOAT64_MAX_SAFE_NTH_TRIBONACCI ) {
+double stdlib_base_tribonacci( const double n ) {
+	if ( stdlib_base_is_nan( n ) || !stdlib_base_is_nonnegative_integer( n ) || n > STDLIB_CONSTANT_FLOAT64_MAX_SAFE_NTH_TRIBONACCI ) {
 		return 0.0 / 0.0; // NaN
 	}
-	return tribonacci_value[ n ];
+	return tribonacci_value[ (size_t)n ];
 }

lib/node_modules/@stdlib/math/base/special/tribonacci/test/test.native.js

@@ -23,6 +23,7 @@
 var resolve = require( 'path' ).resolve;
 var tape = require( 'tape' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
+var PINF = require( '@stdlib/constants/float64/pinf' );
 var tryRequire = require( '@stdlib/utils/try-require' );
 
 
@@ -58,6 +59,24 @@ tape( 'if provided a negative number, the function returns `NaN`', opts, functio
 	t.end();
 });
 
+tape( 'if provided positive infinity, the function returns `NaN`', opts, function test( t ) {
+	var v = tribonacci( PINF );
+	t.strictEqual( isnan( v ), true, 'returns expected value' );
+	t.end();
+});
+
+tape( 'if provided `NaN`, the function returns `NaN`', opts, function test( t ) {
+	var v = tribonacci( NaN );
+	t.strictEqual( isnan( v ), true, 'returns expected value' );
+	t.end();
+});
+
+tape( 'if provided a non-integer, the function returns `NaN`', opts, function test( t ) {
+	var v = tribonacci( 3.14 );
+	t.strictEqual( isnan( v ), true, 'returns expected value' );
+	t.end();
+});
+
 tape( 'the function returns the nth Tribonacci number', opts, function test( t ) {
 	var v;
 	var i;