reduce Method (JavaScript)

Accumulates a single result by calling a defined callback function for all elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function.

array1.reduce(callbackfn[, initialValue])

Parameter

Definition

array1

Required. An array object.

callbackfn

Required. A function that accepts up to four arguments. The reduce method calls the callbackfn function one time for each element in the array.

initialValue

Optional. If initialValue is specified, it is used as the initial value to start the accumulation. The first call to the callbackfn function provides this value as an argument instead of an array value.

An object that contains the accumulated result from the last call to the callback function.

A TypeError exception is thrown when either of the following conditions is true:

  • The callbackfn argument is not a function object.

  • The array contains no elements and initialValue is not provided.

If an initialValue is provided, the reduce method calls the callbackfn function one time for each element present in the array, in ascending index order. If an initialValue is not provided, the reduce method calls the callbackfn function one time for each element, starting with the second element.

The return value of the callback function is provided as the previousValue argument on the next call to the callback function. The return value of the last call to the callback function is the return value of the reduce method.

The callback function is not called for missing elements of the array.

NoteNote

The reduceRight Method (JavaScript) processes the elements in descending index order.

Callback Function Syntax

The syntax of the callback function is as follows:

function callbackfn(previousValue, currentValue, currentIndex, array1)

The callback function is always called with four arguments. You can declare the callback function by using up to four parameters.

The following table lists the callback function parameters.

Callback argument

Definition

previousValue

The value from the previous call to the callback function. If an initialValue is provided to the reduce method, the previousValue is initialValue the first time the function is called.

currentValue

The value of the current array element.

currentIndex

The numeric index of the current array element.

array1

The array object that contains the element.

First Call to Callback Function

The first time the callback function is called, the values provided as arguments depend on whether the reduce method has an initialValue argument.

If an initialValue is provided to the reduce method:

  • The previousValue argument is initialValue.

  • The currentValue argument is the value of the first element present in the array.

If an initialValue is not provided:

  • The previousValue argument is the value of the first element present in the array.

  • The currentValue argument is the value of the second element present in the array.

Modifying the Array Object

The array object can be modified by the callback function.

The following table describes the results of modifying the array object after the reduce method starts.

Condition after the reduce method starts

Element passed to callback function?

Element is added beyond the original length of the array.

No.

Element is added to fill in a missing element of the array.

Yes, if that index has not yet been passed to the callback function.

Element is changed.

Yes, if that element has not yet been passed to the callback function.

Element is deleted from the array.

No, unless that element has already been passed to the callback function.

The following example concatenates array values into a string, separating the values with "::". Because no initial value is provided to the reduce method, the first call to the callback function has "abc" as the previousValue argument and "def" as the currentValue argument.

// Define the callback function.
function appendCurrent (previousValue, currentValue) {
    return previousValue + "::" + currentValue;
    }

// Create an array.
var elements = ["abc", "def", 123, 456];

// Call the reduce method, which calls the callback function
// for each array element.
var result = elements.reduce(appendCurrent);

document.write(result);
// Output:
//  abc::def::123::456

The following example determines the sum of rounded values. The reduce method is called with an initial value of 0.

// Define the callback function.
function addRounded (previousValue, currentValue) {
    return previousValue + Math.round(currentValue);
    }

// Create an array.
var numbers = [10.9, 15.4, 0.5];

// Call the reduce method, starting with an initial value of 0.
var result = numbers.reduce(addRounded, 0);

document.write (result);
// Output: 27

The following example determines an integer that is computed from values in an array. The currentIndex and array1 parameters are used in the callback function.

function addDigitValue(previousValue, currentDigit, currentIndex, array) {
    var exponent = (array.length - 1) - currentIndex;
    var digitValue = currentDigit * Math.pow(10, exponent);
    return previousValue + digitValue;
    }

var digits = [4, 1, 2, 5];

// Determine an integer that is computed from values in the array.
var result = digits.reduce(addDigitValue, 0);

document.write (result);
// Output: 4125

In the following example, the return value of the callback function is an array. The initial value provided to the reduce method is an empty array. The code returns an array that contains a subset of another array.

function Process(previousArray, currentValue) {
    // If currentValue is between 1 and 10, 
    // append currentValue to the array.
    var nextArray;
    if (currentValue >= 1 && currentValue <= 10)
        nextArray = previousArray.concat(currentValue);
    else
        nextArray = previousArray;

    document.write("previousArray=" + previousArray);
    document.write(" currentValue=" + currentValue);
    document.write(" nextArray=" + nextArray);
    document.write("<br />");

    // If this is not the last call by the reduce method,
    // the returned array is previousArray on the next call.
    // If this is the last call by the reduce method, the
    // returned array is the return value of the reduce method.
    return nextArray;
}

// Create an array.
var numbers = [20, 1, -5, 6, 50, 3];

// Call the reduce method, starting with an initial empty array.
// This returns an array that contains only values from 1 through 10.
var emptyArray = new Array();
var resultArray = numbers.reduce(Process, emptyArray);

document.write("result array=" + resultArray);

// Output:
//   previousArray= currentValue=20 nextArray=
//   previousArray= currentValue=1 nextArray=1
//   previousArray=1 currentValue=-5 nextArray=1
//   previousArray=1 currentValue=6 nextArray=1,6
//   previousArray=1,6 currentValue=50 nextArray=1,6
//   previousArray=1,6 currentValue=3 nextArray=1,6,3
//   result array=1,6,3

Supported in the Internet Explorer 9 standards document mode. See Version Information.

Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards, Internet Explorer 8 standards.

Community Additions

Show:
© 2014 Microsoft