@stdlib/math-tools-unary NPM

Unary

$NPM version$ $Build Status$ $Coverage Status$

Multiple dispatch for unary mathematical functions.

Installation

npm install @stdlib/math-tools-unary

Usage

var dispatch = require( '@stdlib/math-tools-unary' );

dispatch( table )

Returns a function which dispatches to specified functions based on input argument types.

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:
```
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 data types.
ndarray: strided look-up table for ndarray arguments. Implementation functions must follow strided array ndarray interface argument conventions:
```
fcn( N, x, strideX, offsetX, y, strideY, offsetY )
```
where
- N: number of indexed elements.
- x: input strided array (i.e., underlying input ndarray buffer).
- strideX: index increment for x.
- offsetX: starting index for x.
- y: destination strided array (i.e., underlying output ndarray buffer).
- strideY: index increment for y.
- offsetY: starting index for y.
Supported data types consist of all supported ndarray data types.

Each strided look-up table should be comprised as follows:

[ <dtype>, <fcn>, <dtype>, <fcn>, ... ]

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.

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, array-like object, or number. If provided an ndarray or array-like object, the function performs element-wise computation.

If provided an ndarray, the function returns an ndarray having the same shape and data type as x.

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 <ndarray>

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.

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 <Float64Array>[ 1.0, 2.0 ]

Examples

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 ) );
}

Notice

This package is part of 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, see the main project repository.