8000 Auto-generated commit · stdlib-js/ndarray-dispatch-by@8508064 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8508064

Browse files
stdlib-botstdlib-bot
committed
Auto-generated commit
1 parent 0a3a3bd commit 8508064

File tree

1 file changed

+206
-10
lines changed
Collapse file tree

1 file changed

+206
-10
lines changed

‎README.md

Lines changed: 206 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
@license Apache-2.0
44
5-
Copyright (c) 2023 The Stdlib Authors.
5+
Copyright (c) 2022 The Stdlib Authors.
66
77
Licensed under the Apache License, Version 2.0 (the "License");
88
you may not use this file except in compliance with the License.
@@ -18,11 +18,11 @@ limitations under the License.
1818
1919
-->
2020

21-
# Dispatch By
21+
# Dispatch
2222

2323
[![NPM version][npm-image]][npm-url] [![Build Status][test-image]][test-url] [![Coverage Status][coverage-image]][coverage-url] <!-- [![dependencies][dependencies-image]][dependencies-url] -->
2424

25-
> Create an [ndarray][@stdlib/ndarray/ctor] function interface which accepts a callback function and performs multiple dispatch.
25+
> Create an [ndarray][@stdlib/ndarray/ctor] function interface which performs multiple dispatch.
2626
2727
<section class="intro">
2828

@@ -53,19 +53,180 @@ The [branches.md][branches-url] file summarizes the available branches and displ
5353
## Usage
5454

5555
```javascript
56-
var dispatchBy = require( '@stdlib/ndarray-dispatch-by' );
56+
var dispatch = require( '@stdlib/ndarray-dispatch' );
5757
```
5858

59-
#### dispatchBy( fcns, types, data, nargs, nin, nout )
59+
#### dispatch( fcns, types, data, nargs, nin, nout )
6060

61-
Creates an [ndarray][@stdlib/ndarray/ctor] function interface which accepts a callback function and performs multiple dispatch.
61+
Returns an [ndarray][@stdlib/ndarray/ctor] function interface which performs multiple dispatch.
62+
63+
<!-- eslint-disable array-element-newline -->
64+
65+
```javascript
66+
var unary = require( '@stdlib/ndarray-base-unary' );
67+
var Float64Array = require( '@stdlib/array-float64' );
68+
var Float32Array = require( '@stdlib/array-float32' );
69+
var ndarray = require( '@stdlib/ndarray-ctor' );
70+
71+
function foo( x ) {
72+
return x * 10.0;
73+
}
74+
75+
function bar( x ) {
76+
return x * 5.0;
77+
}
78+
79+
// Define a list of ndarray functions for applying a unary callback:
80+
var fcns = [
81+
unary,
82+
unary
83+
];
84+
85+
// Define a one-dimensional list of input and output array types:
86+
var types = [
87+
'float64', 'float64', // input, output
88+
'float32', 'float32' // input, output
89+
];
90+
91+
// Define a list of callbacks which should be applied based on the provided array types:
92+
var data = [
93+
foo,
94+
bar
95+
];
96+
97+
// Define the total number of input arguments:
98+
var nargs = 2; // input_array + output_array
99+
100+
// Define the number of input ndarrays:
101+
var nin = 1;
102+
103+
// Define the number of output ndarrays:
104+
var nout = 1;
105+
106+
// Create an ndarray function interface:
107+
var fcn = dispatch( fcns, types, data, nargs, nin, nout );
108+
109+
// ...
110+
111+
var xbuf = new Float64Array( [ 1.0, 2.0, 3.0 ] );
112+
var ybuf = new Float64Array( xbuf.length );
113+
114+
var x = ndarray( 'float64', xbuf, [ 3 ], [ 1 ], 0, 'row-major' );
115+
var y = ndarray( 'float64', ybuf, [ 3 ], [ 1 ], 0, 'row-major' );
116+
117+
fcn( x, y );
118+
// ybuf => <Float64Array>[ 10.0, 20.0, 30.0 ]
119+
120+
xbuf = new Float32Array( [ 1.0, 2.0, 3.0 ] );
121+
ybuf = new Float32Array( xbuf.length );
122+
123+
x = ndarray( 'float32', xbuf, [ 3 ], [ 1 ], 0, 'row-major' );
124+
y = ndarray( 'float32', ybuf, [ 3 ], [ 1 ], 0, 'row-major' );
125+
126+
fcn( x, y );
127+
// ybuf => <Float32Array>[ 5.0, 10.0, 15.0 ]
128+
```
129+
130+
The function accepts the following arguments:
131+
132+
- **fcns**: list of [ndarray][@stdlib/ndarray/ctor] functions.
133+
- **types**: one-dimensional list of [ndarray][@stdlib/ndarray/ctor] argument [data types][@stdlib/ndarray/dtypes]. The length of `types` must be the number of [ndarray][@stdlib/ndarray/ctor] functions multiplied by `nin+nout`. If `fcns` is a function, rather than a list, the number of [ndarray][@stdlib/ndarray/ctor] functions is computed as `types.length / (nin+nout)`.
134+
- **data**: [ndarray][@stdlib/ndarray/ctor] function data (e.g., callbacks). If a list, the length of `data` must equal the number of [ndarray][@stdlib/ndarray/ctor] functions. If `null`, a returned [ndarray][@stdlib/ndarray/ctor] function interface does **not** provide a `data` argument to an invoked [ndarray][@stdlib/ndarray/ctor] function.
135+
- **nargs**: total number of [ndarray][@stdlib/ndarray/ctor] function interface arguments.
136+
- **nin**: number of input [ndarrays][@stdlib/ndarray/ctor].
137+
- **nout**: number of output [ndarrays][@stdlib/ndarray/ctor].
62138

