time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (4517B)

      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 # bifurcate
     22 
     23 > Split values into two groups.
     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 bifurcate = require( '@stdlib/utils/bifurcate' );
     41 ```
     42 
     43 #### bifurcate( collection, \[options,] filter )
     44 
     45 Splits values into two groups. If an element in `filter` is truthy, the corresponding element in `collection` belongs to the first group; otherwise, the `collection` element belongs to the second group.
     46 
     47 ```javascript
     48 var arr = [ 'beep', 'boop', 'foo', 'bar' ];
     49 var filter = [ true, true, false, true ];
     50 
     51 var out = bifurcate( arr, filter );
     52 // returns [ [ 'beep', 'boop', 'bar' ], [ 'foo' ] ]
     53 ```
     54 
     55 The function accepts the following `options`:
     56 
     57 -   `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'`.
     58 
     59 By default, the function returns element values. To return element indices, set the `returns` option to `'indices'`.
     60 
     61 ```javascript
     62 var arr = [ 'beep', 'boop', 'foo', 'bar' ];
     63 var filter = [ true, true, false, true ];
     64 
     65 var opts = {
     66     'returns': 'indices'
     67 };
     68 var out = bifurcate( arr, opts, filter );
     69 // returns [ [ 0, 1, 3 ], [ 2 ] ]
     70 ```
     71 
     72 To return index-element pairs, set the `returns` option to `'*'`.
     73 
     74 ```javascript
     75 var arr = [ 'beep', 'boop', 'foo', 'bar' ];
     76 var filter = [ true, true, false, true ];
     77 
     78 var opts = {
     79     'returns': '*'
     80 };
     81 var out = bifurcate( arr, opts, filter );
     82 // returns [ [ [ 0, 'beep' ], [ 1, 'boop' ], [ 3, 'bar' ] ], [ [ 2, 'foo' ] ] ]
     83 ```
     84 
     85 </section>
     86 
     87 <!-- /.usage -->
     88 
     89 <!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
     90 
     91 <section class="notes">
     92 
     93 ## Notes
     94 
     95 -   Both `collection` and `filter` **must** be collections. 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`).
     96 
     97 </section>
     98 
     99 <!-- /.notes -->
    100 
    101 <!-- Package usage examples. -->
    102 
    103 <section class="examples">
    104 
    105 ## Examples
    106 
    107 <!-- eslint no-undef: "error" -->
    108 
    109 ```javascript
    110 var randu = require( '@stdlib/random/base/randu' );
    111 var floor = require( '@stdlib/math/base/special/floor' );
    112 var bifurcate = require( '@stdlib/utils/bifurcate' );
    113 
    114 var vals;
    115 var arr;
    116 var out;
    117 var f;
    118 var i;
    119 var j;
    120 
    121 vals = [ 'beep', 'boop', 'foo', 'bar', 'woot', 'woot' ];
    122 
    123 // Generate a random collection...
    124 arr = new Array( 100 );
    125 for ( i = 0; i < arr.length; i++ ) {
    126     j = floor( randu()*vals.length );
    127     arr[ i ] = vals[ j ];
    128 }
    129 
    130 // Randomly assign collection values to a group...
    131 f = new Array( arr.length );
    132 for ( i = 0; i < arr.length; i++ ) {
    133     f[ i ] = ( randu() < 0.5 );
    134 }
    135 
    136 // Compute the groups:
    137 out = bifurcate( arr, f );
    138 console.log( out );
    139 ```
    140 
    141 </section>
    142 
    143 <!-- /.examples -->
    144 
    145 <!-- 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. -->
    146 
    147 <section class="references">
    148 
    149 </section>
    150 
    151 <!-- /.references -->
    152 
    153 <!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
    154 
    155 <section class="links">
    156 
    157 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
    158 
    159 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
    160 
    161 [mdn-object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
    162 
    163 </section>
    164 
    165 <!-- /.links -->