Skip to content

Commit 8b7f927

Browse files
feat: add array/base/mskreject-map
PR-URL: #1451 Closes: #1323 --------- Co-authored-by: Philipp Burckhardt <pburckhardt@outlook.com> Reviewed-by: Philipp Burckhardt <pburckhardt@outlook.com>
1 parent d583804 commit 8b7f927

File tree

15 files changed

+1676
-0
lines changed

15 files changed

+1676
-0
lines changed
Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2024 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# mskrejectMap
22+
23+
> Apply a mask to a provided input array and map the unmasked values according to a callback function.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var mskrejectMap = require( '@stdlib/array/base/mskreject-map' );
31+
```
32+
33+
#### mskrejectMap( x, mask, clbk\[, thisArg ] )
34+
35+
Returns a new array by applying a mask and mapping the unmasked values according to a callback function.
36+
37+
```javascript
38+
var x = [ 1, 2, 3, 4 ];
39+
40+
function clbk( val ) {
41+
return val * 2;
42+
}
43+
44+
var y = mskrejectMap( x, [ 0, 1, 0, 1 ], clbk );
45+
// returns [ 2, 6 ]
46+
```
47+
48+
The function supports the following parameters:
49+
50+
- **x**: input array.
51+
- **mask**: mask array.
52+
- **clbk**: function to apply.
53+
- **thisArg**: applied function execution context (_optional_).
54+
55+
The `clbk` function is provided three arguments:
56+
57+
- **value**: current unmasked array element.
58+
- **index**: current unmasked array element index.
59+
- **arr**: input array.
60+
61+
To set the `clbk` function execution context, provide a `thisArg`.
62+
63+
```javascript
64+
var x = [ 1, 2, 3, 4 ];
65+
66+
var mask = [ 0, 1, 0, 1 ];
67+
68+
var increase = 3;
69+
70+
function clbk( value ) {
71+
return value + this;
72+
}
73+
74+
var out = mskrejectMap( x, mask, clbk, increase );
75+
// returns [ 4, 6 ]
76+
```
77+
78+
The function **always** returns a new "generic" array.
79+
80+
#### mskrejectMap.assign( x, mask, out, stride, offset, clbk\[, thisArg ] )
81+
82+
Applies a mask to a provided input array, maps the unmasked values according to a callback function, and assigns to elements in a provided output array.
83+
84+
```javascript
85+
var x = [ 1, 2, 3, 4 ];
86+
87+
var mask = [ 1, 0, 1, 0 ];
88+
89+
var out = [ 0, 0, 0, 0 ];
90+
91+
function clbk( val ) {
92+
return val * 2;
93+
}
94+
95+
var arr = mskrejectMap.assign( x, mask, out, -2, out.length-1, clbk );
96+
// returns [ 0, 8, 0, 4 ]
97+
98+
var bool = ( arr === out );
99+
// returns true
100+
```
101+
102+
The function supports the following parameters:
103+
104+
- **x**: input array.
105+
- **mask**: mask array.
106+
- **out**: output array.
107+
- **stride**: output array stride.
108+
- **offset**: output array offset.
109+
- **clbk**: function to apply.
110+
- **thisArg**: applied function execution context (_optional_).
111+
112+
</section>
113+
114+
<!-- /.usage -->
115+
116+
<section class="notes">
117+
118+
## Notes
119+
120+
- If a `mask` array element is falsy, the corresponding element in `x` is **mapped** in the output array; otherwise, the corresponding element in `x` is "masked" and thus **excluded** from the output array.
121+
122+
</section>
123+
124+
<!-- /.notes -->
125+
126+
<section class="examples">
127+
128+
## Examples
129+
130+
<!-- eslint no-undef: "error" -->
131+
132+
```javascript
133+
var zeroTo = require( '@stdlib/array/base/zero-to' );
134+
var bernoulli = require( '@stdlib/random/array/bernoulli' );
135+
var mskrejectMap = require( '@stdlib/array/base/mskreject-map' );
136+
137+
// Generate a linearly spaced array:
138+
var x = zeroTo( 20 );
139+
console.log( x );
140+
141+
// Generate a random mask:
142+
var mask = bernoulli( x.length, 0.5, {
143+
'dtype': 'generic'
144+
});
145+
console.log( mask );
146+
147+
function clbk( val ) {
148+
return val * 2;
149+
}
150+
151+
// Filter an array using the mask:
152+
var y = mskrejectMap( x, mask, clbk );
153+
console.log( y );
154+
```
155+
156+
</section>
157+
158+
<!-- /.examples -->
159+
160+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
161+
162+
<section class="related">
163+
164+
</section>
165+
166+
<!-- /.related -->
167+
168+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
169+
170+
<section class="links">
171+
172+
</section>
173+
174+
<!-- /.links -->
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2024 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var pow = require( '@stdlib/math/base/special/pow' );
25+
var zeroTo = require( '@stdlib/array/base/zero-to' );
26+
var zeros = require( '@stdlib/array/zeros' );
27+
var isArray = require( '@stdlib/assert/is-array' );
28+
var isnan = require( '@stdlib/assert/is-nan' ).isPrimitive;
29+
var pkg = require( './../package.json' ).name;
30+
var mskrejectMap = require( './../lib' );
31+
32+
33+
// FUNCTIONS //
34+
35+
/**
36+
* Creates a benchmark function.
37+
*
38+
* @private
39+
* @param {PositiveInteger} len - array length
40+
* @returns {Function} benchmark function
41+
*/
42+
function createBenchmark( len ) {
43+
var mask;
44+
var out;
45+
var x;
46+
47+
x = zeroTo( len, 'generic' );
48+
mask = zeros( len, 'generic' );
49+
out = zeros( len, 'generic' );
50+
51+
return benchmark;
52+
53+
/**
54+
* Benchmark function.
55+
*
56+
* @private
57+
* @param {Benchmark} b - benchmark instance
58+
*/
59+
function benchmark( b ) {
60+
var v;
61+
var i;
62+
63+
b.tic();
64+
for ( i = 0; i < b.iterations; i++ ) {
65+
v = mskrejectMap.assign( x, mask, out, 1, 0, function clbk( val ) {
66+
return val * 2;
67+
} );
68+
if ( typeof v !== 'object' ) {
69+
b.fail( 'should return an array' );
70+
}
71+
}
72+
b.toc();
73+
if ( !isArray( v ) || isnan( v[ i%len ] ) ) {
74+
b.fail( 'should return an array' );
75+
}
76+
b.pass( 'benchmark finished' );
77+
b.end();
78+
}
79+
}
80+
81+
82+
// MAIN //
83+
84+
/**
85+
* Main execution sequence.
86+
*
87+
* @private
88+
*/
89+
function main() {
90+
var len;
91+
var min;
92+
var max;
93+
var f;
94+
var i;
95+
96+
min = 1; // 10^min
97+
max = 6; // 10^max
98+
99+
for ( i = min; i <= max; i++ ) {
100+
len = pow( 10, i );
101+
f = createBenchmark( len );
102+
bench( pkg+':assign:len='+len, f );
103+
}
104+
}
105+
106+
main();
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2024 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var isArray = require( '@stdlib/assert/is-array' );
25+
var zeroTo = require( '@stdlib/array/base/zero-to' );
26+
var zeros = require( '@stdlib/array/base/zeros' );
27+
var pkg = require( './../package.json' ).name;
28+
var mskrejectMap = require( './../lib' );
29+
30+
31+
// MAIN //
32+
33+
bench( pkg+'::copy:len=100', function benchmark( b ) {
34+
var x;
35+
var y;
36+
var i;
37+
var v;
38+
39+
x = zeroTo( 100 );
40+
y = zeros( x.length );
41+
42+
b.tic();
43+
for ( i = 0; i < b.iterations; i++ ) {
44+
v = mskrejectMap( x, y, function clbk( val ) {
45+
return val * 2;
46+
} );
47+
if ( typeof v !== 'object' ) {
48+
b.fail( 'should return an array' );
49+
}
50+
}
51+
b.toc();
52+
if ( !isArray( v ) ) {
53+
b.fail( 'should return an array' );
54+
}
55+
b.pass( 'benchmark finished' );
56+
b.end();
57+
});

0 commit comments

Comments
 (0)