refactor!: modify C implementation to accept double values instead of int64 in math/base/special/binomcoefln

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

Author: gunjjoshi

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

@@ -187,17 +187,17 @@ logEachMap( 'ln( %d choose %d ) = %0.4f', n, k, binomcoefln );
 Evaluates the natural logarithm of the [binomial coefficient][binomial-coefficient] of two integers `n` and `k`.
 
 ```c
-double v = stdlib_base_binomcoefln( 8, 2 );
+double v = stdlib_base_binomcoefln( 8.0, 2.0 );
 // returns ~3.332
 ```
 
 The function accepts the following arguments:
 
--   **n**: `[in] int64_t` input value.
--   **k**: `[in] int64_t` input value.
+-   **n**: `[in] double` input value.
+-   **k**: `[in] double` input value.
 
 ```c
-double stdlib_base_binomcoefln( const int64_t n, const int64_t k );
+double stdlib_base_binomcoefln( const double n, const double k );
 ```
 
 </section>
@@ -221,18 +221,16 @@ double stdlib_base_binomcoefln( const int64_t n, const int64_t k );
 ```c
 #include "stdlib/math/base/special/binomcoefln.h"
 #include <stdio.h>
-#include <stdint.h>
-#include <inttypes.h>
 
 int main( void ) {
-    const int64_t a[] = { 24, 32, 48, 116, 33 };
-    const int64_t b[] = { 12, 6, 15, 52, 22 };
+    const double a[] = { 24.0, 32.0, 48.0, 116.0, 33.0 };
+    const double b[] = { 12.0, 6.0, 15.0, 52.0, 22.0 };
 
     double out;
     int i;
     for ( i = 0; i < 5; i++ ) {
         out = stdlib_base_binomcoefln( a[ i ], b[ i ] );
-        printf( "binomcoefln(%" PRId64 ", %" PRId64 ") = %lf\n", a[ i ], b[ i ], out );
+        printf( "binomcoefln(%lf, %lf) = %lf\n", a[ i ], b[ i ], out );
     }
 }
 ```

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

@@ -90,16 +90,16 @@ static double rand_double( void ) {
 * @return elapsed time in seconds
 */
 static double benchmark( void ) {
-	int64_t n[ 100 ];
-	int64_t k[ 100 ];
+	double n[ 100 ];
+	double k[ 100 ];
 	double elapsed;
 	double y;
 	double t;
 	int i;
 
 	for ( i = 0; i < 100; i++ ) {
-		n[ i ] = (int64_t)round( 500.0 * rand_double() );
-		k[ i ] = (int64_t)round( 500.0 * rand_double() );
+		n[ i ] = round( 500.0 * rand_double() );
+		k[ i ] = round( 500.0 * rand_double() );
 	}
 
 	t = tic();

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

@@ -18,17 +18,15 @@
 
 #include "stdlib/math/base/special/binomcoefln.h"
 #include <stdio.h>
-#include <stdint.h>
-#include <inttypes.h>
 
 int main( void ) {
-	const int64_t a[] = { 24, 32, 48, 116, 33 };
-	const int64_t b[] = { 12, 6, 15, 52, 22 };
+	const double a[] = { 24.0, 32.0, 48.0, 116.0, 33.0 };
+	const double b[] = { 12.0, 6.0, 15.0, 52.0, 22.0 };
 
 	double out;
 	int i;
 	for ( i = 0; i < 5; i++ ) {
 		out = stdlib_base_binomcoefln( a[ i ], b[ i ] );
-		printf( "binomcoefln(%" PRId64 ", %" PRId64 ") = %lf\n", a[ i ], b[ i ], out );
+		printf( "binomcoefln(%lf, %lf) = %lf\n", a[ i ], b[ i ], out );
 	}
 }

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

@@ -19,8 +19,6 @@
 #ifndef STDLIB_MATH_BASE_SPECIAL_BINOMCOEFLN_H
 #define STDLIB_MATH_BASE_SPECIAL_BINOMCOEFLN_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 natural logarithm of the binomial coefficient of two integers.
 */
-double stdlib_base_binomcoefln( const int64_t n, const int64_t k );
+double stdlib_base_binomcoefln( const double n, const double k );
 
 #ifdef __cplusplus
 }

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

@@ -42,7 +42,8 @@
         "@stdlib/math/base/special/betaln",
         "@stdlib/math/base/special/abs",
         "@stdlib/math/base/special/ln",
-        "@stdlib/constants/float64/ninf"
+        "@stdlib/constants/float64/ninf",
+        "@stdlib/math/base/assert/is-integer"
       ]
     },
     {
@@ -61,7 +62,8 @@
         "@stdlib/math/base/special/betaln",
         "@stdlib/math/base/special/abs",
         "@stdlib/math/base/special/ln",
-        "@stdlib/constants/float64/ninf"
+        "@stdlib/constants/float64/ninf",
+        "@stdlib/math/base/assert/is-integer"
       ]
     },
     {
@@ -80,7 +82,8 @@
         "@stdlib/math/base/special/betaln",
         "@stdlib/math/base/special/abs",
         "@stdlib/math/base/special/ln",
-        "@stdlib/constants/float64/ninf"
+        "@stdlib/constants/float64/ninf",
+        "@stdlib/math/base/assert/is-integer"
       ]
     }
   ]

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

