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

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: #7936
Reviewed-by: Athan Reines <[email protected]>

Author: gunjjoshi

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

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

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

@@ -30,7 +30,7 @@
 /**
 * Prints the TAP version.
 */
-void print_version() {
+static void print_version( void ) {
 	printf( "TAP version 13\n" );
 }
 
@@ -91,14 +91,14 @@ static double rand_double( void ) {
 */
 static double benchmark( void ) {
 	double elapsed;
-	int32_t x;
+	double x;
 	double t;
 	double y;
 	int i;
 
 	t = tic();
 	for ( i = 0; i < ITERATIONS; i++ ) {
-		x = (int32_t)( 76.0*rand_double() );
+		x = ( 76.0*rand_double() );
 		y = stdlib_base_lucas( x );
 		if ( y != y ) {
 			printf( "should not return NaN\n" );

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

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

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

@@ -19,8 +19,6 @@
 #ifndef STDLIB_MATH_BASE_SPECIAL_LUCAS_H
 #define STDLIB_MATH_BASE_SPECIAL_LUCAS_H
 
-#include <stdint.h>
-
 /*
 * If C++, prevent name mangling so that the compiler emits a binary file having undecorated names, thus mirroring the behavior of a C compiler.
 */
@@ -31,7 +29,7 @@ extern "C" {
 /**
 * Computes the nth Lucas number.
 */
-double stdlib_base_lucas( const int32_t n );
+double stdlib_base_lucas( const double n );
 
 #ifdef __cplusplus
 }

lib/node_modules/@stdlib/math/base/special/lucas/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 MAX_LUCAS = require( '@stdlib/constants/float64/max-safe-nth-lucas' );
 var LUCAS = require( './lucas.json' );
 
@@ -77,8 +77,7 @@ var LUCAS = require( './lucas.json' );
 function lucas( n ) {
 	if (
 		isnan( n ) ||
-		isInteger( n ) === false ||
-		n < 0 ||
+		!isNonNegativeInteger( n ) ||
 		n > MAX_LUCAS
 	) {
 		return NaN;

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

@@ -37,6 +37,7 @@
       "libpath": [],
       "dependencies": [
         "@stdlib/math/base/napi/unary",
+        "@stdlib/math/base/assert/is-nonnegative-integer",
         "@stdlib/constants/float64/max-safe-nth-lucas"
       ]
     },
@@ -51,6 +52,7 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
+        "@stdlib/math/base/assert/is-nonnegative-integer",
         "@stdlib/constants/float64/max-safe-nth-lucas"
       ]
     },
@@ -65,6 +67,7 @@
       "libraries": [],
       "libpath": [],
       "dependencies": [
+        "@stdlib/math/base/assert/is-nonnegative-integer",
         "@stdlib/constants/float64/max-safe-nth-lucas"
       ]
     }

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

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

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

@@ -17,7 +17,10 @@
 */
 
 #include "stdlib/math/base/special/lucas.h"
+#include "stdlib/math/base/assert/is_nonnegative_integer.h"
 #include "stdlib/constants/float64/max_safe_nth_lucas.h"
+#include <stdint.h>
+#include <stdlib.h>
 
 static const int64_t lucas_value[ 77 ] = {
 	2,
@@ -106,16 +109,16 @@ static const int64_t lucas_value[ 77 ] = {
 * @return      output value
 *
 * @example
-* double out = stdlib_base_lucas( 1 );
-* // returns 1
+* double out = stdlib_base_lucas( 1.0 );
+* // returns 1.0
 *
 * @example
-* double out = stdlib_base_lucas( -1 );
+* double out = stdlib_base_lucas( -1.0 );
 * // returns NaN
 */
-double stdlib_base_lucas( const int32_t n ) {
-	if ( n < 0 || n > STDLIB_CONSTANT_FLOAT64_MAX_SAFE_NTH_LUCAS ) {
+double stdlib_base_lucas( const double n ) {
+	if ( !stdlib_base_is_nonnegative_integer( n ) || n > STDLIB_CONSTANT_FLOAT64_MAX_SAFE_NTH_LUCAS ) {
 		return 0.0 / 0.0; // NaN
 	}
-	return lucas_value[ n ];
+	return lucas_value[ (size_t)n ];
 }