refactor!: modify C implementation to accept float values instead of int32 in math/base/special/binomcoeff

This commit updates the signature of the C API to accept a float 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 floats

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

Author: gunjjoshi

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

@@ -162,17 +162,17 @@ logEachMap( 'binomcoeff(%d,%d) = %0.4f', n, k, binomcoeff );
 Evaluates the [binomial coefficient][binomial-coefficient] of two integers `n` and `k` as a single-precision floating-point number.
 
 ```c
-float v = stdlib_base_binomcoeff( 8, 2 );
+float v = stdlib_base_binomcoeff( 8.0f, 2.0f );
 // returns 28.0f
 ```
 
 The function accepts the following arguments:
 
--   **n**: `[in] int32_t` input value.
--   **k**: `[in] int32_t` input value.
+-   **n**: `[in] float` input value.
+-   **k**: `[in] float` input value.
 
 ```c
-float stdlib_base_binomcoeff( const int32_t n, const int32_t k );
+float stdlib_base_binomcoeff( const float n, const float k );
 ```
 
 </section>
@@ -196,17 +196,16 @@ float stdlib_base_binomcoeff( const int32_t n, const int32_t k );
 ```c
 #include "stdlib/math/base/special/binomcoeff.h"
 #include <stdio.h>
-#include <stdint.h>
 
 int main( void ) {
-    const int32_t a[] = { 24, 32, 48, 116, 33 };
-    const int32_t b[] = { 12, 6, 15, 52, 22 };
+    const float a[] = { 24.0f, 32.0f, 48.0f, 116.0f, 33.0f };
+    const float b[] = { 12.0f, 6.0f, 15.0f, 52.0f, 22.0f };
 
     float out;
     int i;
     for ( i = 0; i < 5; i++ ) {
         out = stdlib_base_binomcoeff( a[ i ], b[ i ] );
-        printf( "binomcoeff(%d, %d) = %f\n", a[ i ], b[ i ], out );
+        printf( "binomcoeff(%f, %f) = %f\n", a[ i ], b[ i ], out );
     }
 }
 ```

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

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

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

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

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

@@ -19,8 +19,6 @@
 #ifndef STDLIB_MATH_BASE_SPECIAL_BINOMCOEFF_H
 #define STDLIB_MATH_BASE_SPECIAL_BINOMCOEFF_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 binomial coefficient of two integers as a single-precision floating-point number.
 */
-float stdlib_base_binomcoeff( const int32_t n, const int32_t k );
+float stdlib_base_binomcoeff( const float n, const float k );
 
 #ifdef __cplusplus
 }

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

@@ -42,7 +42,9 @@
         "@stdlib/math/base/special/floorf",
         "@stdlib/math/base/special/gcdf",
         "@stdlib/constants/float32/pinf",
-        "@stdlib/constants/float32/max-safe-integer"
+        "@stdlib/constants/float32/max-safe-integer",
+        "@stdlib/math/base/assert/is-integerf",
+        "@stdlib/math/base/assert/is-oddf"
       ]
     },
     {
@@ -61,7 +63,9 @@
         "@stdlib/math/base/special/floorf",
         "@stdlib/math/base/special/gcdf",
         "@stdlib/constants/float32/pinf",
-        "@stdlib/constants/float32/max-safe-integer"
+        "@stdlib/constants/float32/max-safe-integer",
+        "@stdlib/math/base/assert/is-integerf",
+        "@stdlib/math/base/assert/is-oddf"
       ]
     },
     {
@@ -80,7 +84,9 @@
         "@stdlib/math/base/special/floorf",
         "@stdlib/math/base/special/gcdf",
         "@stdlib/constants/float32/pinf",
-        "@stdlib/constants/float32/max-safe-integer"
+        "@stdlib/constants/float32/max-safe-integer",
+        "@stdlib/math/base/assert/is-integerf",
+        "@stdlib/math/base/assert/is-oddf"
       ]
     }
   ]

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

