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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/CITATION.cff +30 -0
  2. package/LICENSE +0 -304
  3. package/NOTICE +1 -1
  4. package/README.md +23 -11
  5. package/dist/index.d.ts +3 -0
  6. package/dist/index.js +7 -0
  7. package/dist/index.js.map +7 -0
  8. package/docs/types/index.d.ts +9 -9
  9. package/lib/index.js +7 -0
  10. package/lib/main.js +172 -6
  11. package/lib/ndarray.js +7 -6
  12. package/package.json +24 -22
  13. package/docs/repl.txt +0 -179
  14. package/docs/types/test.ts +0 -475
  15. package/lib/binary.js +0 -200
package/lib/main.js CHANGED
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @license Apache-2.0
3
3
  *
4
- * Copyright (c) 2020 The Stdlib Authors.
4
+ * Copyright (c) 2021 The Stdlib Authors.
5
5
  *
6
6
  * Licensed under the Apache License, Version 2.0 (the "License");
7
7
  * you may not use this file except in compliance with the License.
@@ -16,20 +16,186 @@
16
16
  * limitations under the License.
17
17
  */
18
18
 
19
+ /* eslint-disable max-len */
20
+
19
21
  'use strict';
20
22
 
21
23
  // MODULES //
22
24
 
23
- var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
24
- var binary = require( './binary.js' );
25
- var ndarray = require( './ndarray.js' );
25
+ var isFunction = require( '@stdlib/assert-is-function' );
26
+ var isTypedArrayLike = require( '@stdlib/assert-is-typed-array-like' );
27
+ var resolve = require( '@stdlib/strided-base-dtype-resolve-enum' );
28
+ var reinterpretComplex64 = require( '@stdlib/strided-base-reinterpret-complex64' );
29
+ var reinterpretComplex128 = require( '@stdlib/strided-base-reinterpret-complex128' );
30
+ var format = require( '@stdlib/string-format' );
31
+
32
+
33
+ // VARIABLES //
34
+
35
+ var COMPLEX64 = resolve( 'complex64' );
36
+ var COMPLEX128 = resolve( 'complex128' );
26
37
 
27
38
 
28
39
  // MAIN //
29
40
 
