Skip to main content

Working with lists

Like most computing languages, ATL supports lists of values as a data type. The values can be of any type, including other lists. In JSON, these lists of lists are known as arrays.

Read these sections for further guidance:

Creating lists

You can define a list in ATL by writing a comma-separated list of values inside a pair of round brackets.

Alternatively, you can use the makeList function.

ATL in Script

Created List

Printed Result

[[(1, 2, 3)]]

(1, 2, 3)

1, 2 and 3

[[makeList(1, 2, 3)]]

(1, 2, 3)

1, 2 and 3

[[('A', 'B', 'C')]]

(A, B, C)

A, B and C

[[makeList('A', 'B', 'C')]]

(A, B, C)

A, B and C

The Printed Result column shows how Studio displays the list in printed form — that is, as punctuated text. The list's formatting is determined by your project settings. You can override the settings with the list function.

Important

You must use makeList to create an empty or single-value list.

Accessing list values

To get individual values, use bracket notation and specify the index value.

ATL in Script

Result

Notes

[[myList = makeList(10, 20, 30, 40, 50); myList[2]]]

30

The third value in the list.

[[myList = makeList(10, 20, 30, 40, 50); myList[0]]]

10

The first value in the list.

Note

Zero-based indexing applies, so the first element in a sequence is assigned index 0.

To get a subset of values, use sublist or the syntax for list slicing.

ATL in Script

List slice

Printed Result

[[myList = makeList(10, 20, 30, 40, 50); sublist(myList, 1, 4)]]

(20, 30, 40)

20, 30 and 40

[[myList = makeList(10, 20, 30, 40, 50); myList[1:4]]]

(20, 30, 40)

20, 30 and 40

Tip

The syntax for list slicing has other uses. For further guidance, see ATL Guide > Slicing.

Adding values to a list

You can add values to a list — or join two or more lists — using the concat function.

ATL in Script

Resulting List

[[team = makeList('Cammy', 'Linda', 'Andy')]]

(Cammy, Linda, Andy)

[[

team = makeList('Cammy', 'Linda', 'Andy')

concat(team, 'Chrissie')

]]

(Cammy, Linda, Andy, Chrissie)

[[

team = makeList('Cammy', 'Linda', 'Andy')

newMembers = makeList('Chrissie', 'Louise')

concat(team, newMembers)

]]

(Cammy, Linda, Andy, Chrissie, Louise)

Alternatively, use list slice assignment to add values at a specific list position.

ATL in Script

Resulting List

[[

team = makeList('Cammy', 'Linda', 'Andy')

newMembers = makeList('Chrissie', 'Louise')

team[1:1] = newMembers

]]

(Cammy, Chrissie, Louise, Linda, Andy)

[[

team = makeList('Cammy', 'Linda', 'Andy')

newMembers = makeList('Chrissie', 'Louise')

team[ :0] = newMembers

]]

(Chrissie, Louise, Cammy, Linda, Andy)

Tip

To learn more about list slice assignment, see ATL Guide > Slicing.

Changing list values

You can change list values by using this method:

ATL in Script

Resulting List

[[team = makeList('Peter', 'Kapila', 'Logan', 'Kate')]]

(Peter, Kapila, Logan, Kate)

[[

team = makeList('Peter', 'Kapila', 'Logan', 'Kate')

team[2] = 'Jacek'

team

]]

(Peter, Kapila, Jacek, Kate)

Use list slice assignment to change a subset of values.

ATL in Script

Resulting List

[[team = makeList('Peter', 'Kapila', 'Logan', 'Kate')]]

(Peter, Kapila, Logan, Kate)

[[

team = makeList('Peter', 'Kapila', 'Logan', 'Kate')

team[1:3] = makeList('Emma', 'Ashwinie')

team

]]

(Peter, Emma, Ashwinie, Kate)

Filtering lists

To filter any list, use the filter function.

ATL in Script

Filtered List

[[

myList = makeList(10, 20, 30, 40, 50)

filter(myList, value -> value >= 30 && value <= 60)

]]

(30, 40, 50)

[[

team = makeList('Linda', 'Piotr', 'Kapila', 'Lucia')

filter(team, n -> len(n) > 4 && endsWith(n, 'a'))

]]

(Linda, Kapila, Lucia)

Tip

See the filter topic for further guidance.

Mapping lists

Use map to loop through a list, apply a function to each value, and get an amended list.

ATL in Script

Amended List

[[

myList = makeList(10, 20, 30)

map(myList, value -> value + 1)

]]

(11, 21, 31)

[[

team = makeList('Jacek', 'Varuni', 'Emma')

map(team, name -> upper(name))

]]

(JACEK, VARUNI, EMMA)

Tip

See the map topic for further guidance.

Sorting lists

You can sort any list with the sort function, but there are better (simpler) options for sorting lists of numbers, strings, or datetime values. Use the following table for guidance:

ATL Function

Description

sortNumbers

Sorts numbers in ascending order.

sortNumbersReverse

Sorts numbers in descending order.

sortStrings

Sorts strings in alphabetical order.

sortStringsReverse

Sorts strings in reverse-alphabetical order.

sortDateTimes

Sorts datetime objects in chronological order.

sortDateTimesReverse

Sorts datetime objects in reverse-chronological order.

sortMonthNames

Sorts month names in order of calendar month.

Here are examples using sortStrings and sortMonthNames:

ATL in Script

Sorted List

[[

monthList = ('July', 'May', 'April', 'January')

sortStrings(monthList)

]]

(April, January, July, May)

[[

monthList = ('July', 'May', 'April', 'January')

sortMonthNames(monthList)

]]

(January, April, May, July)

© Arria Data2Text Limited