README.md (5389B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2018 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 # bifurcateBy 22 23 > Split values into two groups according to a 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 bifurcateBy = require( '@stdlib/utils/bifurcate-by' ); 41 ``` 42 43 #### bifurcateBy( collection, \[options,] predicate ) 44 45 Splits values into two groups according to a `predicate` function, which specifies which group an element in the input `collection` belongs to. If a `predicate` function returns a truthy value, a collection element belongs to the first group; otherwise, a collection element belongs to the second group. 46 47 ```javascript 48 function predicate( v ) { 49 return v[ 0 ] === 'b'; 50 } 51 var arr = [ 'beep', 'boop', 'foo', 'bar' ]; 52 53 var out = bifurcateBy( arr, predicate ); 54 // returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ] 55 ``` 56 57 A `predicate` function is provided two arguments: 58 59 - `value`: collection element 60 - `index`: collection index 61 62 ```javascript 63 function predicate( v, i ) { 64 console.log( '%d: %s', i, v ); 65 return v[ 0 ] === 'b'; 66 } 67 var arr = [ 'beep', 'boop', 'foo', 'bar' ]; 68 69 var out = bifurcateBy( arr, predicate ); 70 // returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ] 71 ``` 72 73 The function accepts the following `options`: 74 75 - `returns`: specifies the output format. If the option equals `'values'`, the function outputs element values. If the option equals `'indices'`, the function outputs element indices. If the option equals `'*'`, the function outputs both element indices and values. Default: `'values'`. 76 - `thisArg`: execution context. 77 78 By default, the function returns element values. To return element indices, set the `returns` option to `'indices'`. 79 80 ```javascript 81 function predicate( v ) { 82 return v[ 0 ] === 'b'; 83 } 84 var arr = [ 'beep', 'boop', 'foo', 'bar' ]; 85 86 var opts = { 87 'returns': 'indices' 88 }; 89 var out = bifurcateBy( arr, opts, predicate ); 90 // returns [ [ 0, 1, 3 ], [ 2 ] ] 91 ``` 92 93 To return index-element pairs, set the `returns` option to `'*'`. 94 95 ```javascript 96 function predicate( v ) { 97 return v[ 0 ] === 'b'; 98 } 99 var arr = [ 'beep', 'boop', 'foo', 'bar' ]; 100 101 var opts = { 102 'returns': '*' 103 }; 104 var out = bifurcateBy( arr, opts, predicate ); 105 // returns [ [ [ 0, 'beep' ], [ 1, 'boop' ], [ 3, 'bar' ] ], [ [ 2, 'foo' ] ] ] 106 ``` 107 108 To set the `predicate` execution context, provide a `thisArg`. 109 110 ```javascript 111 function predicate( v ) { 112 this.count += 1; 113 return v[ 0 ] === 'b'; 114 } 115 var context = { 116 'count': 0 117 }; 118 var opts = { 119 'thisArg': context 120 }; 121 var arr = [ 'beep', 'boop', 'foo', 'bar' ]; 122 123 var out = bifurcateBy( arr, opts, predicate ); 124 // returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ] 125 126 console.log( context.count ); 127 // => 4 128 ``` 129 130 </section> 131 132 <!-- /.usage --> 133 134 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 135 136 <section class="notes"> 137 138 ## Notes 139 140 - A `collection` may be either an [`Array`][mdn-array], [`Typed Array`][mdn-typed-array], or an array-like [`Object`][mdn-object] (excluding `strings` and `functions`). 141 142 </section> 143 144 <!-- /.notes --> 145 146 <!-- Package usage examples. --> 147 148 <section class="examples"> 149 150 ## Examples 151 152 <!-- eslint no-undef: "error" --> 153 154 ```javascript 155 var randu = require( '@stdlib/random/base/randu' ); 156 var floor = require( '@stdlib/math/base/special/floor' ); 157 var bifurcateBy = require( '@stdlib/utils/bifurcate-by' ); 158 159 var vals; 160 var arr; 161 var out; 162 var i; 163 var j; 164 165 vals = [ 'beep', 'boop', 'foo', 'bar', 'woot', 'woot' ]; 166 167 // Generate a random collection... 168 arr = new Array( 100 ); 169 for ( i = 0; i < arr.length; i++ ) { 170 j = floor( randu()*vals.length ); 171 arr[ i ] = vals[ j ]; 172 } 173 174 function predicate( v ) { 175 return v[ 0 ] === 'b'; 176 } 177 178 // Compute the groups: 179 out = bifurcateBy( arr, predicate ); 180 console.log( out ); 181 ``` 182 183 </section> 184 185 <!-- /.examples --> 186 187 <!-- 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. --> 188 189 <section class="references"> 190 191 </section> 192 193 <!-- /.references --> 194 195 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. --> 196 197 <section class="links"> 198 199 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 200 201 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 202 203 [mdn-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object 204 205 </section> 206 207 <!-- /.links -->