30
- setReadOnly( binary, 'ndarray', ndarray );
41
+ /**
42
+ * Returns a function which dispatches to a native add-on applying a binary function to two input strided arrays.
43
+ *
44
+ * ## Notes
45
+ *
46
+ * - The returned function has the following signature:
47
+ *
48
+ * ```text
49
+ * f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
50
+ * ```
51
+ *
52
+ * where
53
+ *
54
+ * - **N**: number of indexed elements.
55
+ * - **dtypeX**: `x` data type.
56
+ * - **x**: input array.
57
+ * - **strideX**: `x` stride length.
58
+ * - **dtypeY**: `y` data type.
59
+ * - **y**: input array.
60
+ * - **strideY**: `y` stride length.
61
+ * - **dtypeZ**: `z` data type.
62
+ * - **z**: output array.
63
+ * - **strideY**: `z` stride length.
64
+ *
65
+ * - The add-on function should have the following signature:
66
+ *
67
+ * ```text
68
+ * f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
69
+ * ```
70
+ *
71
+ * where
72
+ *
73
+ * - **N**: number of indexed elements.
74
+ * - **dtypeX**: `x` data type (enumeration constant).
75
+ * - **x**: input array.
76
+ * - **strideX**: `x` stride length.
77
+ * - **dtypeY**: `y` data type (enumeration constant).
78
+ * - **y**: input array.
79
+ * - **strideY**: `y` stride length.
80
+ * - **dtypeZ**: `z` data type (enumeration constant).
81
+ * - **z**: output array.
82
+ * - **strideZ**: `z` stride length.
83
+ *
84
+ * - The fallback function should have the following signature:
85
+ *
86
+ * ```text
87
+ * f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
88
+ * ```
89
+ *
90
+ * where
91
+ *
92
+ * - **N**: number of indexed elements.
93
+ * - **dtypeX**: `x` data type.
94
+ * - **x**: input array.
95
+ * - **strideX**: `x` stride length.
96
+ * - **dtypeY**: `y` data type.
97
+ * - **y**: input array.
98
+ * - **strideY**: `y` stride length.
99
+ * - **dtypeZ**: `z` data type.
100
+ * - **z**: output array.
101
+ * - **strideZ**: `z` stride length.
102
+ *
103
+ * @param {Function} addon - add-on interface
104
+ * @param {Function} fallback - fallback function
105
+ * @throws {TypeError} first argument must be a function
106
+ * @throws {TypeError} second argument must be a function
107
+ * @returns {Function} dispatch function
108
+ *
109
+ * @example
110
+ * function addon( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ ) {
111
+ * // Call into native add-on...
112
+ * }
113
+ *
114
+ * function fallback( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ ) {
115
+ * // Fallback JavaScript implementation...
116
+ * }
117
+ *
118
+ * // Create a dispatch function:
119
+ * var f = dispatch( addon, fallback );
120
+ *
121
+ * // ...
122
+ *
123
+ * // Invoke the dispatch function with strided array arguments:
124
+ * f( 2, 'generic', [ 1, 2 ], 1, 'generic', [ 3, 4 ], 1, 'generic', [ 0, 0 ], 1 );
125
+ */
126
+ function dispatch( addon, fallback ) {
127
+ if ( !isFunction( addon ) ) {
128
+ throw new TypeError( format( 'invalid argument. First argument must be a function. Value: `%s`.', addon ) );
129
+ }
130
+ if ( !isFunction( fallback ) ) {
131
+ throw new TypeError( format( 'invalid argument. Second argument must be a function. Value: `%s`.', fallback ) );
132
+ }
133
+ return dispatcher;
134
+
135
+ /**
136
+ * Dispatches to a native add-on.
137
+ *
138
+ * @private
139
+ * @param {integer} N - number of indexed elements
140
+ * @param {*} dtypeX - `x` data type
141
+ * @param {Collection} x - input array
142
+ * @param {integer} strideX - `x` stride length
143
+ * @param {*} dtypeY - `y` data type
144
+ * @param {Collection} y - input array
145
+ * @param {integer} strideY - `y` stride length
146
+ * @param {*} dtypeZ - `z` data type
147
+ * @param {Collection} z - destination array
148
+ * @param {integer} strideZ - `z` stride length
149
+ * @throws {TypeError} unable to resolve a strided array function supporting the provided array argument data types
150
+ * @returns {Collection} `z`
151
+ */
152
+ function dispatcher( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ ) {
153
+ var viewX;
154
+ var viewY;
155
+ var viewZ;
156
+
157
+ // 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)...
158
+ if (
159
+ !isTypedArrayLike( x ) ||
160
+ !isTypedArrayLike( y ) ||
161
+ !isTypedArrayLike( z )
162
+ ) {
163
+ fallback( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ );
164
+ return z;
165
+ }
166
+ dtypeX = resolve( dtypeX );
167
+ dtypeY = resolve( dtypeY );
168
+ dtypeZ = resolve( dtypeZ );
169
+ if ( dtypeX === null || dtypeY === null || dtypeZ === null ) {
170
+ throw new TypeError( 'invalid arguments. Unable to resolve a strided array function supporting the provided array argument data types.' );
171
+ }
172
+ if ( dtypeX === COMPLEX64 ) {
173
+ viewX = reinterpretComplex64( x, 0 );
174
+ } else if ( dtypeX === COMPLEX128 ) {
175
+ viewX = reinterpretComplex128( x, 0 );
176
+ } else {
177
+ viewX = x;
178
+ }
179
+ if ( dtypeY === COMPLEX64 ) {
180
+ viewY = reinterpretComplex64( y, 0 );
181
+ } else if ( dtypeY === COMPLEX128 ) {
182
+ viewY = reinterpretComplex128( y, 0 );
183
+ } else {
184
+ viewY = y;
185
+ }
186
+ if ( dtypeZ === COMPLEX64 ) {
187
+ viewZ = reinterpretComplex64( z, 0 );
188
+ } else if ( dtypeZ === COMPLEX128 ) {
189
+ viewZ = reinterpretComplex128( z, 0 );
190
+ } else {
191
+ viewZ = z;
192
+ }
193
+ addon( N, dtypeX, viewX, strideX, dtypeY, viewY, strideY, dtypeZ, viewZ, strideZ );
194
+ return z;
195
+ }
196
+ }
31
197
 
32
198
 
33
199
  // EXPORTS //
34
200
 
