Find

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,

varfind=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.

vardata=[30,20,50,60,10];functioncondition(val){returnval>20;}varvals=find(data,condition);// returns [ 0, 2, 3 ]

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

vardata=[30,20,50,60,10];varopts={'k': 2,'returns': 'values'};functioncondition(val){returnval>20;}varvals=find(data,opts,condition);// returns [ 30, 50 ]

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

vardata=[30,20,50,60,10];varopts={'k': 2,'returns': 'values'};functioncondition(val){returnval>1000;}varvals=find(data,opts,condition);// returns []

To find the last two values satisfying a search condition,

vardata=[30,20,50,60,10];varopts={'k': -2,'returns': 'values'};functioncondition(val){returnval>20;}varvals=find(data,opts,condition);// returns [ 60, 50 ]

To explicitly specify that only indices are returned,

vardata=[30,20,50,60,10];varopts={'k': -2,'returns': 'indices'};functioncondition(val){returnval>20;}varvals=find(data,opts,condition);// returns [ 3, 2 ]

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

vardata=[30,20,50,60,10];varopts={'k': -2,'returns': '*'};functioncondition(val){returnval>20;}varvals=find(data,opts,condition);// returns [ [3, 60], [2, 50] ]

Examples

varfind=require('compute-find');// Simulate the data...vardata=newArray(100);for(vari=0;i<data.length;i++){data[i]=Math.round(Math.random()*100);}// Find the first 10 values greater than 25...varopts={'k': 10,'returns': '*'};functioncondition(val){returnval>25;}varvals=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.