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

package/README.md

@@ -0,0 +1,385 @@
+<!--
+
+@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.
+
+-->
+
+# dispatch
+
+[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
+
+> Dispatch to a native add-on applying a binary function to two input strided arrays.
+
+<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<!-- Package usage documentation. -->
+
+<section class="installation">
+
+## Installation
+
+```bash
+npm install @stdlib/strided-base-binary-addon-dispatch
+```
+
+</section>
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var dispatch = require( '@stdlib/strided-base-binary-addon-dispatch' );
+```
+
+#### dispatch( addon, fallback )
+
+Returns a function which dispatches to a native add-on applying a binary function to two input strided arrays.
+
+<!-- eslint-disable max-len -->
+
+```javascript
+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 );
+```
+
+The returned function has 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.
+-   **x**: input array.
+-   **strideX**: `x` stride length.
+-   **dtypeY**: `y` data type.
+-   **y**: input array.
+-   **strideY**: `y` stride length.
+-   **dtypeZ**: `z` data type.
+-   **z**: output array.
+-   **strideZ**: `z` stride length.
+
+The `addon` 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, dtypeY, y, strideY, dtypeZ, z, strideZ )
+```
+
+where
+
+-   **N**: number of indexed elements.
+-   **dtypeX**: `x` data type.
+-   **x**: input array.
+-   **strideX**: `x` stride length.
+-   **dtypeY**: `y` data type.
+-   **y**: input array.
+-   **strideY**: `y` stride length.
+-   **dtypeZ**: `z` data type.
+-   **z**: output array.
+-   **strideZ**: `z` stride length.
+
+#### dispatch.ndarray( addon, fallback )
+
+Returns a function which dispatches to a native add-on applying a binary function to two input arrays using alternative indexing semantics.
+
+<!-- eslint-disable max-len, max-params -->
+
+```javascript
+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.ndarray( 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 );
+```
+
+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 `addon` 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.
+
+</section>
+
+<!-- /.usage -->
+
+<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="notes">
+
+## Notes
+
+-   To determine whether to dispatch to the `addon` function, the returned dispatch function checks whether the provided arrays are typed arrays. If the provided arrays are typed arrays, the dispatch function invokes the `addon` function; otherwise, the dispatch function invokes the `fallback` function.
+
+</section>
+
+<!-- /.notes -->
+
+<!-- Package usage examples. -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint-disable max-len, max-params -->
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var Float64Array = require( '@stdlib/array-float64' );
+var dispatch = require( '@stdlib/strided-base-binary-addon-dispatch' );
+
+function addon( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ ) {
+    console.log( x );
+    // => <Float64Array>[ 3, 4 ]
+
+    console.log( y );
+    // => <Float64Array>[ 7, 8 ]
+
+    console.log( z );
+    // => <Float64Array>[ 0, 0 ]
+}
+
+function fallback( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY, dtypeZ, z, strideZ, offsetZ ) {
+    console.log( x );
+    // => [ 1, 2, 3, 4 ]
+
+    console.log( y );
+    // => [ 5, 6, 7, 8 ]
+
+    console.log( z );
+    // => [ 0, 0, 0, 0 ]
+}
+
+// Create a dispatch function:
+var f = dispatch.ndarray( addon, fallback );
+
+// Create strided arrays:
+var x = new Float64Array( [ 1, 2, 3, 4 ] );
+var y = new Float64Array( [ 5, 6, 7, 8 ] );
+var z = new Float64Array( [ 0, 0, 0, 0 ] );
+
+// Dispatch to the add-on function:
+f( 2, 'float64', x, 1, 2, 'float64', y, 1, 2, 'float64', z, 1, 2 );
+
+// Define new strided arrays:
+x = [ 1, 2, 3, 4 ];
+y = [ 5, 6, 7, 8 ];
+z = [ 0, 0, 0, 0 ];
+
+// Dispatch to the fallback function:
+f( 2, 'generic', x, 1, 2, 'generic', y, 1, 2, 'generic', z, 1, 2 );
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="references">
+
+</section>
+
+<!-- /.references -->
+
+<!-- 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="main-repo" >
+
+* * *
+
+## Notice
+
+This package is part of [stdlib][stdlib], a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.
+
+For more information on the project, filing bug reports and feature requests, and guidance on how to develop [stdlib][stdlib], see the main project [repository][stdlib].
+
+#### Community
+
+[![Chat][chat-image]][chat-url]
+
+---
+
+## License
+
+See [LICENSE][stdlib-license].
+
+
+## Copyright
+
+Copyright &copy; 2016-2022. The Stdlib [Authors][stdlib-authors].
+
+</section>
+
+<!-- /.stdlib -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+[npm-image]: http://img.shields.io/npm/v/@stdlib/strided-base-binary-addon-dispatch.svg
+[npm-url]: https://npmjs.org/package/@stdlib/strided-base-binary-addon-dispatch
+
+[test-image]: https://github.com/stdlib-js/strided-base-binary-addon-dispatch/actions/workflows/test.yml/badge.svg
+[test-url]: https://github.com/stdlib-js/strided-base-binary-addon-dispatch/actions/workflows/test.yml
+
+[coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/strided-base-binary-addon-dispatch/main.svg
+[coverage-url]: https://codecov.io/github/stdlib-js/strided-base-binary-addon-dispatch?branch=main
+
+<!--
+
+[dependencies-image]: https://img.shields.io/david/stdlib-js/strided-base-binary-addon-dispatch.svg
+[dependencies-url]: https://david-dm.org/stdlib-js/strided-base-binary-addon-dispatch/main
+
+-->
+
+[umd]: https://github.com/umdjs/umd
+[es-module]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+
+[deno-url]: https://github.com/stdlib-js/strided-base-binary-addon-dispatch/tree/deno
+[umd-url]: https://github.com/stdlib-js/strided-base-binary-addon-dispatch/tree/umd
+[esm-url]: https://github.com/stdlib-js/strided-base-binary-addon-dispatch/tree/esm
+
+[chat-image]: https://img.shields.io/gitter/room/stdlib-js/stdlib.svg
+[chat-url]: https://gitter.im/stdlib-js/stdlib/
+
+[stdlib]: https://github.com/stdlib-js/stdlib
+
+[stdlib-authors]: https://github.com/stdlib-js/stdlib/graphs/contributors
+
+[stdlib-license]: https://raw.githubusercontent.com/stdlib-js/strided-base-binary-addon-dispatch/main/LICENSE
+
+</section>
+
+<!-- /.links -->

package/docs/repl.txt

@@ -0,0 +1,179 @@
+
+{{alias}}( addon, fallback )
+    Returns a function which dispatches to a native add-on applying binary
+    function to two input strided arrays.
+
+    The returned function has the following signature:
+
+      f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
+
+    where
+
+    - N: number of indexed elements.
+    - dtypeX: `x` data type.
+    - x: input array.
+    - strideX: `x` stride length.
+    - dtypeY: `y` data type.
+    - y: input array.
+    - strideY: `y` stride length.
+    - dtypeZ: `z` data type.
+    - z: output array.
+    - strideZ: `z` stride length.
+
+    To determine whether to dispatch to the `addon` function, the returned
+    dispatch function checks whether the provided arrays are typed arrays.
+
+    If the provided arrays are typed arrays, the dispatch function invokes the
+    `addon` function; otherwise, the dispatch function invokes the `fallback`
+    function.
+
+    Parameters
+    ----------
+    addon: Function
+        Add-on interface. The function should have the following signature:
+
+          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.
+        - z: output array.
+        - strideZ: `z` stride length.
+
+    fallback: Function
+        Fallback function. The function should have the following signature:
+
+          f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
+
+        where
+
+        - N: number of indexed elements.
+        - dtypeX: `x` data type.
+        - x: input array.
+        - strideX: `x` stride length.
+        - dtypeY: `y` data type.
+        - y: input array.
+        - strideY: `y` stride length.
+        - dtypeZ: `z` data type.
+        - z: output array.
+        - strideZ: `z` stride length.
+
+    Returns
+    -------
+    fcn: Function
+        Dispatch function.
+
+    Examples
+    --------
+    > function addon( N, dx, x, sx, dy, y, sy, dz, z, sz ) {
+    ...     // Call into native add-on...
+    ... };
+    > function fallback( N, dx, x, sx, dy, y, sy, dz, z, sz ) {
+    ...     // Fallback JavaScript implementation...
+    ... };
+    > var f = {{alias}}( addon, fallback );
+    > var dt = 'generic';
+    > f( 2, dt, [ 1, 2 ], 1, dt, [ 3, 4 ], 1, dt, [ 0, 0 ], 1 );
+
+
+{{alias}}.ndarray( addon, fallback )
+    Returns a function which dispatches to a native add-on applying a binary
+    function to two input strided arrays using alternative indexing semantics.
+
+    The returned function has the following signature:
+
+      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.
+
+    To determine whether to dispatch to the `addon` function, the returned
+    dispatch function checks whether the provided arrays are typed arrays.
+
+    If the provided arrays are typed arrays, the dispatch function invokes the
+    `addon` function; otherwise, the dispatch function invokes the `fallback`
+    function.
+
+    Parameters
+    ----------
+    addon: Function
+        Add-on interface. The function should have the following signature:
+
+          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.
+
+    fallback: Function
+        Fallback function. The function should have the following signature:
+
+          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.
+
+    Returns
+    -------
+    fcn: Function
+        Dispatch function.
+
+    Examples
+    --------
+    > function addon( N, dx, x, sx, dy, y, sy, dz, z, sz ) {
+    ...     // Call into native add-on...
+    ... };
+    > function fallback( N, dx, x, sx, ox, dy, y, sy, dz, z, sz, oz ) {
+    ...     // Fallback JavaScript implementation...
+    ... };
+    > var f = {{alias}}.ndarray( addon, fallback );
+    > var dt = 'generic';
+    > f( 2, dt, [ 1, 2 ], 1, 0, dt, [ 3, 4 ], 1, 0, dt, [ 0, 0 ], 1, 0 );
+
+    See Also
+    --------
+