fix: refactor sapx to use arrays API pattern

Author: Amansingh0807

lib/node_modules/@stdlib/blas/ext/base/ndarray/sapx/README.md

@@ -20,7 +20,7 @@ limitations under the License.
 
 # sapx
 
-> Add a scalar constant to each element in a single-precision floating-point ndarray.
+> Add a scalar constant to each element in a one-dimensional single-precision floating-point ndarray.
 
 <section class="usage">
 
@@ -30,56 +30,58 @@ limitations under the License.
 var sapx = require( '@stdlib/blas/ext/base/ndarray/sapx' );
 ```
 
-#### sapx( x, alpha )
+#### sapx( arrays )
 
-Adds a scalar constant to each element in a single-precision floating-point ndarray.
+Adds a scalar constant to each element in a one-dimensional single-precision floating-point ndarray.
 
 ```javascript
 var Float32Array = require( '@stdlib/array/float32' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 
 var xbuf = new Float32Array( [ 1.0, 2.0, 3.0, 4.0 ] );
 var x = new ndarray( 'float32', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
 
-var out = sapx( x, 5.0 );
+var alpha = scalar2ndarray( 5.0, {
+    'dtype': 'float32'
+});
+
+var out = sapx( [ x, alpha ] );
 // returns <ndarray>[ 6.0, 7.0, 8.0, 9.0 ]
+
+var bool = ( out === x );
+// returns true
+
+var arr = ndarray2array( out );
+// returns [ 6.0, 7.0, 8.0, 9.0 ]
 ```
 
 The function has the following parameters:
 
--   **x**: input ndarray.
--   **alpha**: scalar constant.
-
-Note that indexing is relative to the first index. To introduce an offset, use [`ndarray`][@stdlib/ndarray/ctor] view creation.
+-   **arrays**: array-like object containing a one-dimensional input ndarray and a zero-dimensional ndarray containing a scalar constant.
 
 ```javascript
 var Float32Array = require( '@stdlib/array/float32' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 
 // Initial array:
 var xbuf = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] );
 
 // Create an ndarray view:
 var x = new ndarray( 'float32', xbuf, [ 3 ], [ 1 ], 2, 'row-major' );
-
-var out = sapx( x, 5.0 );
+var alpha = scalar2ndarray( 5.0, {
+    'dtype': 'float32'
+});
+var out = sapx( [ x, alpha ] );
 // returns <ndarray>[ 8.0, 9.0, 10.0 ]
 ```
 
 </section>
 
 <!-- /.usage -->
 
-<section class="notes">
-
-## Notes
-
--   The function **mutates** the input ndarray.
-
-</section>
-
-<!-- /.notes -->
-
 <section class="examples">
 
 ## Examples
@@ -89,18 +91,22 @@ var out = sapx( x, 5.0 );
 ```javascript
 var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var sapx = require( '@stdlib/blas/ext/base/ndarray/sapx' );
 
 var xbuf = discreteUniform( 10, 0, 100, {
     'dtype': 'float32'
 });
 var x = new ndarray( 'float32', xbuf, [ 10 ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( x ) );
 
-console.log( x.data );
-
-sapx( x, 5.0 );
+var alpha = scalar2ndarray( 5.0, {
+    'dtype': 'float32'
+});
 
-console.log( x.data );
+sapx( [ x, alpha ] );
+console.log( ndarray2array( x ) );
 ```
 
 </section>
@@ -119,8 +125,6 @@ console.log( x.data );
 
 <section class="links">
 
-[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray-ctor
-
 </section>
 
 <!-- /.links -->

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

@@ -25,10 +25,18 @@ var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var isnanf = require( '@stdlib/math/base/assert/is-nanf' );
 var pow = require( '@stdlib/math/base/special/pow' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 var pkg = require( './../package.json' ).name;
 var sapx = require( './../lib' );
 
 
+// VARIABLES //
+
+var options = {
+	'dtype': 'float32'
+};
+
+
 // FUNCTIONS //
 
 /**
@@ -39,11 +47,13 @@ var sapx = require( './../lib' );
 * @returns {Function} benchmark function
 */
 function createBenchmark( len ) {
+	var alpha;
+	var xbuf;
 	var x;
 
-	x = new ndarray( 'float32', discreteUniform( len, -100, 100, {
-		'dtype': 'float32'
-	}), [ len ], [ 1 ], 0, 'row-major' );
+	xbuf = discreteUniform( len, -100, 100, options );
+	x = new ndarray( options.dtype, xbuf, [ len ], [ 1 ], 0, 'row-major' );
+	alpha = scalar2ndarray( 5.0, options );
 
 	return benchmark;
 
@@ -59,7 +69,7 @@ function createBenchmark( len ) {
 
 		b.tic();
 		for ( i = 0; i < b.iterations; i++ ) {
-			z = sapx( x, 5.0 );
+			z = sapx( [ x, alpha ] );
 			if ( isnanf( z.data[ i % len ] ) ) {
 				b.fail( 'should not return NaN' );
 			}

lib/node_modules/@stdlib/blas/ext/base/ndarray/sapx/docs/repl.txt

@@ -1,26 +1,28 @@
-{{alias}}( x, alpha )
-    Adds a scalar constant to each element in a single-precision floating-
-    point ndarray.
+
+{{alias}}( arrays )
+    Adds a scalar constant to each element in a one-dimensional single-
+    precision floating-point ndarray.
 
     Parameters
     ----------
-    x: float32ndarray
-        Input ndarray.
-
-    alpha: number
-        Scalar constant.
+    arrays: ArrayLikeObject<ndarray>
+        Array-like object containing a one-dimensional input ndarray and a
+        zero-dimensional ndarray containing a scalar constant.
 
     Returns
     -------
-    out: float32ndarray
+    out: ndarray
         Input ndarray.
 
     Examples
     --------
     > var xbuf = new {{alias:@stdlib/array/float32}}( [ 1.0, 2.0, 3.0, 4.0 ] );
     > var x = {{alias:@stdlib/ndarray/ctor}}( 'float32', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
-    > {{alias}}( x, 5.0 )
+    > var alpha = {{alias:@stdlib/ndarray/from-scalar}}( 5.0, { 'dtype': 'float32' } );
+    > {{alias}}( [ x, alpha ] )
     <ndarray>[ 6.0, 7.0, 8.0, 9.0 ]
+    > var data = x.data
+    <Float32Array>[ 6.0, 7.0, 8.0, 9.0 ]
 
     See Also
     --------

lib/node_modules/@stdlib/blas/ext/base/ndarray/sapx/docs/types/index.d.ts

@@ -23,23 +23,31 @@
 import { float32ndarray } from '@stdlib/types/ndarray';
 
 /**
-* Adds a scalar constant to each element in a single-precision floating-point ndarray.
+* Adds a scalar constant to each element in a one-dimensional single-precision floating-point ndarray.
 *
-* @param x - input ndarray
-* @param alpha - scalar constant
+* @param arrays - array-like object containing a one-dimensional input ndarray and a zero-dimensional ndarray containing a scalar constant
 * @returns input ndarray
 *
 * @example
 * var Float32Array = require( '@stdlib/array/float32' );
 * var ndarray = require( '@stdlib/ndarray/ctor' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+* var ndarray2array = require( '@stdlib/ndarray/to-array' );
 *
 * var xbuf = new Float32Array( [ 1.0, 2.0, 3.0, 4.0 ] );
 * var x = new ndarray( 'float32', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
 *
-* var out = sapx( x, 5.0 );
-* // returns <ndarray>[ 6.0, 7.0, 8.0, 9.0 ]
+* var alpha = scalar2ndarray( 5.0, {
+*     'dtype': 'float32'
+* });
+*
+* var out = sapx( [ x, alpha ] );
+* // returns <ndarray>
+*
+* var arr = ndarray2array( out );
+* // returns [ 6.0, 7.0, 8.0, 9.0 ]
 */
-declare function sapx( x: float32ndarray, alpha: number ): float32ndarray;
+declare function sapx( arrays: [ float32ndarray, float32ndarray ] ): float32ndarray;
 
 
 // EXPORTS //

lib/node_modules/@stdlib/blas/ext/base/ndarray/sapx/docs/types/test.ts

@@ -16,47 +16,38 @@
 * limitations under the License.
 */
 
+import zeros = require( '@stdlib/ndarray/base/zeros' );
+import scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
 import sapx = require( './index' );
 
 
 // TESTS //
 
 // The function returns an ndarray...
 {
-	const x: any = null;
-	sapx( x, 5.0 ); // $ExpectType float32ndarray
+	const x = zeros( 'float32', [ 3 ], 'row-major' );
+	const alpha = scalar2ndarray( 5.0, { 'dtype': 'float32' } );
+	sapx( [ x, alpha ] ); // $ExpectType float32ndarray
 }
 
-// The compiler throws an error if the function is provided a first argument which is not an ndarray...
+// The compiler throws an error if the function is provided a first argument which is not an array-like object containing ndarrays...
 {
-	sapx( 123, 5.0 ); // $ExpectError
-	sapx( true, 5.0 ); // $ExpectError
-	sapx( false, 5.0 ); // $ExpectError
-	sapx( null, 5.0 ); // $ExpectError
-	sapx( undefined, 5.0 ); // $ExpectError
-	sapx( '5', 5.0 ); // $ExpectError
-	sapx( [ '1', '2' ], 5.0 ); // $ExpectError
-	sapx( {}, 5.0 ); // $ExpectError
-	sapx( ( x: number ): number => x, 5.0 ); // $ExpectError
-}
-
-// The compiler throws an error if the function is provided a second argument which is not a number...
-{
-	const x: any = null;
-	sapx( x, '5' ); // $ExpectError
-	sapx( x, true ); // $ExpectError
-	sapx( x, false ); // $ExpectError
-	sapx( x, null ); // $ExpectError
-	sapx( x, undefined ); // $ExpectError
-	sapx( x, [ '1' ] ); // $ExpectError
-	sapx( x, {} ); // $ExpectError
-	sapx( x, ( x: number ): number => x ); // $ExpectError
+	const alpha = scalar2ndarray( 5.0, { 'dtype': 'float32' } );
+	sapx( 123 ); // $ExpectError
+	sapx( true ); // $ExpectError
+	sapx( false ); // $ExpectError
+	sapx( null ); // $ExpectError
+	sapx( undefined ); // $ExpectError
+	sapx( '5' ); // $ExpectError
+	sapx( [ '1', '2' ] ); // $ExpectError
+	sapx( {} ); // $ExpectError
+	sapx( ( x: number ): number => x ); // $ExpectError
 }
 
 // The compiler throws an error if the function is provided an unsupported number of arguments...
 {
-	const x: any = null;
+	const x = zeros( 'float32', [ 3 ], 'row-major' );
+	const alpha = scalar2ndarray( 5.0, { 'dtype': 'float32' } );
 	sapx(); // $ExpectError
-	sapx( x ); // $ExpectError
-	sapx( x, 5.0, 10 ); // $ExpectError
+	sapx( [ x, alpha ], 10 ); // $ExpectError
 }

lib/node_modules/@stdlib/blas/ext/base/ndarray/sapx/examples/index.js

@@ -18,17 +18,26 @@
 
 'use strict';
 
+// MODULES //
+
 var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
 var ndarray = require( '@stdlib/ndarray/ctor' );
+var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
 var sapx = require( './../lib' );
 
+
+// MAIN //
+
 var xbuf = discreteUniform( 10, 0, 100, {
 	'dtype': 'float32'
 });
 var x = new ndarray( 'float32', xbuf, [ 10 ], [ 1 ], 0, 'row-major' );
+console.log( ndarray2array( x ) );
 
-console.log( x.data );
-
-sapx( x, 5.0 );
+var alpha = scalar2ndarray( 5.0, {
+	'dtype': 'float32'
+});
 
-console.log( x.data );
+sapx( [ x, alpha ] );
+console.log( ndarray2array( x ) );

lib/node_modules/@stdlib/blas/ext/base/ndarray/sapx/lib/index.js

@@ -19,20 +19,29 @@
 'use strict';
 
 /**
-* Add a scalar constant to each element in a single-precision floating-point ndarray.
+* Add a scalar constant to each element in a one-dimensional single-precision floating-point ndarray.
 *
 * @module @stdlib/blas/ext/base/ndarray/sapx
 *
 * @example
 * var Float32Array = require( '@stdlib/array/float32' );
 * var ndarray = require( '@stdlib/ndarray/ctor' );
+* var scalar2ndarray = require( '@stdlib/ndarray/from-scalar' );
+* var ndarray2array = require( '@stdlib/ndarray/to-array' );
 * var sapx = require( '@stdlib/blas/ext/base/ndarray/sapx' );
 *
 * var xbuf = new Float32Array( [ 1.0, 2.0, 3.0, 4.0 ] );
 * var x = new ndarray( 'float32', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
 *
-* var out = sapx( x, 5.0 );
-* // returns <ndarray>[ 6.0, 7.0, 8.0, 9.0 ]
+* var alpha = scalar2ndarray( 5.0, {
+*     'dtype': 'float32'
+* });
+*
+* var out = sapx( [ x, alpha ] );
+* // returns <ndarray>
+*
+* var arr = ndarray2array( out );
+* // returns [ 6.0, 7.0, 8.0, 9.0 ]
 */
 
 // MODULES //