map
Loops through a list, applies a function to each value, and returns a new list.
The first parameter takes a list or list-like object, and the second takes a function that amends each list value. You must write this amending function as a lambda expression
The function is often used to map a more complex data structure — for example, an array containing multiple JSON objects — to a simpler list of values. The examples below provide further guidance.
Parameters
INPUT (list, column, row, or array)
The input list or list-like object.
A list-like object = table column, table row, or JSON array.
FUNCTION (function)
An anonymous function to apply to each list value. Write the function as a lambda expression and ensure it has one parameter — e.g.
value -> div(value, 10)divides each value by 10.
Examples
Mapping a list
The function loops through a list, applies a function to each value, and returns a list of amended values.
ATL in Script | Input List | Amended List | Printed Result |
|---|---|---|---|
[[ myList = makeList(10, 20, 30) map(myList, value -> value + 1) ]] | (10, 20, 30) | (11, 21, 31) | 11, 21 and 31 |
The lambda expression value -> value + 1 adds a value of 1 to each input value. This is an example of using arithmetic operators in a lambda. You can also use other ATL functions in a lambda. For example:
ATL in Script | Printed Result |
|---|---|
[[ myList = makeList(10, 20, 30) map(myList, x -> numToWords(x)) ]] | Ten, twenty and thirty |
[[ myList = makeList(10, 20, 30) map(myList, number -> joinStrings(number,"%")) ]] | 10%, 20% and 30% |
[[ myList = makeList(1520, 2760, 3728) map(myList, y -> abbreviateNumber(currencyFormat(y,'GBP'))) ]] | £1.5K, £2.8K and £3.7K |
Mapping an array of objects
Assume a "Describe a JSON Object" project with this data:
{
"data": [
{"product": "Retine", "sales": 24524, "target": 20000},
{"product": "Ointmo", "sales": 26731, "target": 25000},
{"product": "Glower", "sales": 18243, "target": 20000}
]
}The "data" array contains three JSON objects. An array is a like-like object, so you can loop through the array and write a lambda that maps each JSON object to its product or sales value. For example:
ATL in Script | Resulting List | Printed Result |
|---|---|---|
| (Retine, Ointmo, Glower) | Retine, Ointmo and Glower |
| (24524, 26733, 18243) | 24,524, 26,733 and 18,243 |
Once you have these lists, you can use other functions to produce narrative text.
[[ productsList = map(WholeJSON.data, object -> object.product) salesList = map(WholeJSON.data, object -> object.sales) salesTotal = totalVal(salesList) "Combined sales of [[productsList]] totaled [[abbreviateNumber(currencyFormat(salesTotal))]]." ]]
The output text is:
Combined sales of Retine, Ointmo and Glower totaled $69.5K.
Important
The method of using dot notation — e.g. object -> object.sales — to reference specific key names also works when you're mapping a list of ATL objects. Also, note that bracket notation — e.g. object -> object['sales'] — works equally well.
Mapping a two-dimensional array
Assume a "Describe a JSON Object" project with this data:
{
"data": [
["Retine", 24524, 20000],
["Ointmo", 26731, 25000],
["Glower", 18243, 20000]
]
}The "data" array contains three inner arrays. Each inner array has three values: a product value at Index 0, a sales value at Index 1, and a target value at Index 2. There are no key names to reference, so you must reference the index numbers when mapping.
For example, to map each inner array to its Index 0 value:
ATL in Script | Resulting List | Printed Result |
|---|---|---|
| (Retine, Ointmo, Glower) | Retine, Ointmo and Glower |
Here's how you might use map with other functions to produce narrative text:
[[ productsList = map(WholeJSON.data, array -> array[0]) salesList = map(WholeJSON.data, array -> array[1]) salesTotal = totalVal(salesList) "Combined sales of [[productsList]] totaled [[abbreviateNumber(currencyFormat(salesTotal))]]." ]]
The output text is:
Combined sales of Retine, Ointmo and Glower totaled $69.5K.
