# Unary
> Multiple dispatch for unary mathematical functions.
## Usage
```javascript
var dispatch = require( '@stdlib/math/tools/unary' );
```
#### dispatch( table )
Returns a function which dispatches to specified functions based on input argument types.
```javascript
var nabs = require( '@stdlib/math/base/special/abs' );
var dabs = require( '@stdlib/math/strided/special/dabs' );
var sabs = require( '@stdlib/math/strided/special/sabs' );
var gabs = require( '@stdlib/math/strided/special/abs' );
var table = {
'scalar': [
'number', nabs
],
'array': [
'float64', dabs,
'float32', sabs,
'generic', gabs
],
'ndarray': [
'float64', dabs.ndarray,
'float32', sabs.ndarray,
'generic', gabs.ndarray
]
};
var abs = dispatch( table );
```
The function accepts the following arguments:
- **table**: resolution table object which maps input argument types to corresponding implementations.
A `table` resolution object may contain one or more of the following fields:
- **scalar**: strided look-up table for scalar arguments. Implementation functions must accept a single input argument: a scalar value. Supported data types: `'number'` and `'complex'`.
- **array**: strided look-up table for array-like object arguments. Implementation functions must follow strided array interface argument conventions:
```text
fcn( N, x, strideX, y, strideY )
```
where
- **N**: number of indexed elements.
- **x**: input strided array.
- **strideX**: index increment for `x`.
- **y**: destination strided array.
- **strideY**: index increment for `y`.
Supported array data types consist of all supported [ndarray][@stdlib/ndarray/dtypes] data types.
- **ndarray**: strided look-up table for [`ndarray`][@stdlib/ndarray/ctor] arguments. Implementation functions must follow strided array ndarray interface argument conventions:
```text
fcn( N, x, strideX, offsetX, y, strideY, offsetY )
```
where
- **N**: number of indexed elements.
- **x**: input strided array (i.e., underlying input [`ndarray`][@stdlib/ndarray/ctor] buffer).
- **strideX**: index increment for `x`.
- **offsetX**: starting index for `x`.
- **y**: destination strided array (i.e., underlying output [`ndarray`][@stdlib/ndarray/ctor] buffer).
- **strideY**: index increment for `y`.
- **offsetY**: starting index for `y`.
Supported data types consist of all supported [ndarray][@stdlib/ndarray/dtypes] data types.
Each strided look-up table should be comprised as follows:
```text
[ , , , , ... ]
```
If an argument's data type is **not** found in the argument's corresponding look-up table and if a `'generic'` data type is present in that same table, the returned dispatch function will resolve the "generic" implementation. In other words, an implementation associated with a `'generic'` data type will be treated as the default implementation.
If unable to resolve an implementation for a provided argument data type, the returned function throws an error.
* * *
#### dispatcher( x )
Dispatches to an underlying implementation based the data type of `x`.
```javascript
var nabs = require( '@stdlib/math/base/special/abs' );
var dabs = require( '@stdlib/math/strided/special/dabs' );
var sabs = require( '@stdlib/math/strided/special/sabs' );
var gabs = require( '@stdlib/math/strided/special/abs' );
var table = {
'scalar': [
'number', nabs
],
'array': [
'float64', dabs,
'float32', sabs,
'generic', gabs
],
'ndarray': [
'float64', dabs.ndarray,
'float32', sabs.ndarray,
'generic', gabs.ndarray
]
};
var abs = dispatch( table );
var y = abs( -1.0 );
// returns 1.0
```
The returned dispatch function accepts the following arguments:
- **x**: input [`ndarray`][@stdlib/ndarray/ctor], array-like object, or number. If provided an [`ndarray`][@stdlib/ndarray/ctor] or array-like object, the function performs element-wise computation.
If provided an [`ndarray`][@stdlib/ndarray/ctor], the function returns an [`ndarray`][@stdlib/ndarray/ctor] having the same shape and data type as `x`.
```javascript
var dabs = require( '@stdlib/math/strided/special/dabs' );
var sabs = require( '@stdlib/math/strided/special/sabs' );
var gabs = require( '@stdlib/math/strided/special/abs' );
var array = require( '@stdlib/ndarray/array' );
var table = {
'ndarray': [
'float64', dabs.ndarray,
'float32', sabs.ndarray,
'generic', gabs.ndarray
]
};
var abs = dispatch( table );
var x = array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] ); // 2x2
var y = abs( x );
// returns
var v = y.get( 0, 1 );
// returns 2.0
```
If provided an array-like object, the function returns an array-like object having the same length and data type as `x`.
```javascript
var dabs = require( '@stdlib/math/strided/special/dabs' );
var sabs = require( '@stdlib/math/strided/special/sabs' );
var gabs = require( '@stdlib/math/strided/special/abs' );
var Float64Array = require( '@stdlib/array/float64' );
var table = {
'array': [
'float64', dabs,
'float32', sabs,
'generic', gabs
]
};
var abs = dispatch( table );
var x = new Float64Array( [ -1.0, -2.0 ] );
var y = abs( x );
// returns [ 1.0, 2.0 ]
```
* * *
## Examples
```javascript
var nabs = require( '@stdlib/math/base/special/abs' );
var dabs = require( '@stdlib/math/strided/special/dabs' );
var sabs = require( '@stdlib/math/strided/special/sabs' );
var gabs = require( '@stdlib/math/strided/special/abs' );
var Float64Array = require( '@stdlib/array/float64' );
var array = require( '@stdlib/ndarray/array' );
var ind2sub = require( '@stdlib/ndarray/ind2sub' );
var dispatch = require( '@stdlib/math/tools/unary' );
var table;
var sub;
var abs;
var sh;
var x;
var y;
var i;
// Define a table for resolving unary functions based on argument data types:
table = {
'scalar': [
'number', nabs
],
'array': [
'float64', dabs,
'float32', sabs,
'generic', gabs
],
'ndarray': [
'float64', dabs.ndarray,
'float32', sabs.ndarray,
'generic', gabs.ndarray
]
};
// Create a function which dispatches based on argument data types:
abs = dispatch( table );
// Provide a number...
y = abs( -1.0 );
console.log( 'x = %d => abs(x) = %d', -1.0, y );
// Provide an array-like object...
x = new Float64Array( [ -1.0, -2.0, -3.0 ] );
y = abs( x );
for ( i = 0; i < x.length; i++ ) {
console.log( 'x_%d = %d => abs(x_%d) = %d', i, x[ i ], i, y[ i ] );
}
// Provide an ndarray...
x = array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] );
sh = x.shape;
y = abs( x );
for ( i = 0; i < x.length; i++ ) {
sub = ind2sub( sh, i );
console.log( 'x_%d%d = %d => abs(x_%d%d) = %d', sub[ 0 ], sub[ 1 ], x.iget( i ), sub[ 0 ], sub[ 1 ], y.iget( i ) );
}
```
[@stdlib/ndarray/ctor]: https://www.npmjs.com/package/@stdlib/ndarray-ctor
[@stdlib/ndarray/dtypes]: https://www.npmjs.com/package/@stdlib/ndarray-dtypes