feat : add blas/base/crotg

lib/node_modules/@stdlib/blas/base/crotg/.npmignore

@@ -0,0 +1,3 @@
+test/
+benchmark/
+examples/

lib/node_modules/@stdlib/blas/base/crotg/README.md

@@ -0,0 +1,298 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# crotg
+
+> Construct a Givens plane rotation for complex single-precision floating-point numbers.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var crotg = require( '@stdlib/blas/base/crotg' );
+```
+
+#### crotg( ar, ai, br, bi\[, out\[, stride\[, offset]]] )
+
+Constructs a Givens plane rotation for complex single-precision floating-point numbers.
+
+```javascript
+var Complex64Array = require( '@stdlib/array/complex64' );
+
+var out = crotg( 0.0, 0.0, 2.0, 0.0 );
+// returns <Complex64Array>[ 2.0, 0.0, 1.0, 0.0, 0.0, 0.0 ]
+```
+
+The function accepts the following arguments:
+
+-   **ar**: real component of the rotational elimination parameter `a`.
+-   **ai**: imaginary component of the rotational elimination parameter `a`.
+-   **br**: real component of the rotational elimination parameter `b`.
+-   **bi**: imaginary component of the rotational elimination parameter `b`.
+-   **out**: output [`Complex64Array`][@stdlib/array/complex64] (optional).
+-   **stride**: index increment (optional).
+-   **offset**: starting index (optional).
+
+The function returns a [`Complex64Array`][@stdlib/array/complex64] containing the following elements:
+
+-   `out[ 0 ]`: real component of the rotational elimination parameter `r`
+-   `out[ 1 ]`: imaginary component of the rotational elimination parameter `r`
+-   `out[ 2 ]`: real component of the rotational elimination parameter `s`
+-   `out[ 3 ]`: imaginary component of the rotational elimination parameter `s`
+-   `out[ 4 ]`: cosine of the angle of rotation `c`
+-   `out[ 5 ]`: zero (reserved)
+
+#### crotg.ndarray( ar, ai, br, bi, out, stride, offset )
+
+Constructs a Givens plane rotation for complex single-precision floating-point numbers using alternative indexing semantics.
+
+```javascript
+var Complex64Array = require( '@stdlib/array/complex64' );
+
+var out = new Complex64Array( 3 );
+var y = crotg.ndarray( 0.0, 0.0, 2.0, 0.0, out, 1, 0 );
+// returns <Complex64Array>[ 2.0, 0.0, 1.0, 0.0, 0.0, 0.0 ]
+```
+
+The function accepts the following arguments:
+
+-   **ar**: real component of the rotational elimination parameter `a`.
+-   **ai**: imaginary component of the rotational elimination parameter `a`.
+-   **br**: real component of the rotational elimination parameter `b`.
+-   **bi**: imaginary component of the rotational elimination parameter `b`.
+-   **out**: output [`Complex64Array`][@stdlib/array/complex64].
+-   **stride**: index increment.
+-   **offset**: starting index.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   `crotg` corresponds to the BLAS level 1 function [`crotg`][crotg].
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
+var Complex64Array = require( '@stdlib/array/complex64' );
+var crotg = require( '@stdlib/blas/base/crotg' );
+
+function rand() {
+    return discreteUniform( -10, 10 );
+}
+
+var out = new Complex64Array( 3 );
+var ar;
+var ai;
+var br;
+var bi;
+var i;
+
+for ( i = 0; i < 10; i++ ) {
+    ar = rand();
+    ai = rand();
+    br = rand();
+    bi = rand();
+
+    crotg( ar, ai, br, bi, out, 1, 0 );
+
+    console.log( 'a: %d + %dj', ar, ai );
+    console.log( 'b: %d + %dj', br, bi );
+    console.log( 'r: %s', out.get( 0 ).toString() );
+    console.log( 's: %s', out.get( 1 ).toString() );
+    console.log( 'c: %d', out.get( 2 ).re );
+    console.log( '' );
+}
+```
+
+</section>
+
+<!-- /.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/base/crotg.h"
+```
+
+#### stdlib_blas_base_crotg( \*ca, \*cb, \*c, \*s )
+
+Constructs a Givens plane rotation for complex single-precision floating-point numbers.
+
+```c
+float ca[] = { 1.0f, 2.0f };
+float cb[] = { 3.0f, 4.0f };
+float c;
+float s[] = { 0.0f, 0.0f };
+
+stdlib_blas_base_crotg( (void *)ca, (void *)cb, &c, (void *)s );
+```
+
+The function accepts the following arguments:
+
+-   **ca**: `[inout] void*` complex single-precision floating-point number `a`.
+-   **cb**: `[inout] void*` complex single-precision floating-point number `b`.
+-   **c**: `[out] float*` cosine of the angle of rotation.
+-   **s**: `[out] void*` sine of the angle of rotation.
+
+```c
+void stdlib_blas_base_crotg( void *ca, void *cb, float *c, void *s );
+```
+
+#### c_crotg_ndarray( ar, ai, br, bi, \*out, stride, offset )
+
+Constructs a Givens plane rotation for complex single-precision floating-point numbers using alternative indexing semantics.
+
+```c
+float out[] = { 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f };
+
+c_crotg_ndarray( 1.0f, 2.0f, 3.0f, 4.0f, (void *)out, 1, 0 );
+```
+
+The function accepts the following arguments:
+
+-   **ar**: `[in] float` real component of the rotational elimination parameter `a`.
+-   **ai**: `[in] float` imaginary component of the rotational elimination parameter `a`.
+-   **br**: `[in] float` real component of the rotational elimination parameter `b`.
+-   **bi**: `[in] float` imaginary component of the rotational elimination parameter `b`.
+-   **out**: `[out] void*` output array.
+-   **stride**: `[in] CBLAS_INT` index increment.
+-   **offset**: `[in] CBLAS_INT` starting index.
+
+```c
+void c_crotg_ndarray( const float ar, const float ai, const float br, const float bi, void *out, const CBLAS_INT stride, const CBLAS_INT offset );
+```
+
+</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/base/crotg.h"
+#include <stdio.h>
+
+int main( void ) {
+    float ca[] = { 1.0f, 2.0f };
+    float cb[] = { 3.0f, 4.0f };
+    float s[] = { 0.0f, 0.0f };
+    float c = 0.0f;
+
+    printf( "a: %f + %fj\n", ca[ 0 ], ca[ 1 ] );
+    printf( "b: %f + %fj\n", cb[ 0 ], cb[ 1 ] );
+
+    stdlib_blas_base_crotg( (void *)ca, (void *)cb, &c, (void *)s );
+
+    printf( "r: %f + %fj\n", ca[ 0 ], ca[ 1 ] );
+    printf( "c: %f\n", c );
+    printf( "s: %f + %fj\n", s[ 0 ], s[ 1 ] );
+    printf( "\n" );
+
+    // Using ndarray interface:
+    float ar = 5.0f;
+    float ai = 6.0f;
+    float br = 7.0f;
+    float bi = 8.0f;
+    float out[] = { 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f }; // r_re, r_im, s_re, s_im, c, 0
+
+    printf( "a: %f + %fj\n", ar, ai );
+    printf( "b: %f + %fj\n", br, bi );
+
+    c_crotg_ndarray( ar, ai, br, bi, (void *)out, 1, 0 );
+
+    printf( "r: %f + %fj\n", out[ 0 ], out[ 1 ] );
+    printf( "s: %f + %fj\n", out[ 2 ], out[ 3 ] );
+    printf( "c: %f\n", out[ 4 ] );
+}
+```
+
+</section>
+
+<!-- /.examples -->
+
+</section>
+
+<!-- /.c -->
+
+<!-- Section for related `stdlib` packages. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and use `[link_label]: url` code to define the links. -->
+
+<section class="links">
+
+[crotg]: http://www.netlib.org/lapack/explore-html/d8/d56/crotg_8f.html
+
+[@stdlib/array/complex64]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/complex64
+
+</section>
+
+<!-- /.links -->