time-to-botec/squiggle/node_modules/@stdlib/utils/count-by/README.md

countBy

Group values according to an indicator function and return group counts.

Usage

var countBy = require( '@stdlib/utils/count-by' );

countBy( collection, [options,] indicator )

Groups values according to an indicator function, i.e., a function which specifies which group an element in the input collection belongs to, and returns group counts.

function indicator( v ) {
    return v[ 0 ];
}
var arr = [ 'beep', 'boop', 'foo', 'bar' ];

var out = countBy( arr, indicator );
// returns { 'b': 3, 'f': 1 }

An indicator function is provided two arguments:

• value: collection element
• index: collection index

function indicator( v, i ) {
    console.log( '%d: %d', i, v );
    return v[ 0 ];
}
var arr = [ 'beep', 'boop', 'foo', 'bar' ];

var out = countBy( arr, indicator );
// returns { 'b': 3, 'f': 1 }

The function accepts the following options:

• thisArg: execution context.

To set the indicator execution context, provide a thisArg.

function indicator( v ) {
    this.count += 1;
    return v[ 0 ];
}
var context = {
    'count': 0
};
var opts = {
    'thisArg': context
};
var arr = [ 'beep', 'boop', 'foo', 'bar' ];

var out = countBy( arr, opts, indicator );
// returns { 'b': 3, 'f': 1 }

console.log( context.count );
// => 4

Notes

• A collection may be either an Array, Typed Array, or an array-like Object (excluding strings and functions).

• The value returned by an indicator function should be a value which can be serialized as an object key. As a counterexample,

  function indicator( v ) {
      return {};
  }
  var arr = [ 'beep', 'boop', 'foo', 'bar' ];
  
  var out = countBy( arr, indicator );
  // returns { '[object Object]': 4 }
  

  while each group identifier is unique, all collection elements resolve to the same group because each group identifier serializes to the same string.

Examples

var randu = require( '@stdlib/random/base/randu' );
var floor = require( '@stdlib/math/base/special/floor' );
var countBy = require( '@stdlib/utils/count-by' );

var vals;
var arr;
var out;
var i;
var j;

vals = [ 'beep', 'boop', 'foo', 'bar', 'woot', 'woot' ];

// Generate a random collection...
arr = new Array( 100 );
for ( i = 0; i < arr.length; i++ ) {
    j = floor( randu()*vals.length );
    arr[ i ] = vals[ j ];
}

function indicator( v ) {
    // Use the first letter of each element to define groups:
    return v[ 0 ];
}

// Compute the group counts:
out = countBy( arr, indicator );
console.log( out );