@@ -19,4 +19,4 @@
 #include "stdlib/math/base/special/binomcoeff.h"
 #include "stdlib/math/base/napi/binary.h"
 
-STDLIB_MATH_BASE_NAPI_MODULE_II_F( stdlib_base_binomcoeff )
+STDLIB_MATH_BASE_NAPI_MODULE_FF_F( stdlib_base_binomcoeff )

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

@@ -17,11 +17,12 @@
 */
 
 #include "stdlib/math/base/special/binomcoeff.h"
+#include "stdlib/math/base/assert/is_integerf.h"
+#include "stdlib/math/base/assert/is_oddf.h"
 #include "stdlib/math/base/special/floorf.h"
 #include "stdlib/math/base/special/gcdf.h"
 #include "stdlib/constants/float32/pinf.h"
 #include "stdlib/constants/float32/max_safe_integer.h"
-#include <stdint.h>
 
 /**
 * Computes the binomial coefficient of two integers as a single-precision floating-point number.
@@ -31,28 +32,31 @@
 * @return     function value
 *
 * @example
-* float out = stdlib_base_binomcoeff( 8, 2 );
+* float out = stdlib_base_binomcoeff( 8.0f, 2.0f );
 * // returns 28.0f
 */
-float stdlib_base_binomcoeff( const int32_t n, const int32_t k ) {
-	int32_t nc;
-	int32_t kc;
-	int32_t d;
+float stdlib_base_binomcoeff( const float n, const float k ) {
 	float res;
 	float sgn;
+	float nc;
+	float kc;
+	float d;
 	float b;
 	float c;
 	float g;
 	float s;
 
+	if ( !stdlib_base_is_integerf( n ) || !stdlib_base_is_integerf( k ) ) {
+		return 0.0f / 0.0f; // NaN
+	}
 	if ( k < 0 ) {
 		return 0.0f;
 	}
 	sgn = 1.0f;
 	nc = n;
 	if ( nc < 0 ) {
 		nc = -nc + k - 1;
-		if ( k & 1 ) {
+		if ( stdlib_base_is_oddf( k ) ) {
 			sgn *= -1.0f;
 		}
 	}
@@ -63,25 +67,25 @@ float stdlib_base_binomcoeff( const int32_t n, const int32_t k ) {
 		return sgn;
 	}
 	if ( k == 1 || k == nc - 1 ) {
-		return sgn * (float)nc;
+		return sgn * nc;
 	}
 
 	// Minimize the number of computed terms by leveraging symmetry:
 	kc = k;
 	if ( nc - kc < kc ) {
 		kc = nc - kc;
 	}
-	s = stdlib_base_floorf( (float)STDLIB_CONSTANT_FLOAT32_MAX_SAFE_INTEGER / (float)nc );
+	s = stdlib_base_floorf( (float)STDLIB_CONSTANT_FLOAT32_MAX_SAFE_INTEGER / nc );
 
 	// Use a standard algorithm for computing the binomial coefficient
 	res = 1.0f;
-	for ( d = 1; d <= kc; d++ ) {
+	for ( d = 1.0f; d <= kc; d++ ) {
 		// Check for potential overflow...
 		if ( res > s ) {
 			break;
 		}
-		res *= (float)nc;
-		res /= (float)d;
+		res *= nc;
+		res /= d;
 		nc -= 1;
 	}
 
@@ -110,7 +114,7 @@ float stdlib_base_binomcoeff( const int32_t n, const int32_t k ) {
 	if ( b == STDLIB_CONSTANT_FLOAT32_PINF ) {
 		return sgn * b;
 	}
-	c = stdlib_base_binomcoeff( kc, kc-d+1 ) ;
+	c = stdlib_base_binomcoeff( kc, kc-d+1 );
 
 	/*
 	* At this point, the result should be `res*b/c`.