feat: add benchmarks, examples, docs

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: passed
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - task: lint_javascript_tests
    status: na
  - task: lint_javascript_benchmarks
    status: passed
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: passed
  - task: lint_c_examples
    status: passed
  - task: lint_c_benchmarks
    status: passed
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

Author: anandkaranubc

lib/node_modules/@stdlib/math/base/special/kernel-cosf/README.md

@@ -18,63 +18,40 @@ limitations under the License.
 
 -->
 
-# kernelCos
+# kernelCosf
 
-> Compute the [cosine][cosine] of a double-precision floating-point number on `[-π/4, π/4]`.
+> Compute the [cosine][cosine] of a single-precision floating-point number on `[-π/4, π/4]`.
 
 <section class="usage">
 
 ## Usage
 
 ```javascript
-var kernelCos = require( '@stdlib/math/base/special/kernel-cos' );
+var kernelCosf = require( '@stdlib/math/base/special/kernel-cosf' );
 ```
 
-#### kernelCos( x, y )
+#### kernelCosf( x )
 
-Computes the [cosine][cosine] of a double-precision floating-point number on `[-π/4, π/4]`.
+Computes the [cosine][cosine] of a single-precision floating-point number on `[-π/4, π/4]`.
 
 ```javascript
-var v = kernelCos( 0.0, 0.0 );
+var v = kernelCosf( 0.0 );
 // returns ~1.0
 
-v = kernelCos( 3.141592653589793/6.0, 0.0 );
+v = kernelCosf( 3.141592653589793/6.0 );
 // returns ~0.866
 
-v = kernelCos( 0.785, -1.144e-17 );
+v = kernelCosf( 0.785 );
 // returns ~0.707
 
-v = kernelCos( NaN, 0.0 );
+v = kernelCosf( NaN );
 // returns NaN
 ```
 
 </section>
 
 <!-- /.usage -->
 
-<section class="notes">
-
-## Notes
-
--   For increased accuracy, the number for which the [cosine][cosine] should be evaluated can be supplied as a [double-double number][double-double-arithmetic] (i.e., a non-evaluated sum of two [double-precision floating-point numbers][ieee754] `x` and `y`).
-
--   As components of a [double-double number][double-double-arithmetic], the two [double-precision floating-point numbers][ieee754] `x` and `y` must satisfy 
-
-    <!-- <equation class="equation" label="eq:double_double_inequality" align="center" raw="|y| \leq \frac{1}{2} \operatorname{ulp}(x)" alt="Inequality for the two components of a double-double number."> -->
-
-    <div class="equation" align="center" data-raw-text="|y| \leq \frac{1}{2} \operatorname{ulp}(x)" data-equation="eq:double_double_inequality">
-        <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@bb29798906e119fcb2af99e94b60407a270c9b32/lib/node_modules/@stdlib/math/base/special/kernel-cos/docs/img/equation_double_double_inequality.svg" alt="Inequality for the two components of a double-double number.">
-        <br>
-    </div>
-
-    <!-- </equation> -->
-
-    where `ulp` stands for [units in the last place][ulp].
-
-</section>
-
-<!-- /.notes -->
-
 <section class="examples">
 
 ## Examples
@@ -84,13 +61,13 @@ v = kernelCos( NaN, 0.0 );
 ```javascript
 var linspace = require( '@stdlib/array/base/linspace' );
 var PI = require( '@stdlib/constants/float64/pi' );
-var kernelCos = require( '@stdlib/math/base/special/kernel-cos' );
+var kernelCosf = require( '@stdlib/math/base/special/kernel-cosf' );
 
 var x = linspace( -PI/4.0, PI/4.0, 100 );
 
 var i;
 for ( i = 0; i < x.length; i++ ) {
-    console.log( 'kernelCos(%d) = %d', x[ i ], kernelCos( x[ i ], 0.0 ) );
+    console.log( 'kernelCosf(%d) = %d', x[ i ], kernelCosf( x[ i ] ) );
 }
 ```
 
