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

package/docs/types/index.d.ts

@@ -0,0 +1,197 @@
+/*
+* @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.
+*/
+
+// TypeScript Version: 2.0
+
+/// <reference types="@stdlib/types"/>
+
+import { Collection } from '@stdlib/types/object';
+
+/**
+* Add-on function.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type (enumeration constant)
+* @param x - output array
+* @param strideX - `x` stride length
+*
+* @example
+* function addon( N, dtypeX, x, strideX ) {
+*     // Call into native add-on...
+* }
+*/
+type AddonFcn = ( N: number, dtypeX: number, x: Collection, strideX: number ) => any; // tslint:disable-line:max-line-length
+
+/**
+* Fallback function.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type
+* @param x - output array
+* @param strideX - `x` stride length
+*
+* @example
+* function fallback( N, dtypeX, x, strideX ) {
+*     // Fallback JavaScript implementation...
+* }
+*/
+type FallbackFcn = ( N: number, dtypeX: any, x: Collection, strideX: number ) => any; // tslint:disable-line:max-line-length
+
+/**
+* Fallback function supporting alternative indexing semantics.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type
+* @param x - output array
+* @param strideX - `x` stride length
+* @param offsetX - starting `x` index
+*
+* @example
+* function fallback( N, dtypeX, x, strideX, offsetX ) {
+*     // Fallback JavaScript implementation...
+* }
+*/
+type FallbackFcnWithOffsets = ( N: number, dtypeX: any, x: Collection, strideX: number, offsetX: number ) => any; // tslint:disable-line:max-line-length
+
+/**
+* Dispatches to a native add-on.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type
+* @param x - output array
+* @param strideX - `x` stride length
+* @returns `x`
+*/
+type Dispatcher = ( N: number, dtypeX: any, x: Collection, strideX: number ) => Collection; // tslint:disable-line:max-line-length
+
+/**
+* Dispatches to a native add-on.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type
+* @param x - output array
+* @param strideX - `x` stride length
+* @param offsetX - starting `x` index
+* @returns `x`
+*/
+type DispatcherWithOffsets = ( N: number, dtypeX: any, x: Collection, strideX: number, offsetX: number ) => Collection; // tslint:disable-line:max-line-length
+
+/**
+* Interface for creating a native add-on dispatcher.
+*/
+interface Dispatch {
+	/**
+	* Returns a function which dispatches to a native add-on applying a nullary function.
+	*
+	* @param addon - add-on function
+	* @param fallback - fallback function
+	* @returns dispatch function
+	*
+	* @example
+	* function addon( N, dtypeX, x, strideX ) {
+	*     // Call into native add-on...
+	* }
+	*
+	* function fallback( N, dtypeX, x, strideX ) {
+	*     // 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 );
+	*/
+	( addon: AddonFcn, fallback: FallbackFcn ): Dispatcher;
+
+	/**
+	* Returns a function which dispatches to a native add-on applying a nullary function using alternative indexing semantics.
+	*
+	* @param addon - add-on function
+	* @param fallback - fallback function
+	* @returns 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.ndarray( addon, fallback );
+	*
+	* // ...
+	*
+	* // Invoke the dispatch function with strided array arguments:
+	* f( 2, 'generic', [ 1, 2 ], 1, 0 );
+	*/
+	ndarray( addon: AddonFcn, fallback: FallbackFcnWithOffsets ): DispatcherWithOffsets; // tslint:disable-line:max-line-length
+}
+
+/**
+* Returns a function which dispatches to a native add-on applying a nullary function.
+*
+* @param addon - add-on function
+* @param fallback - fallback function
+* @returns dispatch function
+*
+* @example
+* function addon( N, dtypeX, x, strideX ) {
+*     // Call into native add-on...
+* }
+*
+* function fallback( N, dtypeX, x, strideX ) {
+*     // 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 );
+*
+* @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.ndarray( addon, fallback );
+*
+* // ...
+*
+* // Invoke the dispatch function with strided array arguments:
+* f( 2, 'generic', [ 1, 2 ], 1, 0 );
+*/
+declare var dispatch: Dispatch;
+
+
+// EXPORTS //
+
+export = dispatch;

