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,

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.