@@ -121,28 +98,27 @@ for ( i = 0; i < x.length; i++ ) {
 ### Usage
 
 ```c
-#include "stdlib/math/base/special/kernel_cos.h"
+#include "stdlib/math/base/special/kernel_cosf.h"
 ```
 
-#### stdlib_base_kernel_cos( x, y )
+#### stdlib_base_kernel_cosf( x )
 
-Computes the [cosine][cosine] of a double-precision floating-point number on `[-π/4, π/4]`.
+Computes the [cosine][cosine] of a single-precision floating-point number on `[-π/4, π/4]`.
 
 ```c
-var v = stdlib_base_kernel_cos( 0.0, 0.0 );
-// returns ~0.0
+float v = stdlib_base_kernel_cosf( 0.0f );
+// returns ~0.0f
 
-v = stdlib_base_kernel_cos( 3.141592653589793/6.0, 0.0 );
-// returns ~0.866
+v = stdlib_base_kernel_cosf( 3.141592653589793/6.0f );
+// returns ~0.866f
 ```
 
 The function accepts the following arguments:
 
--   **x**: `[in] double` input value (in radians, assumed to be bounded by `~pi/4` in magnitude).
--   **y**: `[in] double` tail of `x`.
+-   **x**: `[in] float` input value (in radians, assumed to be bounded by `~pi/4` in magnitude).
 
 ```c
-double stdlib_base_kernel_cos( const double x, const double y );
+float stdlib_base_kernel_cosf( const float x );
 ```
 
 </section>
@@ -153,10 +129,6 @@ double stdlib_base_kernel_cos( const double x, const double y );
 
 <section class="notes">
 
-### Notes
-
--   For increased accuracy, the number for which the [cosine][cosine] should be evaluated can be supplied as a [double-double number][double-double-arithmetic] (i.e., a non-evaluated sum of two [double-precision floating-point numbers][ieee754] `x` and `y`).
-
 </section>
 
 <!-- /.notes -->
@@ -168,17 +140,17 @@ double stdlib_base_kernel_cos( const double x, const double y );
 ### Examples
 
 ```c
-#include "stdlib/math/base/special/kernel_cos.h"
+#include "stdlib/math/base/special/kernel_cosf.h"
 #include <stdio.h>
 
 int main( void ) {
-    const double x[] = { -0.7853981633974483, -0.6108652381980153, -0.4363323129985824, -0.26179938779914946, -0.08726646259971649, 0.08726646259971649, 0.26179938779914935, 0.43633231299858233, 0.6108652381980153, 0.7853981633974483 };
+    const float x[] = { -0.7853981633974483f, -0.6108652381980153f, -0.4363323129985824f, -0.26179938779914946f, -0.08726646259971649f, 0.08726646259971649f, 0.26179938779914935f, 0.43633231299858233f, 0.6108652381980153f, 0.7853981633974483f };
 
-    double out;
+    float v;
     int i;
     for ( i = 0; i < 10; i++ ) {
-        out = stdlib_base_kernel_cos( x[ i ], 0.0 );
-        printf ( "x[ i ]: %lf, y: %lf, out: %lf\n", x[ i ], 0.0, out );
+        v = stdlib_base_kernel_cosf( x[ i ] );
+        printf( "kernelCosf(%f) = %f\n", x[ i ], v );
     }
 }
 ```
@@ -195,14 +167,6 @@ int main( void ) {
 
 <section class="related">
 
-* * *
-
-## See Also
-
--   <span class="package-name">[`@stdlib/math/base/special/cos`][@stdlib/math/base/special/cos]</span><span class="delimiter">: </span><span class="description">compute the cosine of a number.</span>
--   <span class="package-name">[`@stdlib/math/base/special/kernel-sin`][@stdlib/math/base/special/kernel-sin]</span><span class="delimiter">: </span><span class="description">compute the sine of a double-precision floating-point number on \[-π/4, π/4].</span>
--   <span class="package-name">[`@stdlib/math/base/special/kernel-tan`][@stdlib/math/base/special/kernel-tan]</span><span class="delimiter">: </span><span class="description">compute the tangent of a double-precision floating-point number on \[-π/4, π/4].</span>
-
 </section>
 
 <!-- /.related -->
@@ -213,20 +177,8 @@ int main( void ) {
 
 [cosine]: https://en.wikipedia.org/wiki/Cosine
 
-[double-double-arithmetic]: https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format#Double-double_arithmetic
-
-[ieee754]: https://en.wikipedia.org/wiki/IEEE_floating_point
-
-[ulp]: https://en.wikipedia.org/wiki/Unit_in_the_last_place
-
 <!-- <related-links> -->
 
-[@stdlib/math/base/special/cos]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/cos
-
-[@stdlib/math/base/special/kernel-sin]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/kernel-sin
-
-[@stdlib/math/base/special/kernel-tan]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/math/base/special/kernel-tan
-
 <!-- </related-links> -->
 
 </section>

lib/node_modules/@stdlib/math/base/special/kernel-cosf/benchmark/benchmark.js

@@ -21,11 +21,11 @@
 // MODULES //
 
 var bench = require( '@stdlib/bench' );
-var randu = require( '@stdlib/random/base/randu' );
+var uniform = require( '@stdlib/random/array/uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var PI = require( '@stdlib/constants/float64/pi' );
 var pkg = require( './../package.json' ).name;
-var kernelCos = require( './../lib' );
+var kernelCosf = require( './../lib' );
 
 
 // MAIN //
@@ -35,10 +35,13 @@ bench( pkg, function benchmark( b ) {
 	var y;
 	var i;
 
+	x = uniform( 100, -PI/4.0, PI/4.0, {
+		'dtype': 'float32'
+	});
+
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		x = ( randu() * PI / 2 ) - ( PI / 4.0 );
-		y = kernelCos( x, 0.0 );
+		y = kernelCosf( x[ i % x.length ] );
 		if ( isnan( y ) ) {
 			b.fail( 'should not return NaN' );
 		}

lib/node_modules/@stdlib/math/base/special/kernel-cosf/benchmark/benchmark.native.js

@@ -22,7 +22,7 @@
 
 var resolve = require( 'path' ).resolve;
 var bench = require( '@stdlib/bench' );
-var randu = require( '@stdlib/random/base/randu' );
+var uniform = require( '@stdlib/random/array/uniform' );
 var isnan = require( '@stdlib/math/base/assert/is-nan' );
 var PI = require( '@stdlib/constants/float64/pi' );
 var tryRequire = require( '@stdlib/utils/try-require' );
@@ -31,9 +31,9 @@ var pkg = require( './../package.json' ).name;
 
 // VARIABLES //
 
-var kernelCos = tryRequire( resolve( __dirname, './../lib/native.js' ) );
+var kernelCosf = tryRequire( resolve( __dirname, './../lib/native.js' ) );
 var opts = {
-	'skip': ( kernelCos instanceof Error )
+	'skip': ( kernelCosf instanceof Error )
 };
 
 
@@ -44,10 +44,13 @@ bench( pkg+'::native', opts, function benchmark( b ) {
 	var y;
 	var i;
 
+	x = uniform( 100, -PI/4.0, PI/4.0, {
+		'dtype': 'float32'
+	});
+
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
-		x = ( randu() * PI/2.0 ) - ( PI/4.0 );
-		y = kernelCos( x, 0.0 );
+		y = kernelCosf( x[ i % x.length ] );
 		if ( isnan( y ) ) {
 			b.fail( 'should not return NaN' );
 		}

lib/node_modules/@stdlib/math/base/special/kernel-cosf/benchmark/c/native/benchmark.c

@@ -16,14 +16,14 @@
 * limitations under the License.
 */
 
-#include "stdlib/math/base/special/kernel_cos.h"
+#include "stdlib/math/base/special/kernel_cosf.h"
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>
 #include <time.h>
 #include <sys/time.h>
 
-#define NAME "kernel_cos"
+#define NAME "kernel_cosf"
 #define ITERATIONS 1000000
 #define REPEATS 3
 
@@ -79,9 +79,9 @@ static double tic( void ) {
 *
 * @return random number
 */
-static double rand_double( void ) {
+static float rand_float( void ) {
 	int r = rand();
-	return (double)r / ( (double)RAND_MAX + 1.0 );
+	return (float)r / ( (float)RAND_MAX + 1.0f );
 }
 
 /**
@@ -90,16 +90,19 @@ static double rand_double( void ) {
 * @return elapsed time in seconds
 */
 static double benchmark( void ) {
+	float x[ 100 ];
 	double elapsed;
-	double x;
 	double z;
 	double t;
 	int i;
 
+	for ( i = 0; i < 100; i++ ) {
+		x[ i ] = ( ( rand_float()*2.0f ) - 1.0f ) * 0.7853981633974483f;
+	}
+
 	t = tic();
 	for ( i = 0; i < ITERATIONS; i++ ) {
-		x = ( ( rand_double() * 2.0 ) - 1.0 ) * 0.7853981633974483;
-		z = stdlib_base_kernel_cos( x, 0.0 );
+		z = stdlib_base_kernel_cosf( x[ i%100 ] );
 		if ( z != z ) {
 			printf( "should not return NaN\n" );
 			break;

lib/node_modules/@stdlib/math/base/special/kernel-cosf/docs/img/equation_double_double_inequality.svg

@@ -17,16 +17,16 @@
 */
 
 
-#include "stdlib/math/base/special/kernel_cos.h"
+#include "stdlib/math/base/special/kernel_cosf.h"
 #include <stdio.h>
 
 int main( void ) {
-	const double x[] = { -0.7853981633974483, -0.6108652381980153, -0.4363323129985824, -0.26179938779914946, -0.08726646259971649, 0.08726646259971649, 0.26179938779914935, 0.43633231299858233, 0.6108652381980153, 0.7853981633974483 };
+	const float x[] = { -0.7853981633974483f, -0.6108652381980153f, -0.4363323129985824f, -0.26179938779914946f, -0.08726646259971649f, 0.08726646259971649f, 0.26179938779914935f, 0.43633231299858233f, 0.6108652381980153f, 0.7853981633974483f };
 
-	double out;
+	float v;
 	int i;
 	for ( i = 0; i < 10; i++ ) {
-		out = stdlib_base_kernel_cos( x[ i ], 0.0 );
-		printf ( "x[ i ]: %lf, y: %lf, out: %lf\n", x[ i ], 0.0, out );
+		v = stdlib_base_kernel_cosf( x[ i ] );
+		printf( "kernelCosf(%f) = %f\n", x[ i ], v );
 	}
 }

lib/node_modules/@stdlib/math/base/special/kernel-cosf/examples/c/example.c

@@ -20,11 +20,11 @@
 
 var linspace = require( '@stdlib/array/base/linspace' );
 var PI = require( '@stdlib/constants/float64/pi' );
-var kernelCos = require( './../lib' );
+var kernelCosf = require( './../lib' );
 
 var x = linspace( -PI/4.0, PI/4.0, 100 );
 
 var i;
 for ( i = 0; i < x.length; i++ ) {
-	console.log( 'kernelCos(%d) = %d', x[ i ], kernelCos( x[ i ], 0.0 ) );
+	console.log( 'kernelCosf(%d) = %d', x[ i ], kernelCosf( x[ i ] ) );
 }