feat: add strided and assign APIs to complex/float32/base/mul

PR-URL: stdlib-js#5205
Closes: stdlib-js#5203
Co-authored-by: Athan Reines <[email protected]>
Reviewed-by: Athan Reines <[email protected]> 
Co-authored-by: stdlib-bot <[email protected]>

Author: 3 people

lib/node_modules/@stdlib/complex/float32/base/mul/README.md

@@ -58,6 +58,61 @@ var im = imagf( v );
 // returns -1.0
 ```
 
+#### mul.assign( re1, im1, re2, im2, out, strideOut, offsetOut )
+
+Multiplies two single-precision complex floating-point numbers and assigns results to a provided output array.
+
+```javascript
+var Float32Array = require( '@stdlib/array/float32' );
+
+var out = new Float32Array( 2 );
+var v = mul.assign( 5.0, 3.0, -2.0, 1.0, out, 1, 0 );
+// returns <Float32Array>[ -13.0, -1.0 ]
+
+var bool = ( out === v );
+// returns true
+```
+
+The function supports the following parameters:
+
+-   **re1**: real component of the first complex number.
+-   **im1**: imaginary component of the first complex number.
+-   **re2**: real component of the second complex number.
+-   **im2**: imaginary component of the second complex number.
+-   **out**: output array.
+-   **strideOut**: stride length for `out`.
+-   **offsetOut**: starting index for `out`.
+
+#### mul.strided( z1, sz1, oz1, z2, sz2, oz2, out, so, oo )
+
+Multiplies two single-precision complex floating-point numbers stored in real-valued strided array views and assigns results to a provided strided output array.
+
+```javascript
+var Float32Array = require( '@stdlib/array/float32' );
+
+var z1 = new Float32Array( [ 5.0, 3.0 ] );
+var z2 = new Float32Array( [ -2.0, 1.0 ] );
+var out = new Float32Array( 2 );
+
+var v = mul.strided( z1, 1, 0, z2, 1, 0, out, 1, 0 );
+// returns <Float32Array>[ -13.0, -1.0 ]
+
+var bool = ( out === v );
+// returns true
+```
+
+The function supports the following parameters:
+
+-   **z1**: first complex number strided array view.
+-   **sz1**: stride length for `z1`.
+-   **oz1**: starting index for `z1`.
+-   **z2**: second complex number strided array view.
+-   **sz2**: stride length for `z2`.
+-   **oz2**: starting index for `z2`.
+-   **out**: output array.
+-   **so**: stride length for `out`.
+-   **oo**: starting index for `out`.
+
 </section>
 
 <!-- /.usage -->

lib/node_modules/@stdlib/complex/float32/base/mul/benchmark/benchmark.assign.js

@@ -0,0 +1,70 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var uniform = require( '@stdlib/random/array/uniform' );
+var isnanf = require( '@stdlib/math/base/assert/is-nanf' );
+var Float32Array = require( '@stdlib/array/float32' );
+var pkg = require( './../package.json' ).name;
+var mul = require( './../lib' );
+
+
+// VARIABLES //
+
+var options = {
+	'dtype': 'float32'
+};
+
+
+// MAIN //
+
+bench( pkg+':assign', function benchmark( b ) {
+	var out;
+	var re;
+	var im;
+	var N;
+	var i;
+	var j;
+	var k;
+
+	N = 100;
+	re = uniform( N, -500.0, 500.0, options );
+	im = uniform( N, -500.0, 500.0, options );
+
+	out = new Float32Array( 2 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		j = i % N;
+		k = ( i+1 ) % N;
+		out = mul.assign( re[ j ], im[ j ], re[ k ], im[ k ], out, 1, 0 );
+		if ( typeof out !== 'object' ) {
+			b.fail( 'should return an object' );
+		}
+	}
+	b.toc();
+	if ( isnanf( out[ 0 ] ) || isnanf( out[ 1 ] ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/complex/float32/base/mul/benchmark/benchmark.strided.js

@@ -0,0 +1,68 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var uniform = require( '@stdlib/random/array/uniform' );
+var isnanf = require( '@stdlib/math/base/assert/is-nanf' );
+var Float32Array = require( '@stdlib/array/float32' );
+var pkg = require( './../package.json' ).name;
+var mul = require( './../lib' );
+
+
+// VARIABLES //
+
+var options = {
+	'dtype': 'float32'
+};
+
+
+// MAIN //
+
+bench( pkg+':strided', function benchmark( b ) {
+	var out;
+	var z1;
+	var z2;
+	var N;
+	var i;
+	var j;
+
+	N = 50;
+	z1 = uniform( N*2, -500.0, 500.0, options );
+	z2 = uniform( N*2, -500.0, 500.0, options );
+
+	out = new Float32Array( 2 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		j = ( i % N ) * 2;
+		out = mul.strided( z1, 1, j, z2, 1, j, out, 1, 0 );
+		if ( typeof out !== 'object' ) {
+			b.fail( 'should return an object' );
+		}
+	}
+	b.toc();
+	if ( isnanf( out[ 0 ] ) || isnanf( out[ 1 ] ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

lib/node_modules/@stdlib/complex/float32/base/mul/docs/repl.txt

@@ -28,6 +28,93 @@
     > var im = {{alias:@stdlib/complex/float32/imag}}( out )
     -1.0
 
+
+{{alias}}.assign( re1, im1, re2, im2, out, strideOut, offsetOut )
+    Multiplies two single-precision complex floating-point numbers and assigns
+    results to a provided output array.
+
+    Parameters
+    ----------
+    re1: number
+        Real component of the first complex number.
+
+    im1: number
+        Imaginary component of the first complex number.
+
+    re2: number
+        Real component of the second complex number.
+
+    im2: number
+        Imaginary component of the second complex number.
+
+    out: ArrayLikeObject
+        Output array.
+
+    strideOut: integer
+        Stride length.
+
+    offsetOut: integer
+        Starting index.
+
+    Returns
+    -------
+    out: ArrayLikeObject
+        Output array.
+
+    Examples
+    --------
+    > var out = new {{alias:@stdlib/array/float32}}( 2 );
+    > {{alias}}.assign( 5.0, 3.0, -2.0, 1.0, out, 1, 0 )
+    <Float32Array>[ -13.0, -1.0 ]
+
+
+{{alias}}.strided( z1, sz1, oz1, z2, sz2, oz2, out, so, oo )
+    Multiplies two single-precision complex floating-point numbers stored in
+    real-valued strided array views and assigns results to a provided strided
+    output array.
+
+    Parameters
+    ----------
+    z1: ArrayLikeObject
+        First complex number view.
+
+    sz1: integer
+        Stride length for `z1`.
+
+    oz1: integer
+        Starting index for `z1`.
+
+    z2: ArrayLikeObject
+        Second complex number view.
+
+    sz2: integer
+        Stride length for `z2`.
+
+    oz2: integer
+        Starting index for `z2`.
+
+    out: ArrayLikeObject
+        Output array.
+
+    so: integer
+        Stride length for `out`.
+
+    oo: integer
+        Starting index for `out`.
+
+    Returns
+    -------
+    out: ArrayLikeObject
+        Output array.
+
+    Examples
+    --------
+    > var z1 = new {{alias:@stdlib/array/float32}}( [ 5.0, 3.0 ] );
+    > var z2 = new {{alias:@stdlib/array/float32}}( [ -2.0, 1.0 ] );
+    > var out = new {{alias:@stdlib/array/float32}}( 2 );
+    > {{alias}}.strided( z1, 1, 0, z2, 1, 0, out, 1, 0 )
+    <Float32Array>[ -13.0, -1.0 ]
+
     See Also
     --------