time-to-botec/js/node_modules/@stdlib/utils/count-by/README.md
NunoSempere b6addc7f05 feat: add the node modules
Necessary in order to clearly see the squiggle hotwiring.
2022-12-03 12:44:49 +00:00

4.6 KiB

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 );