package/docs/types/test.ts

@@ -0,0 +1,269 @@
+/*
+* @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.
+*/
+
+/// <reference types="@stdlib/types"/>
+
+import { Collection } from '@stdlib/types/object';
+import dispatch = require( './index' );
+
+
+// FUNCTIONS //
+
+/**
+* Add-on function.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type (enumeration constant)
+* @param x - output array
+* @param strideX - `x` stride length
+*/
+function addon( N: number, dtypeX: number, x: Collection, strideX: number ): void { // tslint:disable-line:max-line-length
+	let i;
+	if ( dtypeX !== dtypeX ) {
+		throw new Error( 'beep' );
+	}
+	for ( i = 0; i < N; i += 1 ) {
+		x[ i * strideX ] = i;
+	}
+}
+
+/**
+* Fallback function.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type
+* @param x - output array
+* @param strideX - `x` stride length
+*/
+function fallback( N: number, dtypeX: any, x: Collection, strideX: number ): void { // tslint:disable-line:max-line-length
+	let i;
+	if ( dtypeX !== dtypeX ) {
+		throw new Error( 'beep' );
+	}
+	for ( i = 0; i < N; i += 1 ) {
+		x[ i * strideX ] = i;
+	}
+}
+
+/**
+* Fallback function with alternative indexing semantics.
+*
+* @param N - number of indexed elements
+* @param dtypeX - `x` data type
+* @param x - output array
+* @param strideX - `x` stride length
+* @param offsetX - starting `x` index
+*/
+function fallbackWithOffsets( N: number, dtypeX: any, x: Collection, strideX: number, offsetX: number ): void { // tslint:disable-line:max-line-length
+	let i;
+	if ( dtypeX !== dtypeX ) {
+		throw new Error( 'beep' );
+	}
+	for ( i = 0; i < N; i += 1 ) {
+		x[ offsetX + ( i * strideX ) ] = i;
+	}
+}
+
+
+// TESTS //
+
+// The function returns a dispatch function...
+{
+	dispatch( addon, fallback ); // $ExpectType Dispatcher
+}
+
+// The compiler throws an error if not provided a first argument which is an add-on function...
+{
+	dispatch( '10', fallback ); // $ExpectError
+	dispatch( 10, fallback ); // $ExpectError
+	dispatch( true, fallback ); // $ExpectError
+	dispatch( false, fallback ); // $ExpectError
+	dispatch( null, fallback ); // $ExpectError
+	dispatch( undefined, fallback ); // $ExpectError
+	dispatch( [], fallback ); // $ExpectError
+	dispatch( {}, fallback ); // $ExpectError
+	dispatch( ( x: string ): string => x, fallback ); // $ExpectError
+}
+
+// The compiler throws an error if not provided a second argument which is a fallback function...
+{
+	dispatch( addon, '10' ); // $ExpectError
+	dispatch( addon, 10 ); // $ExpectError
+	dispatch( addon, true ); // $ExpectError
+	dispatch( addon, false ); // $ExpectError
+	dispatch( addon, null ); // $ExpectError
+	dispatch( addon, undefined ); // $ExpectError
+	dispatch( addon, [] ); // $ExpectError
+	dispatch( addon, {} ); // $ExpectError
+	dispatch( addon, ( x: string ): string => x ); // $ExpectError
+}
+
+// The returned function returns a collection...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch( addon, fallback );
+
+	f( x.length, 'float64', x, 1 ); // $ExpectType Collection
+}
+
+// The compiler throws an error if the returned function is not provided a first argument which is a number...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch( addon, fallback );
+
+	f( '10', 'float64', x, 1 ); // $ExpectError
+	f( true, 'float64', x, 1 ); // $ExpectError
+	f( false, 'float64', x, 1 ); // $ExpectError
+	f( null, 'float64', x, 1 ); // $ExpectError
+	f( undefined, 'float64', x, 1 ); // $ExpectError
+	f( [], 'float64', x, 1 ); // $ExpectError
+	f( {}, 'float64', x, 1 ); // $ExpectError
+	f( ( x: number ): number => x, 'float64', x, 1 ); // $ExpectError
+}
+
+// The compiler throws an error if the returned function is not provided a third argument which is a collection...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch( addon, fallback );
+
+	f( x.length, 'float64', true, 1 ); // $ExpectError
+	f( x.length, 'float64', false, 1 ); // $ExpectError
+	f( x.length, 'float64', null, 1 ); // $ExpectError
+	f( x.length, 'float64', undefined, 1 ); // $ExpectError
+	f( x.length, 'float64', {}, 1 ); // $ExpectError
+}
+
+// The compiler throws an error if the returned function is not provided a fourth argument which is a number...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch( addon, fallback );
+
+	f( x.length, 'float64', x, '10' ); // $ExpectError
+	f( x.length, 'float64', x, true ); // $ExpectError
+	f( x.length, 'float64', x, false ); // $ExpectError
+	f( x.length, 'float64', x, null ); // $ExpectError
+	f( x.length, 'float64', x, undefined ); // $ExpectError
+	f( x.length, 'float64', x, [] ); // $ExpectError
+	f( x.length, 'float64', x, {} ); // $ExpectError
+	f( x.length, 'float64', x, ( x: number ): number => x ); // $ExpectError
+}
+
+// Attached to the main export is an `ndarray` method which returns a dispatch function...
+{
+	dispatch.ndarray( addon, fallbackWithOffsets ); // $ExpectType DispatcherWithOffsets
+}
+
+// The compiler throws an error if the `ndarray` method is not provided a first argument which is an add-on function...
+{
+	dispatch.ndarray( '10', fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( 10, fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( true, fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( false, fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( null, fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( undefined, fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( [], fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( {}, fallbackWithOffsets ); // $ExpectError
+	dispatch.ndarray( ( x: string ): string => x, fallbackWithOffsets ); // $ExpectError
+}
+
+// The compiler throws an error if the `ndarray` method is not provided a second argument which is a fallback function...
+{
+	dispatch.ndarray( addon, '10' ); // $ExpectError
+	dispatch.ndarray( addon, 10 ); // $ExpectError
+	dispatch.ndarray( addon, true ); // $ExpectError
+	dispatch.ndarray( addon, false ); // $ExpectError
+	dispatch.ndarray( addon, null ); // $ExpectError
+	dispatch.ndarray( addon, undefined ); // $ExpectError
+	dispatch.ndarray( addon, [] ); // $ExpectError
+	dispatch.ndarray( addon, {} ); // $ExpectError
+	dispatch.ndarray( addon, ( x: string ): string => x ); // $ExpectError
+}
+
+// The `ndarray` method returns a function which returns a collection...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch.ndarray( addon, fallbackWithOffsets );
+
+	f( x.length, 'float64', x, 1, 0 ); // $ExpectType Collection
+}
+
+// The compiler throws an error if the returned function is not provided a first argument which is a number...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch.ndarray( addon, fallbackWithOffsets );
+
+	f( '10', 'float64', x, 1, 0 ); // $ExpectError
+	f( true, 'float64', x, 1, 0 ); // $ExpectError
+	f( false, 'float64', x, 1, 0 ); // $ExpectError
+	f( null, 'float64', x, 1, 0 ); // $ExpectError
+	f( undefined, 'float64', x, 1, 0 ); // $ExpectError
+	f( [], 'float64', x, 1, 0 ); // $ExpectError
+	f( {}, 'float64', x, 1, 0 ); // $ExpectError
+	f( ( x: number ): number => x, 'float64', x, 1, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the returned function is not provided a third argument which is a collection...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch.ndarray( addon, fallbackWithOffsets );
+
+	f( x.length, 'float64', true, 1, 0 ); // $ExpectError
+	f( x.length, 'float64', false, 1, 0 ); // $ExpectError
+	f( x.length, 'float64', null, 1, 0 ); // $ExpectError
+	f( x.length, 'float64', undefined, 1, 0 ); // $ExpectError
+	f( x.length, 'float64', {}, 1, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the returned function is not provided a fourth argument which is a number...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch.ndarray( addon, fallbackWithOffsets );
+
+	f( x.length, 'float64', x, '10', 0 ); // $ExpectError
+	f( x.length, 'float64', x, true, 0 ); // $ExpectError
+	f( x.length, 'float64', x, false, 0 ); // $ExpectError
+	f( x.length, 'float64', x, null, 0 ); // $ExpectError
+	f( x.length, 'float64', x, undefined, 0 ); // $ExpectError
+	f( x.length, 'float64', x, [], 0 ); // $ExpectError
+	f( x.length, 'float64', x, {}, 0 ); // $ExpectError
+	f( x.length, 'float64', x, ( x: number ): number => x, 0 ); // $ExpectError
+}
+
+// The compiler throws an error if the returned function is not provided a fifth argument which is a number...
+{
+	const x = new Float64Array( 10 );
+
+	const f = dispatch.ndarray( addon, fallbackWithOffsets );
+
+	f( x.length, 'float64', x, 1, '10' ); // $ExpectError
+	f( x.length, 'float64', x, 1, true ); // $ExpectError
+	f( x.length, 'float64', x, 1, false ); // $ExpectError
+	f( x.length, 'float64', x, 1, null ); // $ExpectError
+	f( x.length, 'float64', x, 1, undefined ); // $ExpectError
+	f( x.length, 'float64', x, 1, [] ); // $ExpectError
+	f( x.length, 'float64', x, 1, {} ); // $ExpectError
+	f( x.length, 'float64', x, 1, ( x: number ): number => x ); // $ExpectError
+}

package/lib/index.js

@@ -0,0 +1,60 @@
+/**
+* @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';
+
+/**
+* Dispatch to a native add-on applying a nullary function.
+*
+* @module @stdlib/strided-base-nullary-addon-dispatch
+*
+* @example
+* var dispatch = require( '@stdlib/strided-base-nullary-addon-dispatch' );
+*
+* function addon( N, dtypeX, x, strideX ) {
+*     // Call into native add-on...
+* }
+*
+* function fallback( N, dtypeX, x, strideX ) {
+*     // 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 );
+*/
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var main = require( './main.js' );
+var ndarray = require( './ndarray.js' );
+
+
+// MAIN //
+
+setReadOnly( main, 'ndarray', ndarray );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/main.js

@@ -0,0 +1,153 @@
+/**
+* @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 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 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.
+*
+* ## Notes
+*
+* -   The returned function has the following signature:
+*
+*     ```text
+*     f( N, dtypeX, x, strideX )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type.
+*     -   **x**: output array.
+*     -   **strideX**: `x` stride length.
+*
+* -   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 )
+*     ```
+*
+*     where
+*
+*     -   **N**: number of indexed elements.
+*     -   **dtypeX**: `x` data type.
+*     -   **x**: output array.
+*     -   **strideX**: `x` stride length.
+*
+* @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 ) {
+*     // 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 );
+*/
+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
+	* @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 ) {
+		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 );
+			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 ( dtypeX === COMPLEX64 ) {
+			viewX = reinterpretComplex64( x, 0 );
+		} else if ( dtypeX === COMPLEX128 ) {
+			viewX = reinterpretComplex128( x, 0 );
+		} else {
+			viewX = x;
+		}
+		addon( N, dtypeX, viewX, strideX );
+		return x;
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = dispatch;