35
- module.exports = binary;
201
+ module.exports = dispatch;
package/lib/ndarray.js CHANGED
@@ -30,6 +30,7 @@ var reinterpretComplex64 = require( '@stdlib/strided-base-reinterpret-complex64'
30
30
  var reinterpretComplex128 = require( '@stdlib/strided-base-reinterpret-complex128' );
31
31
  var offsetView = require( '@stdlib/strided-base-offset-view' );
32
32
  var minViewBufferIndex = require( '@stdlib/strided-base-min-view-buffer-index' );
33
+ var format = require( '@stdlib/string-format' );
33
34
 
34
35
 
35
36
  // VARIABLES //
@@ -41,7 +42,7 @@ var COMPLEX128 = resolve( 'complex128' );
41
42
  // MAIN //
42
43
 
43
44
  /**
44
- * Returns a function which dispatches to a native add-on applying a binary function to two input arrays using alternative indexing semantics.
45
+ * Returns a function which dispatches to a native add-on applying a binary function to two input strided arrays using alternative indexing semantics.
45
46
  *
46
47
  * ## Notes
47
48
  *
@@ -133,10 +134,10 @@ var COMPLEX128 = resolve( 'complex128' );
133
134
  */
134
135
  function dispatch( addon, fallback ) {
135
136
  if ( !isFunction( addon ) ) {
136
- throw new TypeError( 'invalid argument. First argument must be a function. Value: `' + addon + '`.' );
137
+ throw new TypeError( format( 'invalid argument. First argument must be a function. Value: `%s`.', addon ) );
137
138
  }
138
139
  if ( !isFunction( fallback ) ) {
139
- throw new TypeError( 'invalid argument. Second argument must be a function. Value: `' + fallback + '`.' );
140
+ throw new TypeError( format( 'invalid argument. Second argument must be a function. Value: `%s`.', fallback ) );
140
141
  }
141
142
  return dispatcher;
142
143
 
@@ -184,13 +185,13 @@ function dispatch( addon, fallback ) {
184
185
  throw new TypeError( 'invalid arguments. Unable to resolve a strided array function supporting the provided array argument data types.' );
185
186
  }
186
187
  if ( !isNonNegativeInteger( offsetX ) ) {
187
- throw new TypeError( 'invalid argument. First input array offset argument must be a nonnegative integer.' );
188
+ throw new TypeError( format( 'invalid argument. First input array offset must be a nonnegative integer. Value: `%s`.', offsetX ) );
188
189
  }
189
190
  if ( !isNonNegativeInteger( offsetY ) ) {
190
- throw new TypeError( 'invalid argument. Second input array offset argument must be a nonnegative integer.' );
191
+ throw new TypeError( format( 'invalid argument. Second input array offset must be a nonnegative integer. Value: `%s`.', offsetY ) );
191
192
  }
192
193
  if ( !isNonNegativeInteger( offsetZ ) ) {
193
- throw new TypeError( 'invalid argument. Output array offset argument must be a nonnegative integer.' );
194
+ throw new TypeError( format( 'invalid argument. Output array offset must be a nonnegative integer. Value: `%s`.', offsetZ ) );
194
195
  }
195
196
  offsetX = minViewBufferIndex( N, strideX, offsetX );
196
197
  offsetY = minViewBufferIndex( N, strideY, offsetY );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@stdlib/strided-base-binary-addon-dispatch",
3
- "version": "0.0.1",
3
+ "version": "0.1.0",
4
4
  "description": "Dispatch to a native add-on applying a binary function to two input strided arrays.",
5
5
  "license": "Apache-2.0",
6
6
  "author": {
@@ -37,29 +37,31 @@
37
37
  "url": "https://github.com/stdlib-js/stdlib/issues"
38
38
  },
39
39
  "dependencies": {
40
- "@stdlib/assert-is-function": "^0.0.x",
41
- "@stdlib/assert-is-nonnegative-integer": "^0.0.x",
42
- "@stdlib/assert-is-typed-array-like": "^0.0.x",
43
- "@stdlib/strided-base-dtype-resolve-enum": "^0.0.x",
44
- "@stdlib/strided-base-min-view-buffer-index": "^0.0.x",
45
- "@stdlib/strided-base-offset-view": "^0.0.x",
46
- "@stdlib/strided-base-reinterpret-complex128": "^0.0.x",
47
- "@stdlib/strided-base-reinterpret-complex64": "^0.0.x",
48
- "@stdlib/types": "^0.0.x",
49
- "@stdlib/utils-define-nonenumerable-read-only-property": "^0.0.x"
40
+ "@stdlib/assert-is-function": "^0.1.0",
41
+ "@stdlib/assert-is-nonnegative-integer": "^0.1.0",
42
+ "@stdlib/assert-is-typed-array-like": "^0.1.0",
43
+ "@stdlib/strided-base-dtype-resolve-enum": "^0.1.0",
44
+ "@stdlib/strided-base-min-view-buffer-index": "^0.1.0",
45
+ "@stdlib/strided-base-offset-view": "^0.1.0",
46
+ "@stdlib/strided-base-reinterpret-complex128": "^0.1.0",
47
+ "@stdlib/strided-base-reinterpret-complex64": "^0.1.0",
48
+ "@stdlib/string-format": "^0.1.0",
49
+ "@stdlib/types": "^0.1.0",
50
+ "@stdlib/utils-define-nonenumerable-read-only-property": "^0.1.0",
51
+ "@stdlib/error-tools-fmtprodmsg": "^0.1.0"
50
52
  },
51
53
  "devDependencies": {
52
- "@stdlib/array-complex128": "^0.0.x",
53
- "@stdlib/array-complex64": "^0.0.x",
54
- "@stdlib/array-float64": "^0.0.x",
55
- "@stdlib/assert-has-own-property": "^0.0.x",
56
- "@stdlib/assert-is-float32array": "^0.0.x",
57
- "@stdlib/assert-is-float64array": "^0.0.x",
58
- "@stdlib/bench": "^0.0.x",
59
- "@stdlib/utils-noop": "^0.0.x",
54
+ "@stdlib/array-complex128": "^0.0.6",
55
+ "@stdlib/array-complex64": "^0.0.6",
56
+ "@stdlib/array-float64": "^0.1.0",
57
+ "@stdlib/assert-has-own-property": "^0.1.0",
58
+ "@stdlib/assert-is-float32array": "^0.1.0",
59
+ "@stdlib/assert-is-float64array": "^0.1.0",
60
+ "@stdlib/bench": "^0.1.0",
61
+ "@stdlib/utils-noop": "^0.1.0",
60
62
  "tape": "git+https://github.com/kgryte/tape.git#fix/globby",
61
63
  "istanbul": "^0.4.1",
62
- "tap-spec": "5.x.x"
64
+ "tap-min": "git+https://github.com/Planeshifter/tap-min.git"
63
65
  },
64
66
  "engines": {
65
67
  "node": ">=0.10.0",
@@ -89,7 +91,7 @@
89
91
  ],
90
92
  "__stdlib__": {},
91
93
  "funding": {
92
- "type": "patreon",
93
- "url": "https://www.patreon.com/athan"
94
+ "type": "opencollective",
95
+ "url": "https://opencollective.com/stdlib"
94
96
  }
95
97
  }
package/docs/repl.txt DELETED
@@ -1,179 +0,0 @@
1
-
2
- {{alias}}( addon, fallback )
3
- Returns a function which dispatches to a native add-on applying binary
4
- function to two input strided arrays.
5
-
6
- The returned function has the following signature:
7
-
8
- f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
9
-
10
- where
11
-
12
- - N: number of indexed elements.
13
- - dtypeX: `x` data type.
14
- - x: input array.
15
- - strideX: `x` stride length.
16
- - dtypeY: `y` data type.
17
- - y: input array.
18
- - strideY: `y` stride length.
19
- - dtypeZ: `z` data type.
20
- - z: output array.
21
- - strideZ: `z` stride length.
22
-
23
- To determine whether to dispatch to the `addon` function, the returned
24
- dispatch function checks whether the provided arrays are typed arrays.
25
-
26
- If the provided arrays are typed arrays, the dispatch function invokes the
27
- `addon` function; otherwise, the dispatch function invokes the `fallback`
28
- function.
29
-
30
- Parameters
31
- ----------
32
- addon: Function
33
- Add-on interface. The function should have the following signature:
34
-
35
- f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
36
-
37
- where
38
-
39
- - N: number of indexed elements.
40
- - dtypeX: `x` data type (enumeration constant).
41
- - x: input array.
42
- - strideX: `x` stride length.
43
- - dtypeY: `y` data type (enumeration constant).
44
- - y: input array.
45
- - strideY: `y` stride length.
46
- - dtypeZ: `z` data type.
47
- - z: output array.
48
- - strideZ: `z` stride length.
49
-
50
- fallback: Function
51
- Fallback function. The function should have the following signature:
52
-
53
- f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
54
-
55
- where
56
-
57
- - N: number of indexed elements.
58
- - dtypeX: `x` data type.
59
- - x: input array.
60
- - strideX: `x` stride length.
61
- - dtypeY: `y` data type.
62
- - y: input array.
63
- - strideY: `y` stride length.
64
- - dtypeZ: `z` data type.
65
- - z: output array.
66
- - strideZ: `z` stride length.
67
-
68
- Returns
69
- -------
70
- fcn: Function
71
- Dispatch function.
72
-
73
- Examples
74
- --------
75
- > function addon( N, dx, x, sx, dy, y, sy, dz, z, sz ) {
76
- ... // Call into native add-on...
77
- ... };
78
- > function fallback( N, dx, x, sx, dy, y, sy, dz, z, sz ) {
79
- ... // Fallback JavaScript implementation...
80
- ... };
81
- > var f = {{alias}}( addon, fallback );
82
- > var dt = 'generic';
83
- > f( 2, dt, [ 1, 2 ], 1, dt, [ 3, 4 ], 1, dt, [ 0, 0 ], 1 );
84
-
85
-
86
- {{alias}}.ndarray( addon, fallback )
87
- Returns a function which dispatches to a native add-on applying a binary
88
- function to two input strided arrays using alternative indexing semantics.
89
-
90
- The returned function has the following signature:
91
-
92
- f( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY, dtypeZ, z,
93
- strideZ, offsetZ )
94
-
95
- where
96
-
97
- - N: number of indexed elements.
98
- - dtypeX: `x` data type.
99
- - x: input array.
100
- - strideX: `x` stride length.
101
- - offsetX: starting `x` index.
102
- - dtypeY: `y` data type.
103
- - y: input array.
104
- - strideY: `y` stride length.
105
- - offsetY: starting `y` index.
106
- - dtypeZ: `z` data type.
107
- - z: output array.
108
- - strideZ: `z` stride length.
109
- - offsetZ: starting `z` index.
110
-
111
- To determine whether to dispatch to the `addon` function, the returned
112
- dispatch function checks whether the provided arrays are typed arrays.
113
-
114
- If the provided arrays are typed arrays, the dispatch function invokes the
115
- `addon` function; otherwise, the dispatch function invokes the `fallback`
116
- function.
117
-
118
- Parameters
119
- ----------
120
- addon: Function
121
- Add-on interface. The function should have the following signature:
122
-
123
- f( N, dtypeX, x, strideX, dtypeY, y, strideY, dtypeZ, z, strideZ )
124
-
125
- where
126
-
127
- - N: number of indexed elements.
128
- - dtypeX: `x` data type (enumeration constant).
129
- - x: input array.
130
- - strideX: `x` stride length.
131
- - dtypeY: `y` data type (enumeration constant).
132
- - y: input array.
133
- - strideY: `y` stride length.
134
- - dtypeZ: `z` data type (enumeration constant).
135
- - z: output array.
136
- - strideZ: `z` stride length.
137
-
138
- fallback: Function
139
- Fallback function. The function should have the following signature:
140
-
141
- f( N, dtypeX, x, strideX, offsetX, dtypeY, y, strideY, offsetY,
142
- dtypeZ, z, strideZ, offsetZ )
143
-
144
- where
145
-
146
- - N: number of indexed elements.
147
- - dtypeX: `x` data type.
148
- - x: input array.
149
- - strideX: `x` stride length.
150
- - offsetX: starting `x` index.
151
- - dtypeY: `y` data type.
152
- - y: input array.
153
- - strideY: `y` stride length.
154
- - offsetY: starting `y` index.
155
- - dtypeZ: `z` data type.
156
- - z: output array.
157
- - strideZ: `z` stride length.
158
- - offsetZ: starting `z` index.
159
-
160
- Returns
161
- -------
162
- fcn: Function
163
- Dispatch function.
164
-
165
- Examples
166
- --------
167
- > function addon( N, dx, x, sx, dy, y, sy, dz, z, sz ) {
168
- ... // Call into native add-on...
169
- ... };
170
- > function fallback( N, dx, x, sx, ox, dy, y, sy, dz, z, sz, oz ) {
171
- ... // Fallback JavaScript implementation...
172
- ... };
173
- > var f = {{alias}}.ndarray( addon, fallback );
174
- > var dt = 'generic';
175
- > f( 2, dt, [ 1, 2 ], 1, 0, dt, [ 3, 4 ], 1, 0, dt, [ 0, 0 ], 1, 0 );
176
-
177
- See Also
178
- --------
179
-