-
-
Notifications
You must be signed in to change notification settings - Fork 448
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
PR-URL: #1851 Closes: #819 --------- Signed-off-by: Philipp Burckhardt <[email protected]> Co-authored-by: Philipp Burckhardt <[email protected]> Reviewed-by: Philipp Burckhardt <[email protected]>
- Loading branch information
1 parent
fb6fb04
commit 8c5698c
Showing
9 changed files
with
823 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,206 @@ | ||
<!-- | ||
@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. | ||
--> | ||
|
||
# anyOwnBy | ||
|
||
> Test whether at least one own property of a provided 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 anyOwnBy = require( '@stdlib/utils/any-own-by' ); | ||
``` | ||
|
||
#### anyBy( collection, predicate\[, thisArg ] ) | ||
|
||
Tests whether at least one own property of a provided [`object`][mdn-object] passes a test implemented by a `predicate` function. | ||
|
||
```javascript | ||
function isNegative( value ) { | ||
return ( value < 0 ); | ||
} | ||
|
||
var obj = { | ||
'a': 1, | ||
'b': 2, | ||
'c': 3, | ||
'd': -24, | ||
'e': 12 | ||
}; | ||
|
||
var bool = anyOwnBy( 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, | ||
'd': -24, | ||
'e': 12 | ||
}; | ||
|
||
var bool = anyOwnBy( obj, isPositive ); | ||
// returns true | ||
``` | ||
|
||
The invoked `function` is provided three arguments: | ||
|
||
- `value`: property value | ||
- `key`: property key | ||
- `obj`: input object | ||
|
||
To set the function execution context, provide a `thisArg`. | ||
|
||
```javascript | ||
function verify( value ) { | ||
this.sum += value; | ||
this.count += 1; | ||
return ( value > 0 ); | ||
} | ||
|
||
var obj = { | ||
'a': -1, | ||
'b': -2, | ||
'c': 3, | ||
'd': -14 | ||
}; | ||
|
||
var context = { | ||
'sum': 0, | ||
'count': 0 | ||
}; | ||
|
||
var bool = anyOwnBy( obj, verify, context ); | ||
// returns true | ||
|
||
var mean = context.sum / context.count; | ||
// returns 0 | ||
``` | ||
|
||
</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 | ||
|
||
- If provided an empty object, the function returns `false`. | ||
|
||
```javascript | ||
function verify() { | ||
return true; | ||
} | ||
var bool = anyOwnBy( {}, verify ); | ||
// returns false | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.notes --> | ||
|
||
<!-- Package usage examples. --> | ||
|
||
<section class="examples"> | ||
|
||
## Examples | ||
|
||
<!-- eslint no-undef: "error" --> | ||
|
||
```javascript | ||
var randu = require( '@stdlib/random/base/randu' ); | ||
var anyOwnBy = require( '@stdlib/utils/any-own-by' ); | ||
function threshold( value ) { | ||
return ( value > 0.94 ); | ||
} | ||
var bool; | ||
var obj = {}; | ||
var keys = [ 'a', 'b', 'c', 'd', 'e' ]; | ||
var i; | ||
for ( i = 0; i < keys.length; i++ ) { | ||
obj[ keys[ i ] ] = randu(); | ||
} | ||
bool = anyOwnBy( 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"> | ||
|
||
|
||
</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 --> |
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,42 @@ | ||
{{alias}}( object, predicate[, thisArg ] ) | ||
Tests whether at least one own property of an object passes a | ||
test implemented by a predicate function. | ||
|
||
The predicate function is provided three arguments: | ||
|
||
- `value`: property value | ||
- `index`: property key | ||
- `object`: the input object | ||
|
||
The function immediately returns upon encountering a truthy return | ||
value. | ||
|
||
If provided an empty object, the function returns `false`. | ||
|
||
Parameters | ||
---------- | ||
object: Object | ||
Input object. | ||
|
||
predicate: Function | ||
Test function. | ||
|
||
thisArg: any (optional) | ||
Execution context. | ||
|
||
Returns | ||
------- | ||
bool: boolean | ||
The function returns `true` if the predicate function returns a truthy | ||
value for one own property; otherwise, the function returns `false`. | ||
|
||
Examples | ||
-------- | ||
> function positive( v ) { return ( v > 0 ); }; | ||
> var obj = { 'a': -1, 'b': 2, 'c': -3 }; | ||
> var bool = {{alias}}( obj, positive ) | ||
true | ||
|
||
See Also | ||
-------- | ||
|
101 changes: 101 additions & 0 deletions
101
lib/node_modules/@stdlib/utils/any-own-by/docs/types/index.d.ts
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,101 @@ | ||
/* | ||
* @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. | ||
*/ | ||
|
||
// TypeScript Version: 4.1 | ||
|
||
/// <reference types="@stdlib/types"/> | ||
|
||
/** | ||
* Checks whether an own property of the object passes the test. | ||
* | ||
* @returns boolean indicating whether an own property of the object passes the test | ||
*/ | ||
type Nullary<U> = ( this: U ) => boolean; | ||
|
||
/** | ||
* Checks whether an own property of the object passes the test. | ||
* | ||
* @param value - collection value | ||
* @returns boolean indicating whether an own property of the object passes the test | ||
*/ | ||
type Unary<T, U> = ( this: U, value: T ) => boolean; | ||
|
||
/** | ||
* Checks whether an own property of the object passes the test. | ||
* | ||
* @param value - property value | ||
* @param key - property key | ||
* @returns boolean indicating whether an own property of the object passes the test | ||
*/ | ||
type Binary<T, U> = ( this: U, value: T, key: number ) => boolean; | ||
|
||
/** | ||
* Checks whether an own property of the object passes the test. | ||
* | ||
* @param value - property value | ||
* @param key - property key | ||
* @param object - input object | ||
* @returns boolean indicating whether an own property of the object passes the test | ||
*/ | ||
type Ternary<T, U> = ( this: U, value: T, key: number, object: Object ) => boolean; | ||
|
||
/** | ||
* Checks whether an own property of the object passes the test. | ||
* | ||
* @param value - property value | ||
* @param key - property key | ||
* @param object - input object | ||
* @returns boolean indicating whether an own property of the object passes the tests | ||
*/ | ||
type Predicate<T, U> = Nullary<U> | Unary<T, U> | Binary<T, U> | Ternary<T, U>; | ||
|
||
/** | ||
* Tests whether any property of an object passes a test implemented by a predicate function. | ||
* | ||
* ## Notes | ||
* | ||
* - The predicate function is provided three arguments: | ||
* | ||
* - `value`: property value | ||
* - `key`: property key | ||
* - `object`: the input object | ||
* | ||
* - The function immediately returns upon encountering a truthy return value. | ||
* - If provided an empty object, the function returns `false`. | ||
* | ||
* @param object - input object | ||
* @param predicate - test function | ||
* @param thisArg - execution context | ||
* @returns boolean indicating whether any own property pass a test | ||
* | ||
* @example | ||
* function isPositive( v ) { | ||
* return ( v > 0 ); | ||
* } | ||
* | ||
* var obj = { 'a': -1, 'b': 2, 'c': -3 }; | ||
* | ||
* var bool = anyOwnBy( obj, isPositive ); | ||
* // returns true | ||
*/ | ||
declare function anyOwnBy<T = unknown, U = unknown>( object: Record<string, unknown>, predicate: Predicate<T, U>, thisArg?: ThisParameterType<Predicate<T, U>> ): boolean; | ||
|
||
|
||
// EXPORTS // | ||
|
||
export = anyOwnBy; |
Oops, something went wrong.
8c5698c
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Coverage Report
The above coverage report was generated for the changes in this push.