Applies a function to each array element.
$ npm install compute-array-function
For use in the browser, use browserify.
var arrayfun = require( 'compute-array-function' );
Applies a function
to each array
element. Array arguments may be either generic arrays
, typed arrays
, or a mixture of both.
var arr = [ 1, 2, 3, 4, 5 ];
function add5( val ) {
return val + 5;
}
var out = arrayfun( add5, arr );
// returns [ 6, 7, 8, 9, 10 ]
The function accepts the following options
:
- dtype: output data type. Default:
generic
. - out:
boolean
indicating whether an outputarray
has been provided. Default:false
.
By default, the output array
is a generic
array. To specify a different data type, set the dtype
option (see compute-array-constructors
for a list of acceptable data types).
var out = arrayfun( add5, arr, {
'dtype': 'int8';
});
// return Int8Array( [6,7,8,9,10] )
By default, the function
returns a new array
. To mutate an array
(e.g., when input values can be discarded or when optimizing memory usage), set the out
option to true
to indicate that an output array
has been provided as the first array
argument.
var out = [ 0, 0, 0, 0, 0 ];
arrayfun( add5, out, arr, {
'out': 'true';
});
// returns [ 6, 7, 8, 9, 10 ]
// Works with typed output arrays, as well...
out = new Int8Array( 5 );
arrayfun( add5, out, arr, {
'out': 'true';
});
// returns Int8Array( [6,7,8,9,10] )
===
The main exported function
does not make any assumptions regarding the number of input arrays
. To create a reusable array
function where the number of input arrays
is known, a factory method is provided.
Creates an apply function
to apply a function
to each array
element.
var afun = arrayfun.factory( 2 );
function add( x, y ) {
return x + y;
}
var arr1 = new Array( 5 ),
arr2 = new Array( 5 );
for ( var i = 0; i < 5; i++ ) {
arr1[ i ] = 5;
arr2[ i ] = i + 5;
}
// arr1 = [ 5, 5, 5, 5, 5 ]
// arr2 = [ 5, 6, 7, 8, 9 ]
var out = afun( add, arr1, arr2 );
// returns [ 10, 11, 12, 13, 14 ]
An apply function
may be provided during function
creation.
var aadd = arrayfun.factory( add, 2 );
var out = aadd( arr1, arr2 );
// returns [ 10, 11, 12, 13, 14 ]
The function accepts the following options
:
- dtype: output data type. Default:
generic
.
By default, the output array
is a generic
array. To specify a different data type, set the dtype
option.
var aadd = arrayfun.factory( add, 2, {
'dtype': 'int32';
});
var out = aadd( arr1, arr2 );
// returns Int32Array( [10,11,12,13,14] )
// ...and for all subsequent calls...
out = aadd( arr1, arr2 );
// returns Int32Array( [10,11,12,13,14] )
Note: a factory function
always returns a new array
.
===
To facilitate using array
functions within an application where input arguments are of known types and where memory management occurs externally, a method to create minimal array
functions is provided.
Creates an apply function
to apply a function
to each array
element, where num
is the number of input arrays
excluding the output array
.
var afcn = arrayfun.create( 2 ),
out = new Array( 5 );
out = afcn( add, out, arr1, arr2 );
// returns [ 10, 11, 12, 13, 14 ]
function subtract( x, y ) {
return x - y;
}
out = afcn( subtract, out, arr1, arr2 );
// returns [ 0, -1, -2, -3, -4 ]
An apply function
may be provided during function
creation.
var aadd = arrayfun.create( add, 2 );
var out = aadd( out, arr1, arr2 );
// returns [ 10, 11, 12, 13, 14 ]
===
Lower-level APIs are provided which forgo some of the guarantees of the above APIs, such as input argument validation. While use of the above APIs is encouraged in REPL environments, use of the lower-level interfaces may be warranted when arguments are of a known type or when performance is paramount.
Applies a function
to each array
element.
var arr = [ 0, 0, 0, 0, 0 ]
var out = arrayfun.raw( add5, arr );
// returns [ 5, 5, 5, 5, 5 ]
The function accepts the same options
as the main exported function.
Creates an apply function
to apply a function
to each array
element.
var afun = arrayfun.rawFactory( 2 );
var out = afun( add, arr1, arr2 );
// returns [ 10, 11, 12, 13, 14 ]
The function accepts the same options
as arrayfun.factory()
.
- Both factory methods, as well as the
.create()
method, use dynamic code evaluation. Beware when using these methods in the browser as they may violate your content security policy (CSP).
var arrayfun = require( 'compute-array-function' );
var arr1,
arr2,
out,
i;
arr1 = new Array( 25 );
for ( i = 0; i < arr1.length; i++ ) {
arr1[ i ] = i;
}
arr2 = new Int32Array( 25 );
for ( i = 0; i < arr2.length; i++ ) {
arr2[ i ] = 5;
}
function add( x, y ) {
return x + y;
}
out = arrayfun( add, arr1, arr2 );
console.log( out );
To run the example code from the top-level application directory,
$ node ./examples/index.js
Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
$ make test
All new feature development should have corresponding unit tests to validate correct functionality.
This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:
$ make test-cov
Istanbul creates a ./reports/coverage
directory. To access an HTML version of the report,
$ make view-cov
Copyright © 2015. The Compute.io Authors.