feat: add C ndarray API and refactor blas/ext/base/dnannsum

PR-URL: #3197
Reviewed-by: Athan Reines <[email protected]>
Co-authored-by: stdlib-bot <[email protected]>

Author: headlessNode

lib/node_modules/@stdlib/blas/ext/base/dnannsum/README.md

@@ -54,11 +54,11 @@ The function has the following parameters:
 
 -   **N**: number of indexed elements.
 -   **x**: input [`Float64Array`][@stdlib/array/float64].
--   **strideX**: index increment for `x`.
+-   **strideX**: stride length for `x`.
 -   **out**: output [`Float64Array`][@stdlib/array/float64] whose first element is the sum and whose second element is the number of non-NaN elements.
--   **strideOut**: index increment for `out`.
+-   **strideOut**: stride length for `out`.
 
-The `N` and `stride` parameters determine which elements in the strided array are accessed at runtime. For example, to compute the sum of every other element in the strided array,
+The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the sum of every other element in the strided array:
 
 ```javascript
 var Float64Array = require( '@stdlib/array/float64' );
@@ -106,7 +106,7 @@ The function has the following additional parameters:
 -   **offsetX**: starting index for `x`.
 -   **offsetOut**: starting index for `out`.
 
-While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to calculate the sum of every other value in the strided array starting from the second value
+While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameters support indexing semantics based on starting indices. For example, to calculate the sum of every other element starting from the second element:
 
 ```javascript
 var Float64Array = require( '@stdlib/array/float64' );
@@ -145,14 +145,14 @@ var filledarrayBy = require( '@stdlib/array/filled-by' );
 var Float64Array = require( '@stdlib/array/float64' );
 var dnannsum = require( '@stdlib/blas/ext/base/dnannsum' );
 
