# 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:

## Syntax

`array.map(callbackFunction)`

## Parameters

**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:

(required)**value****:**The current value being processed.

(optional)**index****:**The index of the value in the array.

(optional)**array****:**The original array that the`map()`

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

## Examples

### Example 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.

## Master Google Sheets Automation

I'd appreciate any feedback you can give me regarding this post.

Was it useful? Are there any errors or was something confusing? Would you like me to write a post about a related topic? Any other feedback is also welcome. Thank you so much!