Auto-generated commit

stdlib-js · Sep 20, 2024 · da954c1 · da954c1
1 parent 18c79a6
commit da954c1
Show file tree

Hide file tree

Showing 21 changed files with 2,342 additions and 182 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -608,6 +608,50 @@
 
 <!-- /.package -->
 
+<section class="package" id="blas-tools-unreleased">
+
+#### [@stdlib/blas/tools](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/tools)
+
+<details>
+
+<section class="features">
+
+##### Features
+
+-   [`339ba1b`](https://github.com/stdlib-js/stdlib/commit/339ba1bf405e085779be64f98aa197115483b857) - add `blas/tools` namespace
+
+</section>
+
+<!-- /.features -->
+
+</details>
+
+</section>
+
+<!-- /.package -->
+
+<section class="package" id="blas-tools-swap-factory-unreleased">
+
+#### [@stdlib/blas/tools/swap-factory](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/tools/swap-factory)
+
+<details>
+
+<section class="features">
+
+##### Features
+
+-   [`c070a88`](https://github.com/stdlib-js/stdlib/commit/c070a889f13926400f2422a6334d5252df1bacaf) - add `blas/tools/swap-factory`
+
+</section>
+
+<!-- /.features -->
+
+</details>
+
+</section>
+
+<!-- /.package -->
+
 </section>
 
 <!-- /.packages -->
@@ -647,6 +691,10 @@ A total of 6 people contributed to this release. Thank you to the following cont
 
 <details>
 
+-   [`339ba1b`](https://github.com/stdlib-js/stdlib/commit/339ba1bf405e085779be64f98aa197115483b857) - **feat:** add `blas/tools` namespace _(by Athan Reines)_
+-   [`dc22190`](https://github.com/stdlib-js/stdlib/commit/dc22190e473acb1a413af6d4482305c65f2420fd) - **refactor:** use `blas/tools/swap-factory` _(by Athan Reines)_
+-   [`2e2f268`](https://github.com/stdlib-js/stdlib/commit/2e2f2681aa86405fd2a5d7cad8c48fe32a2b8cb5) - **refactor:** use `blas/tools/swap-factory` _(by Athan Reines)_
+-   [`c070a88`](https://github.com/stdlib-js/stdlib/commit/c070a889f13926400f2422a6334d5252df1bacaf) - **feat:** add `blas/tools/swap-factory` _(by Athan Reines)_
 -   [`e454c91`](https://github.com/stdlib-js/stdlib/commit/e454c91ae2af928b61effcddadb31548758f8675) - **chore:** improve code style and conditionals _(by Philipp Burckhardt)_
 -   [`898b50d`](https://github.com/stdlib-js/stdlib/commit/898b50d8d705bdf6a55db8cf1858ea1e1d257c35) - **fix:** fix includes and types _(by Philipp Burckhardt)_
 -   [`7e366ae`](https://github.com/stdlib-js/stdlib/commit/7e366ae8bd41439be0e99e958d1c3fbb1b7dd0c2) - **chore:** update package.json descriptions _(by Philipp Burckhardt)_

diff --git a/dswap/lib/main.js b/dswap/lib/main.js
@@ -20,25 +20,17 @@
 
 // MODULES //
 
-var isFloat64ndarrayLike = require( '@stdlib/assert/is-float64ndarray-like' );
-var isNegativeInteger = require( '@stdlib/assert/is-negative-integer' ).isPrimitive;
-var isReadOnly = require( '@stdlib/ndarray/base/assert/is-read-only' );
-var hasEqualValues = require( '@stdlib/array/base/assert/has-equal-values-indexed' );
-var min = require( '@stdlib/math/base/special/fast/min' );
-var without = require( '@stdlib/array/base/without' );
-var ndarraylike2ndarray = require( '@stdlib/ndarray/base/ndarraylike2ndarray' );
-var normalizeIndex = require( '@stdlib/ndarray/base/normalize-index' );
-var nditerStacks = require( '@stdlib/ndarray/iter/stacks' );
-var numel = require( '@stdlib/ndarray/base/numel' );
 var base = require( './../../base/dswap' ).ndarray;
-var format = require( '@stdlib/string/format' );
+var factory = require( './../../tools/swap-factory' );
 
 
 // MAIN //
 
 /**
 * Interchanges two double-precision floating-point vectors.
 *
+* @name dswap
+* @type {Function}
 * @param {ndarrayLike} x - first input array
 * @param {ndarrayLike} y - second input array
 * @param {NegativeInteger} [dim] - dimension along which to interchange elements
@@ -66,86 +58,7 @@ var format = require( '@stdlib/string/format' );
 * var ybuf = y.data;
 * // returns <Float64Array>[ 4.0, 2.0, -3.0, 5.0, -1.0 ]
 */
-function dswap( x, y ) {
-	var dim;
-	var xsh;
-	var ysh;
-	var xit;
-	var yit;
-	var xc;
-	var yc;
-	var vx;
-	var vy;
-	var dm;
-	var S;
-	var N;
-	var i;
-	if ( !isFloat64ndarrayLike( x ) ) {
-		throw new TypeError( format( 'invalid argument. First argument must be an ndarray containing double-precision floating-point numbers. Value: `%s`.', x ) );
-	}
-	if ( !isFloat64ndarrayLike( y ) ) {
-		throw new TypeError( format( 'invalid argument. Second argument must be an ndarray containing double-precision floating-point numbers. Value: `%s`.', y ) );
-	}
-	if ( isReadOnly( x ) || isReadOnly( y ) ) {
-		throw new Error( 'invalid argument. Cannot write to read-only array.' );
-	}
-	// Convert the input arrays to "base" ndarrays:
-	xc = ndarraylike2ndarray( x );
-	yc = ndarraylike2ndarray( y );
-
-	// Resolve the input array shapes:
-	xsh = xc.shape;
-	ysh = yc.shape;
-
-	// Validate that we've been provided non-zero-dimensional arrays...
-	if ( xsh.length < 1 ) {
-		throw new TypeError( format( 'invalid argument. First argument must have at least one dimension.' ) );
-	}
-	if ( ysh.length < 1 ) {
-		throw new TypeError( format( 'invalid argument. Second argument must have at least one dimension.' ) );
-	}
-	// Validate that the arrays have the same shape...
-	if ( !hasEqualValues( xsh, ysh ) ) {
-		throw new Error( 'invalid arguments. The first and second arguments must have the same shape.' );
-	}
-	// Validate that the dimension argument is a negative integer...
-	if ( arguments.length > 2 ) {
-		dim = arguments[ 2 ];
-		if ( !isNegativeInteger( dim ) ) {
-			throw new TypeError( format( 'invalid argument. Third argument must be a negative integer. Value: `%s`.', dim ) );
-		}
-	} else {
-		dim = -1;
-	}
-	// Validate that a provided dimension index is within bounds...
-	dm = min( xsh.length, ysh.length ) - 1;
-	dim = normalizeIndex( dim, dm );
-	if ( dim === -1 ) {
-		throw new RangeError( format( 'invalid argument. Third argument must be a value on the interval: [%d,%d]. Value: `%d`.', -dm, -1, arguments[ 2 ] ) );
-	}
-	// Resolve the size of the interchange dimension:
-	S = xsh[ dim ];
-
-	// If we are only provided one-dimensional input arrays, we can skip iterating over stacks...
-	if ( xsh.length === 1 ) {
-		base( S, xc.data, xc.strides[0], xc.offset, yc.data, yc.strides[0], yc.offset ); // eslint-disable-line max-len
-		return y;
-	}
-	// Resolve the number of stacks:
-	N = numel( without( xsh, dim ) );
-
-	// Create iterators for iterating over stacks of vectors:
-	xit = nditerStacks( xc, [ dim ] );
-	yit = nditerStacks( yc, [ dim ] );
-
-	// Interchange each pair of vectors...
-	for ( i = 0; i < N; i++ ) {
-		vx = xit.next().value;
-		vy = yit.next().value;
-		base( S, vx.data, vx.strides[0], vx.offset, vy.data, vy.strides[0], vy.offset ); // eslint-disable-line max-len
-	}
-	return y;
-}
+var dswap = factory( base, 'float64' );
 
 
 // EXPORTS //

diff --git a/sswap/lib/main.js b/sswap/lib/main.js
@@ -20,25 +20,17 @@
 
 // MODULES //
 
-var isFloat32ndarrayLike = require( '@stdlib/assert/is-float32ndarray-like' );
-var isNegativeInteger = require( '@stdlib/assert/is-negative-integer' ).isPrimitive;
-var isReadOnly = require( '@stdlib/ndarray/base/assert/is-read-only' );
-var hasEqualValues = require( '@stdlib/array/base/assert/has-equal-values-indexed' );
-var min = require( '@stdlib/math/base/special/fast/min' );
-var without = require( '@stdlib/array/base/without' );
-var ndarraylike2ndarray = require( '@stdlib/ndarray/base/ndarraylike2ndarray' );
-var normalizeIndex = require( '@stdlib/ndarray/base/normalize-index' );
-var nditerStacks = require( '@stdlib/ndarray/iter/stacks' );
-var numel = require( '@stdlib/ndarray/base/numel' );
 var base = require( './../../base/sswap' ).ndarray;
-var format = require( '@stdlib/string/format' );
+var factory = require( './../../tools/swap-factory' );
 
 
 // MAIN //
 
 /**
 * Interchanges two single-precision floating-point vectors.
 *
+* @name sswap
+* @type {Function}
 * @param {ndarrayLike} x - first input array
 * @param {ndarrayLike} y - second input array
 * @param {NegativeInteger} [dim=-1] - dimension along which to interchange elements
@@ -66,86 +58,7 @@ var format = require( '@stdlib/string/format' );
 * var ybuf = y.data;
 * // returns <Float32Array>[ 4.0, 2.0, -3.0, 5.0, -1.0 ]
 */
-function sswap( x, y ) {
-	var dim;
-	var xsh;
-	var ysh;
-	var xit;
-	var yit;
-	var xc;
-	var yc;
-	var vx;
-	var vy;
-	var dm;
-	var S;
-	var N;
-	var i;
-	if ( !isFloat32ndarrayLike( x ) ) {
-		throw new TypeError( format( 'invalid argument. First argument must be an ndarray containing single-precision floating-point numbers. Value: `%s`.', x ) );
-	}
-	if ( !isFloat32ndarrayLike( y ) ) {
-		throw new TypeError( format( 'invalid argument. Second argument must be an ndarray containing single-precision floating-point numbers. Value: `%s`.', y ) );
-	}
-	if ( isReadOnly( x ) || isReadOnly( y ) ) {
-		throw new Error( 'invalid argument. Cannot write to read-only array.' );
-	}
-	// Convert the input arrays to "base" ndarrays:
-	xc = ndarraylike2ndarray( x );
-	yc = ndarraylike2ndarray( y );
-
-	// Resolve the input array shapes:
-	xsh = xc.shape;
-	ysh = yc.shape;
-
-	// Validate that we've been provided non-zero-dimensional arrays...
-	if ( xsh.length < 1 ) {
-		throw new TypeError( format( 'invalid argument. First argument must have at least one dimension.' ) );
-	}
-	if ( ysh.length < 1 ) {
-		throw new TypeError( format( 'invalid argument. Second argument must have at least one dimension.' ) );
-	}
-	// Validate that the arrays have the same shape...
-	if ( !hasEqualValues( xsh, ysh ) ) {
-		throw new Error( 'invalid arguments. The first and second arguments must have the same shape.' );
-	}
-	// Validate that the dimension argument is a negative integer...
-	if ( arguments.length > 2 ) {
-		dim = arguments[ 2 ];
-		if ( !isNegativeInteger( dim ) ) {
-			throw new TypeError( format( 'invalid argument. Third argument must be a negative integer. Value: `%s`.', dim ) );
-		}
-	} else {
-		dim = -1;
-	}
-	// Validate that a provided dimension index is within bounds...
-	dm = min( xsh.length, ysh.length ) - 1;
-	dim = normalizeIndex( dim, dm );
-	if ( dim === -1 ) {
-		throw new RangeError( format( 'invalid argument. Third argument must be a value on the interval: [%d,%d]. Value: `%d`.', -dm, -1, arguments[ 2 ] ) );
-	}
-	// Resolve the size of the interchange dimension:
-	S = xsh[ dim ];
-
-	// If we are only provided one-dimensional input arrays, we can skip iterating over stacks...
-	if ( xsh.length === 1 ) {
-		base( S, xc.data, xc.strides[0], xc.offset, yc.data, yc.strides[0], yc.offset ); // eslint-disable-line max-len
-		return y;
-	}
-	// Resolve the number of stacks:
-	N = numel( without( xsh, dim ) );
-
-	// Create iterators for iterating over stacks of vectors:
-	xit = nditerStacks( xc, [ dim ] );
-	yit = nditerStacks( yc, [ dim ] );
-
-	// Interchange each pair of vectors...
-	for ( i = 0; i < N; i++ ) {
-		vx = xit.next().value;
-		vy = yit.next().value;
-		base( S, vx.data, vx.strides[0], vx.offset, vy.data, vy.strides[0], vy.offset ); // eslint-disable-line max-len
-	}
-	return y;
-}
+var sswap = factory( base, 'float32' );
 
 
 // EXPORTS //

diff --git a/tools/README.md b/tools/README.md
@@ -0,0 +1,85 @@
+<!--
+
+@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.
+
+-->
+
+# Tools
+
+> Tools for basic linear algebra subprograms (BLAS).
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var ns = require( '@stdlib/blas/tools' );
+```
+
+#### ns
+
+Namespace for basic linear algebra subprograms (BLAS) tools.
+
+```javascript
+var o = ns;
+// returns {...}
+```
+
+The namespace contains the following:
+
+<!-- <toc pattern="*"> -->
+
+<!-- </toc> -->
+
+</section>
+
+<!-- /.usage -->
+
+<section class="examples">
+
+## Examples
+
+<!-- TODO: better examples -->
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var objectKeys = require( '@stdlib/utils/keys' );
+var ns = require( '@stdlib/blas/tools' );
+
+console.log( objectKeys( ns ) );
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+</section>
+
+<!-- /.links -->