Script Writing - Working With Lists

Overview

This article details the various ways that you can interact with Lists in App Scripts, including how to combine multiple Lists, how to access items in a List, how to manipulate (e.g. add or remove) items in a List, and also provides examples of how to use the most common List methods. 

For information on how to use Loops to iterate through objects in a List, please refer to the Script Writing - Using Loops with Lists article. 

What is a List?

• Lists are ordered sequences of data in Groovy.
• Lists can hold a variety of data and can have different types intermingled.
• Lists are declared with List.

👀 NOTE: In TrackVia, Checkbox field values are stored as lists. Before manipulating Checkbox field values, you must declare it as a List. This allows the use of the methods and operations described later on in this article. See the example below:

List checkBox = currentValues["My Checkbox"] as List

Combining Lists

Two Lists can be added together to create a combined List. The order of the addition determines the order of the created List. 

//Example 1
List sampleList1 = [1, 2, 3] as List
List sampleList2 = [4, 5, 6] as List
List sampleList3 = sampleList1 + sampleList2 as List
//sampleList3 = [1, 2, 3, 4, 5, 6]

//Example 2
List sampleList1 = [1, 2, 3] as List 
List sampleList2 = [4, 5, 6] as List
List sampleList4 = sampleList2 + sampleList1 as List
//sampleList4 = [4, 5, 6, 1, 2, 3] 

Accessing Items in a List

Individual elements in a List can be accessed through the index position. Like many other languages, Groovy's index starts at 0.

Using list[0] will return the first value in the List. Using list[-1] will yield the last object in the List. For example,

List sampleList = [1, 2, 3]
sampleList[0]
//Returns 1

sampleList[-1]
//Returns 3 

You can also access specific portions of the List using the subList() method. The start and ending index are provided as parameters in this method.

List sampleList1 = ["Orange", "Green", "Blue", "Purple", "Red", "Yellow"] as List

//Example 1
List sublist1 = sampleList1.sublist(3,4) as List
//subList1 = [Purple]

//Example 2
List sublist2 = sampleList1.sublist(2,3) as List
//sublist2 = [Blue]

//Example 3
List sublist3 = sampleList1.sublist(0,3) as List
//sublist3 = [Orange, Green, Blue]

Manipulating Items in a List

Individual elements can be added or removed in different ways.

Adding Items to a List

• Items can be added in bulk using the "Combining Lists" method detailed above.
• Individual elements can be added using the shovel operator << or the .add() method.
• The .add() method has the benefit of letting us specify the index position of the added item by specifying the index, then the value to be added.

See the examples below: 

//Example 1
List sampleList1 = [1, 2, 3] as List
sampleList1 << 4 
//sampleList1 = [1, 2, 3, 4]

//Example 2
List sampleList1 = [1, 2, 3] as List
sampleList1.add(4)
//sampleList1 = [1, 2, 3, 4]

// Example 3
List sampleList1 = [1, 2, 3] as List
sampleList1.add(0, 4)
//sampleList1 = [4, 1, 2, 3]

Removing Items from a List

• Items in Lists can be removed in bulk by subtracting a List from the original List.
• The listed elements will be removed from the original list anywhere they appear.

See the examples below:

//Example 1
List sampleList1 = [1, 2, 3, 4, 5, 6, 6, 7, 9] as List
List sampleList2 = [4, 5, 6] as List
List sampleList3 = sampleList1 - sampleList2 as List
//sampleList3 = [1, 2, 3, 7, 8, 9]

//Example 2
List sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8, 9] as List
List sampleList2 = [4, 5, 6] as List
List sampleList3 = sampleList1 - sampleList2 as List
//sampleList3 = [1, 2, 3, 7, 8, 9]

• Individual items can be removed either through subtraction of the individual element or through the .pop() method which removes the last element
• The index position of the List can be used with the .remove() method to remove items at a specific place.

See the examples below: 

//Example 1
List sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8, 9] as List
List sampleList2 = sampleList1 - 3
//sampleList2 = [1, 2, 4, 5, 6, 7, 8, 9]

//Example 2
List sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8, 9] as List
sampleList1.pop()
//sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8]

//Example 3
List sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8, 9] as List
sampleList1.remove(0)
//sampleList1 = [2, 3, 4, 5, 6, 7, 8, 9]

Common List Methods

.add()

• Adds an object to the end of a List
• An index can also be specified to put the object a specific point in the List. 

See the examples below: 

//Example 1
List sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8, 9] as List
sampleList1.add(10)
//sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

//Example 2
List sampleList1 = [1, 2, 3, 4, 5, 6, 7, 8, 9] as List
sampleList1.add(0, 10)
//sampleList1 = [10, 1, 2, 3, 4, 5, 6, 7, 8, 9]

.contains()

• Checks if a value exists in the List. 
• This returns a Boolean value of true or false

See the example below: 

List sampleList = ["Orange", "Green", "Blue"] as List
sampleList.contains("Orange")
//Returns true

sampleList.contains("Purple")
//Returns false

.isEmpty()

• Checks whether the List is empty and contains no elements.
• This returns a Boolean value of true or false

See the example below:

List sampleList1 = ["Orange", "Green", "Blue"] as List
List sampleList2 = []

sampleList1.isEmpty()
//Returns false

sampleList2.isEmpty()
//Returns true

.reverse()

• Returns a List with the elements in reverse order. See the example below:

List sampleList1 = ["Orange", "Green", "Blue"] as List
List sampleList2 = sampleList1.reverse() as List
//sampleList2 = [Blue, Green, Orange]

.size()

• Returns the number of objects in a List as an integer. See the example below: 

List sampleList1 = ["Orange", "Green", "Blue"] as List
List sampleList2 = []

sampleList1.size()
//Returns 3

sampleList2.size()
//Returns 0

Related Articles: 

• Script Writing - Using Loops with Lists
• App Script Best Practices
• App Script Example Library