63139
</section>
64140

65141
<!-- /.usage -->
66142

67143
<section class="notes">
68144

145+
## Notes
146+
147+
- A returned [ndarray][@stdlib/ndarray/ctor] function interface has the following signature:
148+
149+
```text
150+
f( x, y, ... )
151+
```
152+
153+
where
154+
155+
- **x**: [ndarray][@stdlib/ndarray/ctor].
156+
- **y**: [ndarray][@stdlib/ndarray/ctor].
157+
- **...**: additional [ndarrays][@stdlib/ndarray/ctor].
158+
159+
- The number of [ndarray][@stdlib/ndarray/ctor] function interface parameters is derived from `nargs`, the number of input [ndarrays][@stdlib/ndarray/ctor] is derived from `nin`, and the number of output [ndarrays][@stdlib/ndarray/ctor] is derived from `nout`.
160+
161+
- An [ndarray][@stdlib/ndarray/ctor] function (i.e., a value provided for the `fcns` argument) should have the following signature:
162+
163+
```text
164+
f( arrays[, data] )
165+
```
166+
167+
where
168+
169+
- **arrays**: array containing input and output [ndarrays][@stdlib/ndarray/ctor].
170+
- **data**: [ndarray][@stdlib/ndarray/ctor] function data (e.g., a callback).
171+
172+
- For convenience, a single [ndarray][@stdlib/ndarray/ctor] function may be provided which will be invoked whenever the [ndarray][@stdlib/ndarray/ctor] argument data types match a sequence of types in `types`. Providing a single [ndarray][@stdlib/ndarray/ctor] function is particularly convenient for the case where, regardless of array data types, traversing arrays remains the same, but the [ndarray][@stdlib/ndarray/ctor] function `data` differs (e.g., callbacks which differ based on the array data types). For example, the following
173+
174+
<!-- eslint-disable array-element-newline -->
175+
176+
```javascript
177+
var unary = require( '@stdlib/ndarray-base-unary' );
178+
179+
function foo( x ) {
180+
return x * 10.0;
181+
}
182+
183+
function bar( x ) {
184+
return x * 5.0;
185+
}
186+
187+
var fcns = [
188+
unary,
189+
unary
190+
];
191+
var types = [
192+
'float64', 'float64',
193+
'float32', 'float32'
194+
];
195+
var data = [
196+
foo,
197+
bar
198+
];
199+
200+
var fcn = dispatch( fcns, types, data, 2, 1, 1 );
201+
```
202+
203+
is equivalent to
204+
205+
<!-- eslint-disable array-element-newline -->
206+
207+
```javascript
208+
var unary = require( '@stdlib/ndarray-base-unary' );
209+
210+
function foo( x ) {
211+
return x * 10.0;
212+
}
213+
214+
function bar( x ) {
215+
return x * 5.0;
216+
}
217+
218+
var types = [
219+
'float64', 'float64',
220+
'float32', 'float32'
221+
];
222+
var data = [
223+
foo,
224+
bar
225+
];
226+
227+
var fcn = dispatch( unary, types, data, 2, 1, 1 );
228+
```
229+
69230
</section>
70231
71232
<!-- /.notes -->
@@ -77,7 +238,29 @@ Creates an [ndarray][@stdlib/ndarray/ctor] function interface which accepts a ca
77238
<!-- eslint no-undef: "error" -->
78239
79240
```javascript
80-
var dispatchBy = require( '@stdlib/ndarray-dispatch-by' );
241+
var unary = require( '@stdlib/ndarray-base-unary' );
242+
var ndarray = require( '@stdlib/ndarray-ctor' );
243+
var abs = require( '@stdlib/math-base-special-abs' );
244+
var Float64Array = require( '@stdlib/array-float64' );
245+
var dispatch = require( '@stdlib/ndarray-dispatch' );
246+
247+
var types = [ 'float64', 'float64' ];
248+
249+
var data = [
250+
abs
251+
];
252+
253+
var absolute = dispatch( unary, types, data, 2, 1, 1 );
254+
255+
var xbuf = new Float64Array( [ -1.0, -2.0, -3.0, -4.0, -5.0 ] );
256+
var ybuf = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] );
257+
258+
var x = ndarray( 'float64', xbuf, [ 5 ], [ 1 ], 0, 'row-major' );
259+
var y = ndarray( 'float64', ybuf, [ 5 ], [ 1 ], 0, 'row-major' );
260+
261+
absolute( x, y );
262+
console.log( ybuf );
263+
// => <Float64Array>[ 1.0, 2.0, 3.0, 4.0, 5.0 ]
81264
```
82265

