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.
PR-URL: stdlib-js#1437 Closes: stdlib-js#821 --------- Signed-off-by: Pranavchiku [email protected] Signed-off-by: Rutam <[email protected]> Signed-off-by: Philipp Burckhardt <[email protected]> Co-authored-by: Pranav <[email protected]> Co-authored-by: Philipp Burckhardt <[email protected]> Reviewed-by: Pranav <[email protected]> Reviewed-by: Philipp Burckhardt <[email protected]>
- Loading branch information
1 parent
24b0f19
commit 80fdd70
Showing
10 changed files
with
1,057 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,238 @@ | ||
<!-- | ||
@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. | ||
--> | ||
|
||
# someOwnBy | ||
|
||
> Test whether an object contains at least `n` own properties which pass 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 someOwnBy = require( '@stdlib/utils/some-own-by' ); | ||
``` | ||
|
||
#### someOwnBy( obj, n, predicate\[, thisArg ] ) | ||
|
||
Tests whether an `object` contains at least `n` own 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 = someOwnBy( 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 = someOwnBy( 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 = someOwnBy( obj, 1, sum, context ); | ||
// returns true | ||
|
||
var mean = context.sum / context.count; | ||
// returns 0.25 | ||
``` | ||
|
||
</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 | ||
|
||
- An [`Object`][mdn-object] refers to a JavaScript object, which is a collection of properties. Each property is an association between a key (or name) and a value. The key can be a string or a symbol, and the value can be any JavaScript value, including functions and other objects | ||
|
||
- If provided an empty `object`, the function returns `false`. | ||
|
||
```javascript | ||
function alwaysTrue() { | ||
return true; | ||
} | ||
var bool = someOwnBy( {}, 1, alwaysTrue ); | ||
// returns false | ||
``` | ||
|
||
- The function does **not** skip `undefined` elements. | ||
|
||
<!-- eslint-disable no-sparse-arrays, stdlib/doctest-marker --> | ||
|
||
```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 = someOwnBy( obj, 1, log ); | ||
/* => | ||
a: 1 | ||
b: void 0 | ||
c: void 0 | ||
d: 4 | ||
e: -1 | ||
*/ | ||
``` | ||
|
||
- The function provides limited support for dynamic objects (i.e., objects 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 someOwnBy = require( '@stdlib/utils/some-own-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 = someOwnBy( obj, 5, 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 | ||
|
||
</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-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object | ||
|
||
<!-- <related-links> --> | ||
|
||
<!-- </related-links> --> | ||
|
||
</section> | ||
|
||
<!-- /.links --> |
109 changes: 109 additions & 0 deletions
109
lib/node_modules/@stdlib/utils/some-own-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,109 @@ | ||
/** | ||
* @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 someOwnBy = 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 = someOwnBy( 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 keys; | ||
var obj; | ||
var key; | ||
var i; | ||
var j; | ||
|
||
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; | ||
keys = Object.keys( obj ); | ||
for ( j = 0; j < keys.length; j++ ) { | ||
key = keys[ j ]; | ||
if ( 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 some `own` properties of a provided object | ||
satisfy a predicate function for at least `n` properties. | ||
|
||
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 | ||
Test function. | ||
|
||
thisArg: any (optional) | ||
Execution context. | ||
|
||
Returns | ||
------- | ||
bool: boolean | ||
The function returns `true` if an object's own properties satisfy a | ||
predicate for at least `n` 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.