-function clbk() {
+function rand() {
     if ( bernoulli( 0.7 ) > 0 ) {
         return discreteUniform( 0, 100 );
     }
     return NaN;
 }
 
-var x = filledarrayBy( 10, 'float64', clbk );
+var x = filledarrayBy( 10, 'float64', rand );
 console.log( x );
 
 var out = new Float64Array( 2 );
@@ -164,6 +164,136 @@ console.log( out );
 
 <!-- /.examples -->
 
+<!-- C interface documentation. -->
+
+* * *
+
+<section class="c">
+
+## C APIs
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- C usage documentation. -->
+
+<section class="usage">
+
+### Usage
+
+```c
+#include "stdlib/blas/ext/base/dnannsum.h"
+```
+
+#### stdlib_strided_dnannsum( N, \*X, strideX, \*n )
+
+Computes the sum of double-precision floating-point strided array elements, ignoring `NaN` values.
+
+```c
+#include "stdlib/blas/base/shared.h"
+
+const double x[] = { 1.0, 2.0, 0.0/0.0, 4.0 };
+CBLAS_INT n = 0;
+
+double v = stdlib_strided_dnannsum( 4, x, 1, &n );
+// returns 7.0
+```
+
+The function accepts the following arguments:
+
+-   **N**: `[in] CBLAS_INT` number of indexed elements.
+-   **X**: `[in] double*` input array.
+-   **strideX**: `[in] CBLAS_INT` stride length for `X`.
+-   **n**: `[out] CBLAS_INT*` pointer for storing the number of non-NaN elements.
+
+```c
+double stdlib_strided_dnannsum( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, CBLAS_INT *n );
+```
+
+#### stdlib_strided_dnannsum_ndarray( N, \*X, strideX, offsetX, \*n )
+
+Computes the sum of double-precision floating-point strided array elements, ignoring `NaN` values and using alternative indexing semantics.
+
+```c
+#include "stdlib/blas/base/shared.h"
+
+const double x[] = { 1.0, 2.0, 0.0/0.0, 4.0 };
+CBLAS_INT n = 0; 
+
+double v = stdlib_strided_dnannsum_ndarray( 4, x, 1, 0, &n );
+// returns 7.0
+```
+
+The function accepts the following arguments:
+
+-   **N**: `[in] CBLAS_INT` number of indexed elements.
+-   **X**: `[in] double*` input array.
+-   **strideX**: `[in] CBLAS_INT` stride length for `X`.
+-   **offsetX**: `[in] CBLAS_INT` starting index for `X`.
+-   **n**: `[out] CBLAS_INT*` pointer for storing the number of non-NaN elements.
+
+```c
+double stdlib_strided_dnannsum_ndarray( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX, CBLAS_INT *n );
+```
+
+</section>
+
+<!-- /.usage -->
+
+<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+</section>
+
+<!-- /.notes -->
+
+<!-- C API usage examples. -->
+
+<section class="examples">
+
+### Examples
+
+```c
+#include "stdlib/blas/ext/base/dnannsum.h"
+#include "stdlib/blase/base/shared.h"
+#include <stdio.h>
+
+int main( void ) {
+    // Create a strided array:
+    const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 0.0/0.0, 0.0/0.0 };
+
+    // Specify the number of elements:
+    const int N = 5;
+
+    // Specify the stride length:
+    const int strideX = 2;
+
+    // Initialize a variable for storing the number of non-NaN elements:
+    CBLAS_INT n = 0;
+
+    // Compute the sum:
+    double v = stdlib_strided_dnannsum( N, x, strideX, &n );
+
+    // Print the result:
+    printf( "sum: %lf\n", v );
+    printf( "n: %"CBLAS_IFMT"\n", n );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+</section>
+
+<!-- /.c -->
+
 <section class="references">
 
 </section>

lib/node_modules/@stdlib/blas/ext/base/dnannsum/benchmark/benchmark.js

@@ -33,6 +33,19 @@ var dnannsum = require( './../lib/dnannsum.js' );
 
 // FUNCTIONS //
 
+/**
+* Returns a random number.
+*
+* @private
+* @returns {number} random number
+*/
+function rand() {
+	if ( bernoulli( 0.7 ) > 0 ) {
+		return discreteUniform( -10, 10 );
+	}
+	return NaN;
+}
+
 /**
 * Creates a benchmark function.
 *
@@ -44,17 +57,10 @@ function createBenchmark( len ) {
 	var out;
 	var x;
 
-	x = filledarrayBy( len, 'float64', clbk );
+	x = filledarrayBy( len, 'float64', rand );
 	out = new Float64Array( 2 );
 	return benchmark;
 
-	function clbk() {
-		if ( bernoulli( 0.7 ) > 0 ) {
-			return discreteUniform( -10, 10 );
-		}
-		return NaN;
-	}
-
 	function benchmark( b ) {
 		var i;
 

lib/node_modules/@stdlib/blas/ext/base/dnannsum/benchmark/benchmark.native.js

@@ -42,6 +42,19 @@ var opts = {
 
 // FUNCTIONS //
 
+/**
+* Returns a random number.
+*
+* @private
+* @returns {number} random number
+*/
+function rand() {
+	if ( bernoulli( 0.7 ) > 0 ) {
+		return discreteUniform( -10, 10 );
+	}
+	return NaN;
+}
+
 /**
 * Creates a benchmark function.
 *
@@ -53,17 +66,10 @@ function createBenchmark( len ) {
 	var out;
 	var x;
 
-	x = filledarrayBy( len, 'float64', clbk );
+	x = filledarrayBy( len, 'float64', rand );
 	out = new Float64Array( 2 );
 	return benchmark;
 
-	function clbk() {
-		if ( bernoulli( 0.7 ) > 0 ) {
-			return discreteUniform( -10, 10 );
-		}
-		return NaN;
-	}
-
 	function benchmark( b ) {
 		var i;
 

lib/node_modules/@stdlib/blas/ext/base/dnannsum/benchmark/benchmark.ndarray.js

@@ -33,6 +33,19 @@ var dnannsum = require( './../lib/ndarray.js' );
 
 // FUNCTIONS //
 
+/**
+* Returns a random number.
+*
+* @private
+* @returns {number} random number
+*/
+function rand() {
+	if ( bernoulli( 0.7 ) > 0 ) {
+		return discreteUniform( -10, 10 );
+	}
+	return NaN;
+}
+
 /**
 * Creates a benchmark function.
 *
@@ -44,17 +57,10 @@ function createBenchmark( len ) {
 	var out;
 	var x;
 
-	x = filledarrayBy( len, 'float64', clbk );
+	x = filledarrayBy( len, 'float64', rand );
 	out = new Float64Array( 2 );
 	return benchmark;
 
-	function clbk() {
-		if ( bernoulli( 0.7 ) > 0 ) {
-			return discreteUniform( -10, 10 );
-		}
-		return NaN;
-	}
-
 	function benchmark( b ) {
 		var i;
 

lib/node_modules/@stdlib/blas/ext/base/dnannsum/benchmark/benchmark.ndarray.native.js

@@ -42,6 +42,19 @@ var opts = {
 
 // FUNCTIONS //
 
+/**
+* Returns a random number.
+*
+* @private
+* @returns {number} random number
+*/
+function rand() {
+	if ( bernoulli( 0.7 ) > 0 ) {
+		return discreteUniform( -10, 10 );
+	}
+	return NaN;
+}
+
 /**
 * Creates a benchmark function.
 *
@@ -53,17 +66,10 @@ function createBenchmark( len ) {
 	var out;
 	var x;
 
-	x = filledarrayBy( len, 'float64', clbk );
+	x = filledarrayBy( len, 'float64', rand );
 	out = new Float64Array( 2 );
 	return benchmark;
 
-	function clbk() {
-		if ( bernoulli( 0.7 ) > 0 ) {
-			return discreteUniform( -10, 10 );
-		}
-		return NaN;
-	}
-
 	function benchmark( b ) {
 		var i;