@stdlib/math-tools-unary
TypeScript icon, indicating that this package has built-in type declarations

0.2.1 • Public • Published
About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please consider financially supporting stdlib. We greatly appreciate your continued support!

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.

Community

Chat


License

See LICENSE.

Copyright

Copyright © 2016-2024. The Stdlib Authors.

Package Sidebar

Install

npm i @stdlib/math-tools-unary

Homepage

stdlib.io

Weekly Downloads

32

Version

0.2.1

License

Apache-2.0

Unpacked Size

87.9 kB

Total Files

18

Last publish

Collaborators

  • stdlib-bot
  • kgryte
  • planeshifter
  • rreusser