diff --git a/lib/node_modules/@stdlib/utils/any-in-by/README.md b/lib/node_modules/@stdlib/utils/any-in-by/README.md new file mode 100644 index 00000000000..a774899a3be --- /dev/null +++ b/lib/node_modules/@stdlib/utils/any-in-by/README.md @@ -0,0 +1,185 @@ + + +# anyInBy + +> Test whether at least one property in an object passes a test implemented by a predicate function. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var anyInBy = require( '@stdlib/utils/any-in-by' ); +``` + +#### anyInBy( object, predicate\[, thisArg ] ) + +Tests whether at least one property in an `object` passes a test implemented by a `predicate` function. + +```javascript +function isNegative( value ) { + return ( value < 0 ); +} + +var obj = { + 'a': 1, + 'b': 2, + 'c': -1 +}; + +var bool = anyInBy( obj, isNegative ); +// returns true +``` + +If a `predicate` function returns a truthy value, the function **immediately** returns `true`. + +```javascript +function isPositive( value ) { + if ( value < 0 ) { + throw new Error( 'should never reach this line' ); + } + return ( value > 0 ); +} + +var obj = { + 'a': 1, + 'b': -2, + 'c': 3 +}; + +var bool = anyInBy( obj, isPositive ); +// returns true +``` + +The invoked `function` is provided three arguments: + +- `value`: property value +- `key`: property key +- `object`: input object + +To set the function execution context, provide a `thisArg`. + +```javascript +function sum( value ) { + this.sum += value; + this.count += 1; + return ( value < 0 ); +} + +var obj = { + 'a': 1, + 'b': 2, + 'c': 3, + 'd': -4 +}; + +var context = { + 'sum': 0, + 'count': 0 +}; + +var bool = anyInBy( obj, sum, context ); +// returns true + +var mean = context.sum / context.count; +// returns 0.5 +``` + +
+ + + + + +
+ +## Notes + +- The `obj` object may contain own properties as well as inherited properties from its prototype chain. + +- If provided an empty object, the function returns `false`. + + ```javascript + function alwaysTrue() { + return true; + } + var bool = anyInBy( {}, alwaysTrue ); + // returns false + ``` + +
+ + + + + + +
+ +## Examples + + + +```javascript +var randu = require( '@stdlib/random/base/randu' ); +var anyInBy = require( '@stdlib/utils/any-in-by' ); + +function threshold( value ) { + return ( value > 0.95 ); +} + +var bool; +var obj = {}; +var i; + +for ( i = 0; i < 100; i++ ) { + obj[i] = randu(); +} + +bool = anyInBy( obj, threshold ); +// returns +``` + +
+ + + + + +
+ +
+ + + + + +