@@ -19,4 +19,4 @@
 #include "stdlib/math/base/special/binomcoefln.h"
 #include "stdlib/math/base/napi/binary.h"
 
-STDLIB_MATH_BASE_NAPI_MODULE_LL_D( stdlib_base_binomcoefln )
+STDLIB_MATH_BASE_NAPI_MODULE_DD_D( stdlib_base_binomcoefln )

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

@@ -17,11 +17,11 @@
 */
 
 #include "stdlib/math/base/special/binomcoefln.h"
+#include "stdlib/math/base/assert/is_integer.h"
 #include "stdlib/math/base/special/betaln.h"
 #include "stdlib/math/base/special/abs.h"
 #include "stdlib/math/base/special/ln.h"
 #include "stdlib/constants/float64/ninf.h"
-#include <stdint.h>
 
 /**
 * Computes the natural logarithm of the binomial coefficient of two integers.
@@ -31,10 +31,13 @@
 * @return     function value
 *
 * @example
-* double out = stdlib_base_binomcoefln( 8, 2 );
+* double out = stdlib_base_binomcoefln( 8.0, 2.0 );
 * // returns ~3.332
 */
-double stdlib_base_binomcoefln( const int64_t n, const int64_t k ) {
+double stdlib_base_binomcoefln( const double n, const double k ) {
+	if ( !stdlib_base_is_integer( n ) || !stdlib_base_is_integer( k ) ) {
+		return 0.0 / 0.0; // NaN
+	}
 	if ( n < 0 ) {
 		return stdlib_base_binomcoefln( -n + k - 1, k );
 	}
@@ -45,7 +48,7 @@ double stdlib_base_binomcoefln( const int64_t n, const int64_t k ) {
 		return 0.0;
 	}
 	if ( k == 1 ) {
-		return stdlib_base_ln( stdlib_base_abs( (double)n ) );
+		return stdlib_base_ln( stdlib_base_abs( n ) );
 	}
 	if ( n < k ) {
 		return STDLIB_CONSTANT_FLOAT64_NINF;
@@ -55,5 +58,5 @@ double stdlib_base_binomcoefln( const int64_t n, const int64_t k ) {
 	}
 
 	// Case: n - k >= 2
-	return -stdlib_base_ln( (double)(n + 1) ) - stdlib_base_betaln( (double)(n - k + 1), (double)(k + 1) );
+	return -stdlib_base_ln( ( n + 1 ) ) - stdlib_base_betaln( ( n - k + 1 ), ( k + 1 ) );
 }