83266
</section>
@@ -88,6 +271,15 @@ var dispatchBy = require( '@stdlib/ndarray-dispatch-by' );
88271

89272
<section class="related">
90273

274+
* * *
275+
276+
## See Also
277+
278+
- <span class="package-name">[`@stdlib/ndarray/array`][@stdlib/ndarray/array]</span><span class="delimiter">: </span><span class="description">multidimensional arrays.</span>
279+
- <span class="package-name">[`@stdlib/ndarray/ctor`][@stdlib/ndarray/ctor]</span><span class="delimiter">: </span><span class="description">multidimensional array constructor.</span>
280+
281+
</section>
282+
91283
<!-- /.related -->
92284

93285
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
@@ -129,8 +321,8 @@ Copyright &copy; 2016-2023. The Stdlib [Authors][stdlib-authors].
129321
[npm-image]: http://img.shields.io/npm/v/@stdlib/ndarray-dispatch-by.svg
130322
[npm-url]: https://npmjs.org/package/@stdlib/ndarray-dispatch-by
131323

132-
[test-image]: https://github.com/stdlib-js/ndarray-dispatch-by/actions/workflows/test.yml/badge.svg?branch=v0.0.1
133-
[test-url]: https://github.com/stdlib-js/ndarray-dispatch-by/actions/workflows/test.yml?query=branch:v0.0.1
324+
[test-image]: https://github.com/stdlib-js/ndarray-dispatch-by/actions/workflows/test.yml/badge.svg?branch=main
325+
[test-url]: https://github.com/stdlib-js/ndarray-dispatch-by/actions/workflows/test.yml?query=branch:main
134326

135327
[coverage-image]: https://img.shields.io/codecov/c/github/stdlib-js/ndarray-dispatch-by/main.svg
136328
[coverage-url]: https://codecov.io/github/stdlib-js/ndarray-dispatch-by?branch=main
@@ -159,9 +351,13 @@ Copyright &copy; 2016-2023. The Stdlib [Authors][stdlib-authors].
159351

160352
[stdlib-license]: https://raw.githubusercontent.com/stdlib-js/ndarray-dispatch-by/main/LICENSE
161353

354+
<!-- <related-links> -->
355+
356+
[@stdlib/ndarray/array]: https://github.com/stdlib-js/ndarray-array
357+
162358
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray-ctor
163359

164-
<!-- <related-links> -->
360+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/ndarray-dtypes
165361

166362
<!-- </related-links> -->
167363

0 commit comments

Comments
 (0)
0