addToAtlObject
Adds key–value pairs to an ATL object.
If a given key already exists in the ATL object, the value given for that key replaces the existing value.
For more about ATL objects, see ATL Guide > ATL objects.
Parameters
OBJECT (ATL object)
The ATL object to which to add keys and values.
KEYS (string or list)
Optional. One or more key names. Key names must be strings, and each must be unique.
To add multiple keys, input a list. Keys are paired with values by position in the list.
VALUES (any or list)
Optional. One or more values. The values can be any type: number, string, list, ATL object, etc.
To add multiple values, input a list. Values are paired with keys by position in the list.
Examples
This example shows how to add key–value pairs to an ATL object:
[[
myObject = createAtlObject()
keys = makeList('Branch', 'Manager', 'Sales', 'Profit')
values = makeList('Boston', 'Chris Logan', 1351152.58, 75150.78)
addToAtlObject(myObject, keys, values)
]]
The amended ATL object is:
|
Note
The first ATL statement — myObject = createAtlObject() — creates an empty ATL object. You can also add key–value pairs to an already populated object. This is shown further below.
The function excludes a key when there is no corresponding value, and the same is true in reverse.
[[
myObject = createAtlObject()
keys = makeList('Branch', 'Manager', 'Sales', 'Profit', 'Units')
values = makeList('Boston', 'Chris Logan', 1351152.58, 75150.78)
addToAtlObject(myObject, keys, values)
]]
There are five values in keys and only four in values, so the resulting object has just four key–value pairs.
|
Each key in an ATL object must be unique. Bear in mind that when a given key (second parameter) already exists in the input ATL object, the given value for that key (third parameter) replaces the existing value. For example:
[[
myObject = (product = 'Ointmo', Q1sales = 21624, Q2sales = 30714)
newKeys = makeList('product', 'Q3sales')
newValues = makeList('Retine', 21000)
addToAtlObject(myObject, newKeys, newValues)
]]The amended ATL object is:
|
The function attempts to add two key–value pairs to myObject, but one given key (product) already exists. Therefore, the value given for that key ('Retine') replaces the original value ('Ointmo').
Note that the other given key (Q3Sales) and its value are added to the object.
