The Array method map() in Apps Script
The Array method map() returns a new array that is populated with values obtained by calling a function on every element of the original array.
Given the array [1,2,3] and a function f(x), the map method will apply the function to each element in the array and will return the array [f(1), f(2), f(3)].
Prerequisites
This tutorial assumes that you're familiar with:
Syntaxarray.map(callbackFunction)
Parameters
array.map(callbackFunction)callbackFunction (required):
This function will be executed once for every element in the array and a new array containing the output of these executions will be returned.
The callbackFunction can accept three arguments:
value(required): The current value being processed.index(optional): The index of the value in the array.array(optional): The original array that themap()method was called on.
Return value
The map() method returns a new array containing values obtained by executing the callbackFunction on every element of the original array.
How does the map() Array method work?
The map() method will execute the callbackFunction once for every element in the array. The value returned by the callbackFunction will be added to a new array. This new array will then be returned.
Consider an input array named arr containing 5 values and a callback function named f().
Input array
val1 | val2 | val3 | val4 | val5 |
Output array
The value returned by arr.map(f) is an array whose elements are obtained by executing the function f() on each value of arr.
f(val1) | f(val2) | f(val3) | f(val4) | f(val5) |
ExamplesExample 1: Using the map() Array method to square values in an array
Example 1.1
In the code below, the function square(value) is the callbackFunction parameter in the map() method. This function is executed once for every element in the array values and it returns the square of each element. The array squaredValues contains these values.
function mapEx1_1() {
var values = [1,2,3,4,5];
var squaredValues = values.map(square);
Logger.log(squaredValues);
}
function square(value) {
return value * value;
}Output
[1.0, 4.0, 9.0, 16.0, 25.0]
Example 1.2
Instead of defining the function square() separately and then passing it as a parameter, you can also define it in-line. The code below shows you how to do this.
function mapEx1_2() {
var values = [1,2,3,4,5];
var squaredValues = values.map(function(value) {
return value * value;
});
Logger.log(squaredValues);
}Output
[1.0, 4.0, 9.0, 16.0, 25.0]
Note
Notice that there is no name for the function in the above example.
This is because, in Apps Script (which is a version of JavaScript), a function is basically a variable with a value of type function.
Consider the function addTwoNumbers() below.
function addTwoNumbers(num1, num2) {
return num1 + num2;
}This function can also be rewritten in the following way:
var addTwoNumbers = function(num1, num2) {
return num1 + num2;
}Here the variable addTwoNumbers contains a value of type function. In Apps Script, both of the above code snippets have the exact same result.
When you pass a function as a parameter to the map() method, you're really passing the function value. Therefore, the following statement values.map(square); in Example 1.1 is the same as the code snippet below in Example 1.2
values.map(function(value) {
return value * value;
});This is because square is just a variable that contains the following function value:
function(value) {
return value * value;
}Conclusion
In this tutorial, you learned how to use the map() Array method to create a new array that is obtained by applying a function to every element of the original array.