Skip to content

Commit b11d53b

Browse files
kgrytekgryte
committed
feat: add array/base/bifurcate-indices-by 
1 parent 8695944 commit b11d53b

File tree

10 files changed

+883
-0
lines changed

10 files changed

+883
-0
lines changed

‎lib/node_modules/@stdlib/array/base/bifurcate-indices-by/README.md

+157
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2023 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+
# bifurcateIndicesBy
22+
23+
> Split element indices into two groups according to an predicate function.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var bifurcateIndicesBy = require( '@stdlib/array/base/bifurcate-indices-by' );
41+
```
42+
43+
#### bifurcateIndicesBy( x, predicate\[, thisArg] )
44+
45+
Splits element indices into two groups according to an predicate function.
46+
47+
```javascript
48+
function predicate( v ) {
49+
return v[ 0 ] === 'b';
50+
}
51+
52+
var x = [ 'beep', 'boop', 'foo', 'bar' ];
53+
54+
var out = bifurcateIndicesBy( x, predicate );
55+
// returns [ [ 0, 1, 3 ], [ 2 ] ]
56+
```
57+
58+
An `predicate` function is provided the following arguments:
59+
60+
- **value**: current array element.
61+
- **index**: current array element index.
62+
- **arr**: input array.
63+
64+
To set the `predicate` function execution context, provide a `thisArg`.
65+
66+
```javascript
67+
function predicate( v ) {
68+
this.count += 1;
69+
return v[ 0 ] === 'b';
70+
}
71+
72+
var x = [ 'beep', 'boop', 'foo', 'bar' ];
73+
74+
var context = {
75+
'count': 0
76+
};
77+
var out = bifurcateIndicesBy( x, predicate, context );
78+
// returns [ [ 0, 1, 3 ], [ 2 ] ]
79+
80+
var cnt = context.count;
81+
// returns 4
82+
```
83+
84+
</section>
85+
86+
<!-- /.usage -->
87+
88+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
89+
90+
<section class="notes">
91+
92+
</section>
93+
94+
<!-- /.notes -->
95+
96+
<!-- Package usage examples. -->
97+
98+
<section class="examples">
99+
100+
## Examples
101+
102+
<!-- eslint no-undef: "error" -->
103+
104+
```javascript
105+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
106+
var take = require( '@stdlib/array/base/take' );
107+
var bifurcateIndicesBy = require( '@stdlib/array/base/bifurcate-indices-by' );
108+
109+
function predicate( v ) {
110+
// Use the first letter of each element to define groups:
111+
return v[ 0 ] === 'b';
112+
}
113+
114+
// Define an initial array of values:
115+
var values = [ 'beep', 'boop', 'foo', 'bar', 'woot', 'woot' ];
116+
117+
// Sample from the initial array to generate a random collection:
118+
var indices = discreteUniform( 100, 0, values.length-1, {
119+
'dtype': 'generic'
120+
});
121+
var x = take( values, indices );
122+
// returns [...]
123+
124+
// Split the values:
125+
var out = bifurcateIndicesBy( x, predicate );
126+
// returns [...]
127+
128+
console.log( out );
129+
```
130+
131+
</section>
132+
133+
<!-- /.examples -->
134+
135+
<!-- 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. -->
136+
137+
<section class="references">
138+
139+
</section>
140+
141+
<!-- /.references -->
142+
143+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
144+
145+
<section class="related">
146+
147+
</section>
148+
149+
<!-- /.related -->
150+
151+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
152+
153+
<section class="links">
154+
155+
</section>
156+
157+
<!-- /.links -->

‎lib/node_modules/@stdlib/array/base/bifurcate-indices-by/benchmark/benchmark.length.js

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2023 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 isArrayArray = require( '@stdlib/assert/is-array-array' );
26+
var zeroTo = require( '@stdlib/array/base/zero-to' );
27+
var pkg = require( './../package.json' ).name;
28+
var bifurcateIndicesBy = require( './../lib' );
29+
30+
31+
// FUNCTIONS //
32+
33+
/**
34+
* Creates a benchmark function.
35+
*
36+
* @private
37+
* @param {PositiveInteger} len - array length
38+
* @returns {Function} benchmark function
39+
*/
40+
function createBenchmark( len ) {
41+
var x = zeroTo( len );
42+
return benchmark;
43+
44+
/**
45+
* Benchmark function.
46+
*
47+
* @private
48+
* @param {Benchmark} b - benchmark instance
49+
*/
50+
function benchmark( b ) {
51+
var out;
52+
var i;
53+
54+
b.tic();
55+
for ( i = 0; i < b.iterations; i++ ) {
56+
out = bifurcateIndicesBy( x, predicate );
57+
if ( typeof out !== 'object' ) {
58+
b.fail( 'should return an array of arrays' );
59+
}
60+
}
61+
b.toc();
62+
if ( !isArrayArray( out ) ) {
63+
b.fail( 'should return an array of arrays' );
64+
}
65+
b.pass( 'benchmark finished' );
66+
b.end();
67+
}
68+
69+
/**
70+
* Predicate function.
71+
*
72+
* @private
73+
* @param {*} value - current array element
74+
* @param {NonNegativeInteger} index - current array element index
75+
* @param {Collection} arr - input array
76+
* @returns {boolean} predicate value
77+
*/
78+
function predicate( value, index ) {
79+
return ( index < len/2 );
80+
}
81+
}
82+
83+
84+
// MAIN //
85+
86+
/**
87+
* Main execution sequence.
88+
*
89+
* @private
90+
*/
91+
function main() {
92+
var len;
93+
var min;
94+
var max;
95+
var f;
96+
var i;
97+
98+
min = 1; // 10^min
99+
max = 6; // 10^max
100+
101+
for ( i = min; i <= max; i++ ) {
102+
len = pow( 10, i );
103+
104+
f = createBenchmark( len );
105+
bench( pkg+':len='+len, f );
106+
}
107+
}
108+
109+
main();

‎lib/node_modules/@stdlib/array/base/bifurcate-indices-by/docs/repl.txt

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
2+
{{alias}}( x, predicate[, thisArg] )
3+
Splits element indices into two groups according to an predicate function.
4+
5+
When invoked, the predicate function is provided the following arguments:
6+
7+
- value: current array element.
8+
- index: current array element index.
9+
- arr: input array.
10+
11+
If a predicate function returns a truthy value, an array value is placed in
12+
the first group; otherwise, an array value is placed in the second group.
13+
14+
If provided an empty array, the function returns an empty object.
15+
16+
Parameters
17+
----------
18+
x: ArrayLike
19+
Input array.
20+
21+
predicate: Function
22+
Predicate function specifying which group an element in the input array
23+
belongs to.
24+
25+
thisArg: any (optional)
26+
Predicate function execution context.
27+
28+
Returns
29+
-------
30+
out: Object
31+
Split results.
32+
33+
Examples
34+
--------
35+
> function fcn( v ) { return v[ 0 ] === 'b'; };
36+
> var x = [ 'beep', 'boop', 'foo', 'bar' ];
37+
> var out = {{alias}}( x, fcn )
38+
[ [ 0, 1, 3 ], [ 2 ] ]
39+
40+
See Also
41+
--------
42+

0 commit comments

Comments
 (0)