@stdlib/strided-base-binary-addon-dispatch 0.0.1

package/lib/index.js

@@ -0,0 +1,53 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2021 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';
+
+/**
+* Dispatch to a native add-on applying a binary function to two input strided arrays.
+*
+* @module @stdlib/strided-base-binary-addon-dispatch
+*
+* @example
+* var dispatch = require( '@stdlib/strided-base-binary-addon-dispatch' );
+*
+* function addon( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ ) {
+*     // Call into native add-on...
+* }
+*
+* function fallback( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ ) {
+*     // Fallback JavaScript implementation...
+* }
+*
+* // Create a dispatch function:
+* var f = dispatch( addon, fallback );
+*
+* // ...
+*
+* // Invoke the dispatch function with strided array arguments:
+* f( 2, 'generic', [ 1, 2 ], 1, 'generic', [ 3, 4 ], 1, 'generic', [ 0, 0 ], 1 );
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/main.js

@@ -0,0 +1,35 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2020 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 setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var binary = require( './binary.js' );
+var ndarray = require( './ndarray.js' );
+
+
+// MAIN //
+
+setReadOnly( binary, 'ndarray', ndarray );
+
+
+// EXPORTS //
+
+module.exports = binary;

package/lib/ndarray.js

@@ -0,0 +1,228 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2021 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.
+*/
+
+/* eslint-disable max-len */
+
+'use strict';
+
+// MODULES //
+
+var isFunction = require( '@stdlib/assert-is-function' );
+var isTypedArrayLike = require( '@stdlib/assert-is-typed-array-like' );
+var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;
+var resolve = require( '@stdlib/strided-base-dtype-resolve-enum' );
+var reinterpretComplex64 = require( '@stdlib/strided-base-reinterpret-complex64' );
+var reinterpretComplex128 = require( '@stdlib/strided-base-reinterpret-complex128' );
+var offsetView = require( '@stdlib/strided-base-offset-view' );
+var minViewBufferIndex = require( '@stdlib/strided-base-min-view-buffer-index' );
+
+
+// VARIABLES //
+
+var COMPLEX64 = resolve( 'complex64' );
+var COMPLEX128 = resolve( 'complex128' );
+
+
+// MAIN //
+
+/**
+* Returns a function which dispatches to a native add-on applying a binary function to two input arrays using alternative indexing semantics.
+*
+* ## Notes
+*
+* -   The returned function has the following signature:
+*
+*     ```text
+*     f( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY, dtypeZ, z, strideZ, offsetZ )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type.
+*     -   **x**: input array.
+*     -   **strideX**: `x` stride length.
+*     -   **offsetX**: starting `x` index.
+*     -   **dtypeY**: `y` data type.
+*     -   **y**: input array.
+*     -   **strideY**: `y` stride length.
+*     -   **offsetY**: starting `y` index.
+*     -   **dtypeZ**: `z` data type.
+*     -   **z**: output array.
+*     -   **strideZ**: `z` stride length.
+*     -   **offsetZ**: starting `z` index.
+*
+* -   The add-on function should have the following signature:
+*
+*     ```text
+*     f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type (enumeration constant).
+*     -   **x**: input array.
+*     -   **strideX**: `x` stride length.
+*     -   **dtypeY**: `y` data type (enumeration constant).
+*     -   **y**: input array.
+*     -   **strideY**: `y` stride length.
+*     -   **dtypeZ**: `z` data type (enumeration constant).
+*     -   **z**: output array.
+*     -   **strideZ**: `z` stride length.
+*
+* -   The fallback function should have the following signature:
+*
+*     ```text
+*     f( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY, dtypeZ, z, strideZ, offsetZ )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type.
+*     -   **x**: input array.
+*     -   **strideX**: `x` stride length.
+*     -   **offsetX**: starting `x` index.
+*     -   **dtypeY**: `y` data type.
+*     -   **y**: input array.
+*     -   **strideY**: `y` stride length.
+*     -   **offsetY**: starting `y` index.
+*     -   **dtypeZ**: `z` data type.
+*     -   **z**: output array.
+*     -   **strideZ**: `z` stride length.
+*     -   **offsetZ**: starting `z` index.
+*
+* @param {Function} addon - add-on interface
+* @param {Function} fallback - fallback function
+* @throws {TypeError} first argument must be a function
+* @throws {TypeError} second argument must be a function
+* @returns {Function} dispatch function
+*
+* @example
+* function addon( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ ) {
+*     // Call into native add-on...
+* }
+*
+* function fallback( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY, dtypeZ, z, strideZ, offsetZ ) {
+*     // Fallback JavaScript implementation...
+* }
+*
+* // Create a dispatch function:
+* var f = dispatch( addon, fallback );
+*
+* // ...
+*
+* // Invoke the dispatch function with strided array arguments:
+* f( 2, 'generic', [ 1, 2 ], 1, 0, 'generic', [ 3, 4 ], 1, 0, 'generic', [ 0, 0 ], 1, 0 );
+*/
+function dispatch( addon, fallback ) {
+	if ( !isFunction( addon ) ) {
+		throw new TypeError( 'invalid argument. First argument must be a function. Value: `' + addon + '`.' );
+	}
+	if ( !isFunction( fallback ) ) {
+		throw new TypeError( 'invalid argument. Second argument must be a function. Value: `' + fallback + '`.' );
+	}
+	return dispatcher;
+
+	/**
+	* Dispatches to a native add-on.
+	*
+	* @private
+	* @param {integer} N - number of indexed elements
+	* @param {*} dtypeX - `x` data type
+	* @param {Collection} x - input array
+	* @param {integer} strideX - `x` stride length
+	* @param {NonNegativeInteger} offsetX - starting `x` index
+	* @param {*} dtypeY - `y` data type
+	* @param {Collection} y - input array
+	* @param {integer} strideY - `y` stride length
+	* @param {NonNegativeInteger} offsetY - starting `y` index
+	* @param {*} dtypeZ - `z` data type
+	* @param {Collection} z - destination array
+	* @param {integer} strideZ - `z` stride length
+	* @param {NonNegativeInteger} offsetZ - starting `z` index
+	* @throws {TypeError} fifth argument must be a nonnegative integer
+	* @throws {TypeError} ninth argument must be a nonnegative integer
+	* @throws {TypeError} thirteenth argument must be a nonnegative integer
+	* @throws {TypeError} unable to resolve a strided array function supporting the provided array argument data types
+	* @returns {Collection} `z`
+	*/
+	function dispatcher( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY, dtypeZ, z, strideZ, offsetZ ) { // eslint-disable-line max-params
+		var viewX;
+		var viewY;
+		var viewZ;
+
+		// WARNING: we assume that, if we're provided something resembling a typed array, we're provided a typed array; however, this can lead to potential unintended errors as the native add-on may not work with non-typed array objects (e.g., generic arrays)...
+		if (
+			!isTypedArrayLike( x ) ||
+			!isTypedArrayLike( y ) ||
+			!isTypedArrayLike( z )
+		) {
+			fallback( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY, dtypeZ, z, strideZ, offsetZ );
+			return z;
+		}
+		dtypeX = resolve( dtypeX );
+		dtypeY = resolve( dtypeY );
+		dtypeZ = resolve( dtypeZ );
+		if ( dtypeX === null || dtypeY === null || dtypeZ === null ) {
+			throw new TypeError( 'invalid arguments. Unable to resolve a strided array function supporting the provided array argument data types.' );
+		}
+		if ( !isNonNegativeInteger( offsetX ) ) {
+			throw new TypeError( 'invalid argument. First input array offset argument must be a nonnegative integer.' );
+		}
+		if ( !isNonNegativeInteger( offsetY ) ) {
+			throw new TypeError( 'invalid argument. Second input array offset argument must be a nonnegative integer.' );
+		}
+		if ( !isNonNegativeInteger( offsetZ ) ) {
+			throw new TypeError( 'invalid argument. Output array offset argument must be a nonnegative integer.' );
+		}
+		offsetX = minViewBufferIndex( N, strideX, offsetX );
+		offsetY = minViewBufferIndex( N, strideY, offsetY );
+		offsetZ = minViewBufferIndex( N, strideZ, offsetZ );
+		if ( dtypeX === COMPLEX64 ) {
+			viewX = reinterpretComplex64( x, offsetX );
+		} else if ( dtypeX === COMPLEX128 ) {
+			viewX = reinterpretComplex128( x, offsetX );
+		} else {
+			viewX = offsetView( x, offsetX );
+		}
+		if ( dtypeY === COMPLEX64 ) {
+			viewY = reinterpretComplex64( y, offsetY );
+		} else if ( dtypeY === COMPLEX128 ) {
+			viewY = reinterpretComplex128( y, offsetY );
+		} else {
+			viewY = offsetView( y, offsetY );
+		}
+		if ( dtypeZ === COMPLEX64 ) {
+			viewZ = reinterpretComplex64( z, offsetZ );
+		} else if ( dtypeZ === COMPLEX128 ) {
+			viewZ = reinterpretComplex128( z, offsetZ );
+		} else {
+			viewZ = offsetView( z, offsetZ );
+		}
+
+		addon( N, dtypeX, viewX, strideX, dtypeY, viewY, strideY, dtypeZ, viewZ, strideZ );
+		return z;
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = dispatch;

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@stdlib/strided-base-binary-addon-dispatch",
+  "version": "0.0.1",
+  "description": "Dispatch to a native add-on applying a binary function to two input strided arrays.",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "The Stdlib Authors",
+    "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+  },
+  "contributors": [
+    {
+      "name": "The Stdlib Authors",
+      "url": "https://github.com/stdlib-js/stdlib/graphs/contributors"
+    }
+  ],
+  "main": "./lib",
+  "directories": {
+    "benchmark": "./benchmark",
+    "doc": "./docs",
+    "example": "./examples",
+    "lib": "./lib",
+    "test": "./test"
+  },
+  "types": "./docs/types",
+  "scripts": {
+    "test": "make test",
+    "test-cov": "make test-cov",
+    "examples": "make examples",
+    "benchmark": "make benchmark"
+  },
+  "homepage": "https://stdlib.io",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/stdlib-js/strided-base-binary-addon-dispatch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stdlib-js/stdlib/issues"
+  },
+  "dependencies": {
+    "@stdlib/assert-is-function": "^0.0.x",
+    "@stdlib/assert-is-nonnegative-integer": "^0.0.x",
+    "@stdlib/assert-is-typed-array-like": "^0.0.x",
+    "@stdlib/strided-base-dtype-resolve-enum": "^0.0.x",
+    "@stdlib/strided-base-min-view-buffer-index": "^0.0.x",
+    "@stdlib/strided-base-offset-view": "^0.0.x",
+    "@stdlib/strided-base-reinterpret-complex128": "^0.0.x",
+    "@stdlib/strided-base-reinterpret-complex64": "^0.0.x",
+    "@stdlib/types": "^0.0.x",
+    "@stdlib/utils-define-nonenumerable-read-only-property": "^0.0.x"
+  },
+  "devDependencies": {
+    "@stdlib/array-complex128": "^0.0.x",
+    "@stdlib/array-complex64": "^0.0.x",
+    "@stdlib/array-float64": "^0.0.x",
+    "@stdlib/assert-has-own-property": "^0.0.x",
+    "@stdlib/assert-is-float32array": "^0.0.x",
+    "@stdlib/assert-is-float64array": "^0.0.x",
+    "@stdlib/bench": "^0.0.x",
+    "@stdlib/utils-noop": "^0.0.x",
+    "tape": "git+https://github.com/kgryte/tape.git#fix/globby",
+    "istanbul": "^0.4.1",
+    "tap-spec": "5.x.x"
+  },
+  "engines": {
+    "node": ">=0.10.0",
+    "npm": ">2.7.0"
+  },
+  "os": [
+    "aix",
+    "darwin",
+    "freebsd",
+    "linux",
+    "macos",
+    "openbsd",
+    "sunos",
+    "win32",
+    "windows"
+  ],
+  "keywords": [
+    "stdlib",
+    "base",
+    "strided",
+    "array",
+    "dispatch",
+    "addon",
+    "add-on",
+    "native",
+    "binary"
+  ],
+  "__stdlib__": {},
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/athan"
+  }
+}