Skip to content

Commit 52e6dc7

Browse files
kgrytekgryte
committed
feat: add array/base/where 
1 parent 1093407 commit 52e6dc7

17 files changed

Lines changed: 3190 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/array/base/where/README.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
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+
# where
22+
23+
> Take elements from either one of two arrays depending on a condition.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var where = require( '@stdlib/array/base/where' );
31+
```
32+
33+
#### where( condition, x, y )
34+
35+
Takes elements from either `x` or `y` depending on a condition.
36+
37+
```javascript
38+
var x = [ 1, 2, 3, 4 ];
39+
var y = [ 5, 6, 7, 8 ];
40+
41+
var condition = [ true, false, true, false ];
42+
43+
var z = where( condition, x, y );
44+
// returns [ 1, 6, 3, 8 ]
45+
```
46+
47+
The function supports the following parameters:
48+
49+
- **condition**: array of values indicating whether to take an element from either `x` or `y`. If a condition element is truthy, the function takes a respective element from `x`; otherwise, the function takes a respective element from `y`. If non-empty, must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with the resolved output array length.
50+
- **x**: first input array. If `condition` is non-empty, must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with the resolved output array length.
51+
- **y**: second input array. If `condition` is non-empty, must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with the resolved output array length.
52+
53+
When all input arrays are non-empty, the function supports broadcasting single-element arrays to the resolved output array length, which is equal to the maximum length of all provided input arrays.
54+
55+
```javascript
56+
var x = [ 1, 2, 3, 4 ];
57+
var y = [ 5 ];
58+
59+
var condition = [ true, false, true, false ];
60+
61+
var z = where( condition, x, y );
62+
// returns [ 1, 5, 3, 5 ]
63+
64+
z = where( condition, y, x );
65+
// returns [ 5, 2, 5, 4 ]
66+
67+
z = where( [ true ], x, y );
68+
// returns [ 1, 2, 3, 4 ]
69+
70+
z = where( [ false ], x, y );
71+
// returns [ 5, 5, 5, 5 ]
72+
73+
z = where( condition, [ 1 ], y );
74+
// returns [ 1, 5, 1, 5 ]
75+
```
76+
77+
If `condition` is an empty array, the function returns an empty array.
78+
79+
```javascript
80+
var x = [ 1, 2, 3, 4 ];
81+
var y = [ 5, 6, 7, 8 ];
82+
83+
var condition = [];
84+
85+
var z = where( condition, x, y );
86+
// returns []
87+
```
88+
89+
#### where.assign( condition, x, y, out, stride, offset )
90+
91+
Takes elements from either `x` or `y` depending on a condition and assigns the values to elements in a provided output array.
92+
93+
```javascript
94+
var x = [ 1, 2, 3, 4 ];
95+
var y = [ 5, 6, 7, 8 ];
96+
97+
var out = [ 0, 0, 0, 0 ];
98+
var condition = [ true, false, true, false ];
99+
100+
var arr = where.assign( condition, x, y, out, 1, 0 );
101+
// returns [ 1, 6, 3, 8 ]
102+
103+
var bool = ( arr === out );
104+
// returns true
105+
```
106+
107+
The function supports the following parameters:
108+
109+
- **condition**: array of values indicating whether to take an element from either `x` or `y`. If a condition element is truthy, the function takes a respective element from `x`; otherwise, the function takes a respective element from `y`. If non-empty, must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with the output array.
110+
- **x**: first input array. If `condition` is non-empty, must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with the output array.
111+
- **y**: second input array. If `condition` is non-empty, must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with the output array.
112+
- **out**: output array.
113+
- **stride**: output array stride.
114+
- **offset**: output array offset.
115+
116+
The function supports broadcasting single-element arrays to the output array length.
117+
118+
```javascript
119+
var x = [ 1, 2, 3, 4 ];
120+
var y = [ 5 ];
121+
122+
var condition = [ true, false, true, false ];
123+
124+
var out = [ 0, 0, 0, 0 ];
125+
var arr = where.assign( condition, x, y, out, 1, 0 );
126+
// returns [ 1, 5, 3, 5 ]
127+
128+
out = [ 0, 0, 0, 0 ];
129+
arr = where.assign( condition, y, x, out, 1, 0 );
130+
// returns [ 5, 2, 5, 4 ]
131+
132+
out = [ 0, 0, 0, 0 ];
133+
arr = where.assign( [ true ], x, y, out, 1, 0 );
134+
// returns [ 1, 2, 3, 4 ]
135+
136+
out = [ 0, 0, 0, 0 ];
137+
arr = where.assign( [ false ], x, y, out, 1, 0 );
138+
// returns [ 5, 5, 5, 5 ]
139+
140+
out = [ 0, 0, 0, 0 ];
141+
arr = where.assign( condition, [ 1 ], y, out, 1, 0 );
142+
// returns [ 1, 5, 1, 5 ]
143+
```
144+
145+
When `condition` is an empty array, the function returns the output array unchanged.
146+
147+
```javascript
148+
var x = [ 1, 2, 3, 4 ];
149+
var y = [ 5, 6, 7, 8 ];
150+
151+
var out = [ 0, 0, 0, 0 ];
152+
var condition = [];
153+
154+
var arr = where.assign( condition, x, y, out, 1, 0 );
155+
// returns [ 0, 0, 0, 0 ]
156+
157+
var bool = ( arr === out );
158+
// returns true
159+
```
160+
161+
</section>
162+
163+
<!-- /.usage -->
164+
165+
<section class="notes">
166+
167+
</section>
168+
169+
<!-- /.notes -->
170+
171+
<section class="examples">
172+
173+
## Examples
174+
175+
<!-- eslint no-undef: "error" -->
176+
177+
```javascript
178+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
179+
var bernoulli = require( '@stdlib/random/array/bernoulli' );
180+
var where = require( '@stdlib/array/base/where' );
181+
182+
var opts = {
183+
'dtype': 'generic'
184+
};
185+
186+
// Generate an array of indicator values:
187+
var condition = bernoulli( 20, 0.9, opts );
188+
console.log( condition );
189+
190+
// Generate an array of random values:
191+
var x = discreteUniform( condition.length, 0, 10, opts );
192+
console.log( x );
193+
194+
// Define an array containing a broadcasted "missing" value:
195+
var y = [ NaN ];
196+
197+
// Return an array with randomly placed missing values:
198+
var z = where( condition, x, y );
199+
console.log( z );
200+
```
201+
202+
</section>
203+
204+
<!-- /.examples -->
205+
206+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
207+
208+
<section class="related">
209+
210+
</section>
211+
212+
<!-- /.related -->
213+
214+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
215+
216+
<section class="links">
217+
218+
[@stdlib/ndarray/base/broadcast-shapes]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/base/broadcast-shapes
219+
220+
</section>
221+
222+
<!-- /.links -->

‎lib/node_modules/@stdlib/array/base/where/benchmark/benchmark.assign.length.js‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
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 bernoulli = require( '@stdlib/random/array/bernoulli' );
26+
var zeros = require( '@stdlib/array/zeros' );
27+
var ones = require( '@stdlib/array/ones' );
28+
var isArray = require( '@stdlib/assert/is-array' );
29+
var pkg = require( './../package.json' ).name;
30+
var where = require( './../lib' );
31+
32+
33+
// VARIABLES //
34+
35+
var opts = {
36+
'dtype': 'generic'
37+
};
38+
39+
40+
// FUNCTIONS //
41+
42+
/**
43+
* Creates a benchmark function.
44+
*
45+
* @private
46+
* @param {PositiveInteger} len - array length
47+
* @returns {Function} benchmark function
48+
*/
49+
function createBenchmark( len ) {
50+
var conditions;
51+
var out;
52+
var x;
53+
var y;
54+
55+
conditions = [
56+
bernoulli( len, 0.5, opts ),
57+
bernoulli( len, 0.5, opts )
58+
];
59+
out = zeros( len, opts.dtype );
60+
x = zeros( len, opts.dtype );
61+
y = ones( len, opts.dtype );
62+
63+
return benchmark;
64+
65+
/**
66+
* Benchmark function.
67+
*
68+
* @private
69+
* @param {Benchmark} b - benchmark instance
70+
*/
71+
function benchmark( b ) {
72+
var v;
73+
var i;
74+
75+
b.tic();
76+
for ( i = 0; i < b.iterations; i++ ) {
77+
v = where.assign( conditions[ i%conditions.length ], x, y, out, 1, 0 ); // eslint-disable-line max-len
78+
if ( typeof v !== 'object' ) {
79+
b.fail( 'should return an array' );
80+
}
81+
}
82+
b.toc();
83+
if ( !isArray( v ) ) {
84+
b.fail( 'should return an array' );
85+
}
86+
b.pass( 'benchmark finished' );
87+
b.end();
88+
}
89+
}
90+
91+
92+
// MAIN //
93+
94+
/**
95+
* Main execution sequence.
96+
*
97+
* @private
98+
*/
99+
function main() {
100+
var len;
101+
var min;
102+
var max;
103+
var f;
104+
var i;
105+
106+
min = 1; // 10^min
107+
max = 6; // 10^max
108+
109+
for ( i = min; i <= max; i++ ) {
110+
len = pow( 10, i );
111+
f = createBenchmark( len );
112+
bench( pkg+':assign:len='+len, f );
113+
}
114+
}
115+
116+
main();

0 commit comments

Comments
 (0)