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

package/lib/ndarray.js

@@ -0,0 +1,164 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2022 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 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' );
+var format = require( '@stdlib/string-format' );
+
+
+// VARIABLES //
+
+var COMPLEX64 = resolve( 'complex64' );
+var COMPLEX128 = resolve( 'complex128' );
+
+
+// MAIN //
+
+/**
+* Returns a function which dispatches to a native add-on applying a nullary function using alternative indexing semantics.
+*
+* ## Notes
+*
+* -   The returned function has the following signature:
+*
+*     ```text
+*     f( N, dtypeX, x, strideX, offsetX )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type.
+*     -   **x**: output array.
+*     -   **strideX**: `x` stride length.
+*     -   **offsetX**: starting `x` index.
+*
+* -   The add-on function should have the following signature:
+*
+*     ```text
+*     f( N, dtypeX, x, strideX )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type (enumeration constant).
+*     -   **x**: output array.
+*     -   **strideX**: `x` stride length.
+*
+* -   The fallback function should have the following signature:
+*
+*     ```text
+*     f( N, dtypeX, x, strideX, offsetX )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type.
+*     -   **x**: output array.
+*     -   **strideX**: `x` stride length.
+*     -   **offsetX**: starting `x` 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 ) {
+*     // Call into native add-on...
+* }
+*
+* function fallback( N, dtypeX, x, strideX, offsetX ) {
+*     // 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 );
+*/
+function dispatch( addon, fallback ) {
+	if ( !isFunction( addon ) ) {
+		throw new TypeError( format( 'invalid argument. First argument must be a function. Value: `%s`.', addon ) );
+	}
+	if ( !isFunction( fallback ) ) {
+		throw new TypeError( format( 'invalid argument. Second argument must be a function. Value: `%s`.', 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 - output array
+	* @param {integer} strideX - `x` stride length
+	* @param {NonNegativeInteger} offsetX - starting `x` index
+	* @throws {TypeError} fifth argument must be a nonnegative integer
+	* @throws {TypeError} unable to resolve a strided array function supporting the provided array argument data types
+	* @returns {Collection} `x`
+	*/
+	function dispatcher( N, dtypeX, x, strideX, offsetX ) {
+		var viewX;
+
+		// 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 ) ) {
+			fallback( N, dtypeX, x, strideX, offsetX );
+			return x;
+		}
+		dtypeX = resolve( dtypeX );
+		if ( dtypeX === 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( format( 'invalid argument. Output array offset must be a nonnegative integer. Value: `%s`.', offsetX ) );
+		}
+		offsetX = minViewBufferIndex( N, strideX, offsetX );
+		if ( dtypeX === COMPLEX64 ) {
+			viewX = reinterpretComplex64( x, offsetX );
+		} else if ( dtypeX === COMPLEX128 ) {
+			viewX = reinterpretComplex128( x, offsetX );
+		} else {
+			viewX = offsetView( x, offsetX );
+		}
+		addon( N, dtypeX, viewX, strideX );
+		return x;
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = dispatch;

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@stdlib/strided-base-nullary-addon-dispatch",
+  "version": "0.0.1",
+  "description": "Dispatch to a native add-on applying a nullary function.",
+  "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-nullary-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/string-format": "^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-min": "git+https://github.com/Planeshifter/tap-min.git"
+  },
+  "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"
+  ],
+  "__stdlib__": {},
+  "funding": {
+    "type": "patreon",
+    "url": "https://www.patreon.com/athan"
+  }
+}