time-to-botec/js/node_modules/@stdlib/math/tools/unary/README.md

Unary

Multiple dispatch for unary mathematical functions.

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