var reduce = require( '@stdlib/utils/reduce' );

Applies a function against an accumulator and each element in an array and returns the accumulated result.

function sum( accumulator, value ) {
    return accumulator + value;
}

var arr = [ 1, 2, 3, 4 ];

var out = reduce( arr, 0, sum );
// returns 10

The function accepts both array-like objects and ndarray-like objects.

var array = require( '@stdlib/ndarray/array' );

function sum( accumulator, value ) {
    return accumulator + value;
}

var opts = {
    'dtype': 'generic'
};
var arr = array( [ [ 1, 2, 3 ], [ 4, 5, 6 ] ], opts );

var out = reduce( arr, 0, sum );
// returns 21

The applied function is provided the following arguments:

• accumulator: accumulated value.
• value: array element.
• index: element index.
• arr: input array.

To set the this context when invoking the input function, provide a thisArg.

function sum( accumulator, value ) {
    this.count += 1;
    return accumulator + value;
}

var arr = [ 1, 2, 3, 4 ];

var ctx = {
    'count': 0
};

var out = reduce( arr, 0, sum, ctx );
// returns 10

var mean = out / ctx.count;
// returns 2.5

• For input arrays, the function differs from Array.prototype.reduce in the following ways:

  • The function requires an initial value for the accumulator. The initial value is used during the first invocation of the reducer function.
  • The function does not skip the first array element.
  • The function does not skip undefined elements.
  • The function does not support dynamic array-like objects (i.e., array-like objects whose length changes during execution).

• The function supports array-like objects exposing getters and setters for array element access (e.g., Complex64Array, Complex128Array, etc).

  var Complex64Array = require( '@stdlib/array/complex64' );
  var Complex64 = require( '@stdlib/complex/float32/ctor' );
  var realf = require( '@stdlib/complex/float32/real' );
  var imagf = require( '@stdlib/complex/float32/imag' );
  
  function sum( acc, z ) {
      var re1 = realf( acc );
      var im1 = imagf( acc );
      var re2 = realf( z );
      var im2 = imagf( z );
      return new Complex64( re1+re2, im1+im2 );
  }
  
  var x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] );
  
  var v = reduce( x, new Complex64( 0.0, 0.0 ), sum );
  // returns <Complex64>
  
  var re = realf( v );
  // returns 16.0
  
  var im = imagf( v );
  // returns 20.0

• For ndarray-like objects, the function performs a reduction over the entire input ndarray (i.e., higher-order ndarray dimensions are flattened to a single-dimension).

• When applying a function to ndarray-like objects, performance will be best for ndarray-like objects which are single-segment contiguous.

• @stdlib/utils/for-each: invoke a function for each element in a collection.
• @stdlib/utils/map: apply a function to each element in an array and assign the result to an element in an output array.
• @stdlib/utils/async/reduce: apply a function against an accumulator and each element in a collection and return the accumulated result.
• @stdlib/utils/reduce-right: apply a function against an accumulator and each element in an array while iterating from right to left and return the accumulated result.