compute-find

1.0.0 • Public • Published

Find

NPM version Build Status Coverage Status Dependencies

Finds array elements which satisfy a test condition.

A better version than the ECMAScript 6 proposal.

Installation

$ npm install compute-find

For use in the browser, use browserify.

Usage

To use the module,

var find = require( 'compute-find' );

find( arr, [opts,] clbk )

Finds array elements which satisfy a test condition. The function accepts two options: k and returns.

  • k: an integer which limits the number of elements returned and whose sign determines the direction in which to search. If set to a negative integer, the function searches from the last element to the first element.

  • returns: specifies the type of result to return and may be one of three options: indices, values, *.

    • indices: indicates to return the element indices of those elements satisfying the search condition.
    • values: indicates to return the element values of those elements satisfying the search condition.
    • *: indicates to return both the element indices and values of those elements satisfying the search condition. The returned result is an array of arrays, where each sub-array is an index-value pair.

The callback is provided three arguments:

  • element: the current array element
  • index: the current array element's index
  • array: the input array

By default, k is the length of the input array and returns is set to indices.

var data = [ 30, 20, 50, 60, 10 ];
 
function condition( val ) {
    return val > 20;
}
 
var vals = find( data, condition );
// returns [ 0, 2, 3 ]

To limit the number of results and specify that values should be returned,

var data = [ 30, 20, 50, 60, 10 ];
 
var opts = {
    'k': 2,
    'returns': 'values'
};
 
function condition( val ) {
    return val > 20;
}
 
var vals = find( data, opts, condition );
// returns [ 30, 50 ]

If no array elements satisfy the test condition, the function returns an empty array.

var data = [ 30, 20, 50, 60, 10 ];
 
var opts = {
    'k': 2,
    'returns': 'values'
};
 
function condition( val ) {
    return val > 1000;
}
 
var vals = find( data, opts, condition );
// returns []

To find the last two values satisfying a search condition,

var data = [ 30, 20, 50, 60, 10 ];
 
var opts = {
    'k': -2,
    'returns': 'values'
};
 
function condition( val ) {
    return val > 20;
}
 
var vals = find( data, opts, condition );
// returns [ 60, 50 ]

To explicitly specify that only indices are returned,

var data = [ 30, 20, 50, 60, 10 ];
 
var opts = {
    'k': -2,
    'returns': 'indices'
};
 
function condition( val ) {
    return val > 20;
}
 
var vals = find( data, opts, condition );
// returns [ 3, 2 ]

And to return both indices and values as index-value pairs,

var data = [ 30, 20, 50, 60, 10 ];
 
var opts = {
    'k': -2,
    'returns': '*'
};
 
function condition( val ) {
    return val > 20;
}
 
var vals = find( data, opts, condition );
// returns [ [3, 60], [2, 50] ]

Examples

var find = require( 'compute-find' );
 
// Simulate the data...
var data = new Array( 100 );
 
for ( var i = 0; i < data.length; i++ ) {
    data[ i ] = Math.round( Math.random()*100 );
}
 
// Find the first 10 values greater than 25...
var opts = {
    'k': 10,
    'returns': '*'
};
 
function condition( val ) {
    return val > 25;
}
 
var vals = find( data, opts, condition );
 
console.log( vals.join( '\n' ) );

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

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.

Test Coverage

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

License

MIT license.


Copyright

Copyright © 2014. Athan Reines.

Package Sidebar

Install

npm i compute-find

Weekly Downloads

85

Version

1.0.0

License

none

Last publish

Collaborators

  • kgryte