Apps Script Course: Arrays

Arrays are objects that can contain a large number of values and will be particularly useful in Apps Script... For example, when you want to retrieve values from a range of cells, you will get an array, similarly, when you want to insert a row of data into a sheet, you will need to use an array.

Arrays are also very practical for performing more advanced actions such as searching, processing, sorting, and filtering that we will see later in this course.


Creating an Array

To create an empty array, enter [] and assign this array to a variable or a constant:

const myArray = [];

You can also add values to this array, for example, numerical values:

const numberList = [4.5, -45.6, 12.36, -7.31];

Or text format values:

const courseWords = ['Course', 'Apps', 'Script'];

And many other types of values, even arrays (but we will come back to that later).

Accessing Values

Here is an array containing 3 values:

const valueRange = ['Sheets', '-', 'Pratique'];

To access a value in an array, specify its number in []. For example, for the first value, enter:

const valueRange = ['Sheets', '-', 'Pratique'];
const text1 = valueRange[0];

console.log(text1); // Displays: Sheets
Array values are numbered starting from 0 (so the first value is at index 0, the second at 1, etc).

Modifying a Value

In the same way as accessing an array's data, specify the index of the value in the array to modify it:

const valueRange = ['Excel', '-', 'Pratique'];
valueRange[0] = 'Sheets';

// You can also display an entire array's data with console.log()
console.log(valueRange); // Displays: [ 'Sheets', '-', 'Pratique' ]

You can also use the values stored in variables to complete your array (and vice versa):

const word1 = 'Sheets';
const word2 = '-';
const valueRange = [word1, word2, 'Pratique'];
const word3 = valueRange[2];

console.log(valueRange); // Displays: [ 'Sheets', '-', 'Pratique' ]
console.log(word3) // Displays: Pratique;

And you can also directly enter an operation so that the array retains its result:

const monthArray = ['January', 'February', 'March'];
const year = 2024;
const monthYearArray = [monthArray[0] + ' ' + year, monthArray[1] + ' ' + year, monthArray[2] + ' ' + year];

console.log(monthYearArray); // Displays [ 'January 2024', 'February 2024', 'March 2024' ]: 

Value or Reference

Before going further, a brief aside on values and references... You may have noticed that in one of the previous examples, the array was assigned to a constant, one of its values was modified, and yet no error appeared:

const valueRange = ['Excel', '-', 'Pratique'];
valueRange[0] = 'Sheets';

To better understand, try to guess what values will be returned by console.log for these 2 examples:

let example1 = 10;
let example2 = example1;
example2 = 20;

// What will the value of example1 be?
console.log(example1);
let example1 = [10];
let example2 = example1;
example2[0] = 20;

// What will the value in example1 be?
console.log(example1);

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

In the first code, the value of example1 remains 10, there was no trick here.

In the second code, the value in example1 changed to 20 even though this variable did not seem to have been modified.

In the first example, the value was of a primitive type (which are "simple" values such as numerical, text, boolean, etc.), so the value was simply "copied", there was no "link" between these 2 variables.

In the second example, the value was an array... And when the operation example2 = example1 occurred, example2 did not receive a copy of the array but a reference to it. The two variables therefore had a reference to the same array, so if you modify the array from one, you can access the modifications from the other since it is the same array (somewhat like if you create 2 shortcuts on your computer to the same file).

It is also for this reason that you can assign an array to a constant and modify its content (because what has actually been assigned to the constant and that you cannot change, is the reference to the array and not its content).

All of this is a bit technical, do not worry if it's still a bit unclear to you, and simply come back to this page when you need it.

Adding a Value

To add a value to the end of an array, use the push method. A "method" is the name given to an object function that you will add here following the concerned object (the array):

const shoppingList = [];

shoppingList.push('bread');
shoppingList.push('sugar');
shoppingList.push('apples');

console.log(shoppingList); // Displays: [ 'bread', 'sugar', 'apples' ]

// You can also add several values at once
shoppingList.push('carrots', 'tomatoes', 'onions');

console.log(shoppingList); // Displays: [ 'bread', 'sugar', 'apples', 'carrots', 'tomatoes', 'onions' ]

To add a value at the beginning of an array, use the unshift method:

const shoppingList = ['carrots', 'tomatoes', 'onions'];

shoppingList.unshift('bread');

console.log(shoppingList); // Displays: [ 'bread', 'carrots', 'tomatoes', 'onions' ]

Number of Values

To obtain the number of values contained in an array, use the length property:

const shoppingList = ['carrots', 'tomatoes', 'onions'];

shoppingList.push('bread');

console.log(shoppingList.length); // Displays: 4

In this example, console.log returns 4 because the array contains 4 values.

You already know how to access a value of an array based on its index and how to get the number of values in an array... Now find a solution to access the last value of the array (using the length property), before moving to the solution a bit further down:

const shoppingList = ['carrots', 'tomatoes', 'onions'];

const lastValue = 

console.log(lastValue);

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

The index you need to specify here is the number of values in the array - 1 because remember, the indexing starts at 0:

const shoppingList = ['carrots', 'tomatoes', 'onions'];

const lastValue = shoppingList[shoppingList.length - 1];

console.log(lastValue); // Displays: onions

By using this solution (instead of directly entering index 2), you can add values to the array without having to modify the code:

const shoppingList = ['carrots', 'tomatoes', 'onions'];

shoppingList.push('parsley', 'peppers');

const lastValue = shoppingList[shoppingList.length - 1];

console.log(lastValue); // Displays: peppers