forked from stdlib-js/stdlib
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add support to test whether some "own" and inherited properties of a provided object satisfies a predicate function. Fixes: stdlib-js#825
- Loading branch information
1 parent
0f3838c
commit 15958c9
Showing
10 changed files
with
1,113 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,234 @@ | ||
<!-- | ||
@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. | ||
--> | ||
|
||
# someInBy | ||
|
||
> Test whether an object contains at least `n` properties which pass a test implemented by a predicate function. | ||
<section class="intro"> | ||
|
||
</section> | ||
|
||
<!-- /.intro --> | ||
|
||
<section class="usage"> | ||
|
||
## Usage | ||
|
||
```javascript | ||
var someInBy = require( '@stdlib/utils/some-in-by' ); | ||
``` | ||
|
||
#### someInBy( obj, n, predicate\[, thisArg ] ) | ||
|
||
Tests whether an `obj` contains at least `n` properties which pass a test implemented by a `predicate` function. | ||
|
||
```javascript | ||
function isNegative( value ) { | ||
return ( value < 0 ); | ||
} | ||
|
||
var obj = { | ||
'a': 1, | ||
'b': -2, | ||
'c': 3, | ||
'd': -1 | ||
}; | ||
|
||
var bool = someInBy( obj, 2, isNegative ); | ||
// returns true | ||
``` | ||
|
||
Once the function finds `n` successful properties, 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, | ||
'd': 4 | ||
}; | ||
|
||
var bool = someInBy( obj, 2, isPositive ); | ||
// returns true | ||
``` | ||
|
||
The invoked `function` is provided three arguments: | ||
|
||
- `value`: object property value | ||
- `key`: object property key | ||
- `obj`: 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': -5 | ||
}; | ||
|
||
var context = { | ||
'sum': 0, | ||
'count': 0 | ||
}; | ||
|
||
var bool = someInBy( obj, 1, sum, context ); | ||
// returns true | ||
|
||
var mean = context.sum / context.count; | ||
// returns 0.25 | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.usage --> | ||
|
||
<section class="notes"> | ||
|
||
## Notes | ||
|
||
- If provided an empty `obj`, the function returns `false`. | ||
|
||
```javascript | ||
function alwaysTrue() { | ||
return true; | ||
} | ||
var bool = someInBy( {}, 1, alwaysTrue ); | ||
// returns false | ||
``` | ||
|
||
- The function does **not** skip `undefined` properties. | ||
|
||
```javascript | ||
function log( value, key ) { | ||
console.log( '%s: %s', key, value ); | ||
return ( value < 0 ); | ||
} | ||
|
||
var obj = { | ||
'a': 1, | ||
'b': void 0, | ||
'c': void 0, | ||
'd': 4, | ||
'e': -1 | ||
}; | ||
|
||
var bool = someInBy( obj, 1, log ); | ||
// logs | ||
// a: 1 | ||
// b: void 0 | ||
// c: void 0 | ||
// d: 4 | ||
// e: -1 | ||
``` | ||
|
||
- The function provides limited support for dynamic objects (i.e., objects whose properties change during execution). | ||
|
||
</section> | ||
|
||
<!-- /.notes --> | ||
|
||
<section class="examples"> | ||
|
||
## Examples | ||
|
||
```javascript | ||
var randu = require( '@stdlib/random/base/randu' ); | ||
var someInBy = require( '@stdlib/utils/some-in-by' ); | ||
|
||
function threshold( value ) { | ||
return ( value > 0.95 ); | ||
} | ||
|
||
var bool; | ||
var obj = {}; | ||
var i; | ||
|
||
for ( i = 0; i < 100; i++ ) { | ||
obj[ 'key' + i ] = randu(); | ||
} | ||
|
||
bool = someInBy( obj, 5, threshold ); | ||
// returns <boolean> | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.examples --> | ||
|
||
<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/any-by`][@stdlib/utils/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/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/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/async/some-by`][@stdlib/utils/async/some-by]</span><span class="delimiter">: </span><span class="description">test whether a collection contains `n` elements which pass a test implemented by a predicate function.</span> | ||
- <span class="package-name">[`@stdlib/utils/some-by-right`][@stdlib/utils/some-by-right]</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, iterating from right to left.</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"> | ||
<!-- <related-links> --> | ||
|
||
[@stdlib/utils/any-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/any-by | ||
|
||
[@stdlib/utils/every-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/every-by | ||
|
||
[@stdlib/utils/none-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/none-by | ||
|
||
[@stdlib/utils/async/some-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/async/some-by | ||
|
||
[@stdlib/utils/some-by-right]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/utils/some-by-right | ||
|
||
<!-- </related-links> --> | ||
|
||
</section> | ||
|
||
<!-- /.links --> |
105 changes: 105 additions & 0 deletions
105
lib/node_modules/@stdlib/utils/some-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,105 @@ | ||
/** | ||
* @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 someInBy = 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': NaN, | ||
'e': i + 4, | ||
'f': NaN | ||
}; | ||
bool = someInBy( obj, 2, 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 + '::loop', function benchmark( b ) { | ||
var total; | ||
var count; | ||
var bool; | ||
var obj; | ||
var key; | ||
var i; | ||
|
||
total = 2; | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
obj = { | ||
'a': i, | ||
'b': i + 1, | ||
'c': i + 2, | ||
'd': NaN, | ||
'e': i + 4, | ||
'f': NaN | ||
}; | ||
bool = false; | ||
count = 0; | ||
for ( key in obj ) { | ||
if ( Object.prototype.hasOwnProperty.call( obj, key ) && isnan(obj[ key ] )) { | ||
count += 1; | ||
if ( count === total ) { | ||
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(); | ||
}); |
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,45 @@ | ||
|
||
{{alias}}( obj, n, predicate[, thisArg ] ) | ||
Tests whether an object contains at least `n` properties | ||
(own and inherited) which pass a test | ||
implemented by a predicate function. | ||
|
||
The predicate function is provided three arguments: | ||
|
||
- `value`: object value | ||
- `key`: object key | ||
- `obj`: the input object | ||
|
||
The function immediately returns upon finding `n` successful properties. | ||
|
||
If provided an empty object, the function returns `false`. | ||
|
||
Parameters | ||
---------- | ||
obj: Object | ||
Input object over which to iterate. | ||
|
||
n: number | ||
Minimum number of successful properties. | ||
|
||
predicate: Function | ||
The test function. | ||
|
||
thisArg: any (optional) | ||
Execution context. | ||
|
||
Returns | ||
------- | ||
bool: boolean | ||
The function returns `true` if an object contains at least `n` | ||
successful properties; otherwise, the function returns `false`. | ||
|
||
Examples | ||
-------- | ||
> function negative( v ) { return ( v < 0 ); }; | ||
> var obj = { 'a': 1, 'b': 2, 'c': -3, 'd': 4, 'e': -1 }; | ||
> var bool = {{alias}}( obj, 2, negative ) | ||
true | ||
|
||
See Also | ||
-------- |
Oops, something went wrong.