The Array method indexOf() in Apps Script

The Array method indexOf() is used to find if a value is present in an array. It returns the index where the element is found or -1 if it is not found in the array.

Prerequisites

This tutorial assumes that you're familiar with:

Syntax

array.indexOf(value, startIndex)

Parameters

value (required):

The value to find in the array.

startIndex (optional):

The array index at which to begin searching the array.
If this value is greater than the length of the array, the array will not be searched and -1 will be returned.
If it is negative, the starting position is determined by starting at the end of the array and moving towards the beginning of the array. This will be clear from the examples below.

Return value

The indexOf() method returns the index where the value was found or -1 if it is not found. If the value occurs multiple times then the index of the first position where it is found will be returned.

Note: If you specify the start index, then the array will be searched only from this position onwards. So, the indexOf() method can return -1 even if the element is present in the array but it is present prior to the start index that you specify.

Examples

In Apps Script, you can only run functions. So you have to copy and paste each of the code snippets below into a function before you run them.

I recommend creating separate functions to try out each of the examples below. Also, don't forget to give each of these functions a unique name.

Example 1: Finding if a value is present in an array

Example 1.1

In the code below, colors.indexOf("red") returns 0 since the value "red" is the first element in the array and array indices start at 0.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors.indexOf("red"));

Output

0.0

Example 1.2

In the code below, colors.indexOf("cyan") returns -1 since the value "cyan" is not found in the array.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors.indexOf("cyan"));

Output

-1.0

Example 1.3

In the code below, colors.indexOf("blue") returns 1.0 even though "blue" is present twice. The index of its first occurrence is returned.

var colors = ["red", "blue", "green", "blue", "orange", "purple"];
Logger.log(colors.indexOf("blue"));

Output

1.0

Example 2: Specifying the array index to start the search from

Example 2.1

In the code below, colors.indexOf("red",1) returns -1 since the value "red" is not found at or after the start index 1. The value "red" is only present at index 0.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors.indexOf("red",1));

Output

-1.0

Example 2.2

In the code below, colors.indexOf("red",10) returns -1 since the start index 10 exceeds the length of the array.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors.indexOf("red",10));

Output

-1.0

Example 2.3

In the code below, colors.indexOf("blue", 2) returns 3.0 even though "blue" is present in index 1. This is because the start index has been specified as 2. The index of the first occurrence of the value "blue" in the array colors after the start index is returned.

var colors = ["red", "blue", "green", "blue", "orange", "purple"];
Logger.log(colors.indexOf("blue", 2));

Output

3.0

Example 2.4

When you specify a negative start index of -1, the starting position is the last element of the array. When it is -2, it is the penultimate element of the array and so on.

Note: Once the starting point is determined, the actual direction of search remains unchanged. The array is always searched left to right. Therefore, colors.indexOf("orange",-1) returns -1 but colors.indexOf("orange",-2) returns 4. This is because, when the start index is -1, the search begins at the last element and proceeds in a left to right direction. The element "orange" will not be found since it is to the left of where the search begins.

In the code below, colors.indexOf("purple",-1) returns 5.0 because the search starts at the last element, the value "purple" was found at that position and the index of that position in the array is 5.

The statement colors.indexOf("orange",-1) returns -1 since the search starts at the last position and the value "orange" is not found at the last position. However, colors.indexOf("orange",-2) returns 4.0 since the search starts at the penultimate position, the value "orange" is found at that position and the index of this position in the array is 4.

var colors = ["red", "blue", "green", "black", "orange", "purple"];
Logger.log(colors.indexOf("purple",-1));
Logger.log(colors.indexOf("purple",-3));
Logger.log(colors.indexOf("orange",-1));
Logger.log(colors.indexOf("orange",-2));

Output

5.0

-1.0

4.0

Example 3: The search is performed using a strict comparison (i.e., similar to the === operator)

In the code below, values.indexOf("1") returns -1 since a strict comparison of the number 1 and string "1" results in false.

function indexOfEx6() {
 var values = [1,2,3];
 Logger.log(values.indexOf("1"));
}

Output

-1.0

Example 7: Be careful when the element you're searching for is an array or object

In the code below, colors.indexOf(["red", "blue"]) returns -1 even though the array ["red", "blue"] is present in the array colors. This is because comparing two arrays or objects for equality in Apps Script requires special logic. A strict comparison performed by the indexOf() method will return false even if both of the arrays being compared contain the same values.

var colors = [["red","blue"], "green", "black", "orange"];
Logger.log(colors.indexOf(["red", "blue"]));

Output

-1.0

Conclusion

In this tutorial, you learned how to use the indexOf() method to find if an element is present in an array.

Sign up to be notified when I publish new content

By signing up you agree to the Privacy Policy & Terms.