-
-
Notifications
You must be signed in to change notification settings - Fork 447
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
ce5ea47
commit 7338c81
Showing
12 changed files
with
1,095 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,252 @@ | ||
<!-- | ||
@license Apache-2.0 | ||
Copyright (c) 2024 The Stdlib Authors. | ||
Licensed under the Apache License, Version 2.0 (the "License"); | ||
you may not use this file except in compliance with the License. | ||
You may obtain a copy of the License at | ||
http://www.apache.org/licenses/LICENSE-2.0 | ||
Unless required by applicable law or agreed to in writing, software | ||
distributed under the License is distributed on an "AS IS" BASIS, | ||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
See the License for the specific language governing permissions and | ||
limitations under the License. | ||
--> | ||
|
||
# anyInBy | ||
|
||
> Test whether at least one property in an object passes a test implemented by a predicate function. | ||
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. --> | ||
|
||
<section class="intro"> | ||
|
||
</section> | ||
|
||
<!-- /.intro --> | ||
|
||
<!-- Package usage documentation. --> | ||
|
||
<section class="usage"> | ||
|
||
## Usage | ||
|
||
```javascript | ||
var anyInBy = require( '@stdlib/utils/any-in-by' ); | ||
``` | ||
|
||
#### anyInBy( collection, 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`: collection element | ||
- `index`: collection index | ||
- `collection`: input collection | ||
|
||
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 | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.usage --> | ||
|
||
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> | ||
|
||
<section class="notes"> | ||
|
||
## Notes | ||
|
||
- The `obj` object may contain own properties as well as inherited properties from its prototype chain. | ||
|
||
- If provided an empty collection, the function returns `false`. | ||
|
||
```javascript | ||
function alwaysTrue() { | ||
return true; | ||
} | ||
var bool = anyInBy( {}, alwaysTrue ); | ||
// returns false | ||
``` | ||
|
||
- The function differs from [`Array.prototype.some`][mdn-array-some] in the following ways: | ||
|
||
- The function does **not** skip `undefined` elements. | ||
|
||
<!-- eslint-disable no-sparse-arrays, stdlib/doctest-marker --> | ||
|
||
```javascript | ||
function log( value, index ) { | ||
console.log( '%s: %s', index, value ); | ||
return ( value < 0 ); | ||
} | ||
|
||
var arr = [ 1, , , 4, -1 ]; | ||
|
||
var bool = anyInBy( arr, log ); | ||
/* => | ||
0: 1 | ||
1: undefined | ||
2: undefined | ||
3: 4 | ||
4: -1 | ||
*/ | ||
``` | ||
|
||
- The function provides limited support for dynamic collections (i.e., collections whose `length` changes during execution). | ||
|
||
</section> | ||
|
||
|
||
<!-- /.notes --> | ||
|
||
<!-- Package usage examples. --> | ||
|
||
<section class="examples"> | ||
|
||
## Examples | ||
|
||
<!-- eslint no-undef: "error" --> | ||
|
||
```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 <boolean> | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.examples --> | ||
|
||
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> | ||
|
||
<section class="references"> | ||
|
||
</section> | ||
|
||
<!-- /.references --> | ||
|
||
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. --> | ||
|
||
<section class="related"> | ||
|
||
* * * | ||
|
||
## See Also | ||
|
||
- <span class="package-name">[`@stdlib/utils/async/any-by`][@stdlib/utils/async/any-by]</span><span class="delimiter">: </span><span class="description">test whether at least one element in a collection passes a test implemented by a predicate function.</span> | ||
- <span class="package-name">[`@stdlib/utils/any-by-right`][@stdlib/utils/any-by-right]</span><span class="delimiter">: </span><span class="description">test whether at least one element in a collection passes a test implemented by a predicate function, iterating from right to left.</span> | ||
- <span class="package-name">[`@stdlib/utils/every-by`][@stdlib/utils/every-by]</span><span class="delimiter">: </span><span class="description">test whether all elements in a collection pass a test implemented by a predicate function.</span> | ||
- <span class="package-name">[`@stdlib/utils/for-each`][@stdlib/utils/for-each]</span><span class="delimiter">: </span><span class="description">invoke a function for each element in a collection.</span> | ||
- <span class="package-name">[`@stdlib/utils/none-by`][@stdlib/utils/none-by]</span><span class="delimiter">: </span><span class="description">test whether all elements in a collection fail a test implemented by a predicate function.</span> | ||
- <span class="package-name">[`@stdlib/utils/some-by`][@stdlib/utils/some-by]</span><span class="delimiter">: </span><span class="description">test whether a collection contains at least `n` elements which pass a test implemented by a predicate function.</span> | ||
|
||
</section> | ||
|
||
<!-- /.related --> | ||
|
||
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> | ||
|
||
<section class="links"> | ||
|
||
[mdn-array-some]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some | ||
|
||
<!-- <related-links> --> | ||
|
||
[@stdlib/utils/async/any-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/async/any-by | ||
|
||
[@stdlib/utils/any-by-right]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/any-by-right | ||
|
||
[@stdlib/utils/every-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/every-by | ||
|
||
[@stdlib/utils/for-each]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/for-each | ||
|
||
[@stdlib/utils/none-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/none-by | ||
|
||
[@stdlib/utils/some-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/some-by | ||
|
||
<!-- </related-links> --> | ||
|
||
</section> | ||
|
||
<!-- /.links --> |
136 changes: 136 additions & 0 deletions
136
lib/node_modules/@stdlib/utils/any-in-by/benchmark/benchmark.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,136 @@ | ||
/** | ||
* @license Apache-2.0 | ||
* | ||
* Copyright (c) 2024 The Stdlib Authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
'use strict'; | ||
|
||
// MODULES // | ||
|
||
var bench = require( '@stdlib/bench' ); | ||
var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; | ||
var isnan = require( '@stdlib/math/base/assert/is-nan' ); | ||
var pkg = require( './../package.json' ).name; | ||
var anyInBy = require( './../lib' ); | ||
|
||
|
||
// MAIN // | ||
|
||
bench( pkg, function benchmark( b ) { | ||
var bool; | ||
var obj; | ||
var i; | ||
|
||
function predicate( v ) { | ||
return isnan( v ); | ||
} | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
obj = { | ||
'a': i, | ||
'b': i+1, | ||
'c': i+2, | ||
'd': i+3, | ||
'e': i+4, | ||
'f': NaN | ||
}; | ||
bool = anyInBy( obj, predicate ); | ||
if ( typeof bool !== 'boolean' ) { | ||
b.fail( 'should return a boolean' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( !isBoolean( bool ) ) { | ||
b.fail( 'should return a boolean' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); | ||
|
||
bench( pkg+'::built-in', function benchmark( b ) { | ||
var bool; | ||
var keys; | ||
var obj; | ||
var i; | ||
|
||
function predicate( v ) { | ||
return isnan( v ); | ||
} | ||
function testPredicate(key) { | ||
return predicate(obj[key]); | ||
} | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
obj = { | ||
'a': i, | ||
'b': i+1, | ||
'c': i+2, | ||
'd': i+3, | ||
'e': i+4, | ||
'f': NaN | ||
}; | ||
keys = Object.keys( obj ); | ||
bool = keys.some(testPredicate); | ||
if ( typeof bool !== 'boolean' ) { | ||
b.fail( 'should return a boolean' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( !isBoolean( bool ) ) { | ||
b.fail( 'should return a boolean' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); | ||
|
||
bench( pkg+'::loop', function benchmark( b ) { | ||
var bool; | ||
var keys; | ||
var obj; | ||
var i; | ||
var j; | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
obj = { | ||
'a': i, | ||
'b': i+1, | ||
'c': i+2, | ||
'd': i+3, | ||
'e': i+4, | ||
'f': NaN | ||
}; | ||
keys = Object.keys( obj ); | ||
bool = false; | ||
for ( j = 0; j < keys.length; j++ ) { | ||
if ( isnan( obj[ keys[j] ] ) ) { | ||
bool = true; | ||
break; | ||
} | ||
} | ||
if ( typeof bool !== 'boolean' ) { | ||
b.fail( 'should return a boolean' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( !isBoolean( bool ) ) { | ||
b.fail( 'should be a boolean' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); |
2 changes: 2 additions & 0 deletions
2
lib/node_modules/@stdlib/utils/any-in-by/benchmark/julia/REQUIRE
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
julia 1.5 | ||
BenchmarkTools 0.5.0 |
Oops, something went wrong.