Arrays

An array is a data structure that holds a group of values. Arrays are helpful when you have a list of items that are similar in type. For example, lists of area codes, phone numbers, or customer names.

There are two kinds of arrays that you can use in Studio:

String arrays: Pipe-delimited strings in a variable. They hold string values, which can be made up of alphanumeric characters.
Dynamic arrays: Arrays that are stored in dynamic data objects.

If you have a list where the data is all different types of information about a single entity, a dynamic data objects is a more appropriate data structure to use. A comparison of arrays and objects is available on the Data Structures help page.

Key Facts about Arrays

An array must have at least two elements. An array with only one element appears to be a regular variable. It's still an array and you can call it as an array. The same is true for dynamic arrays.
In Studio, array indexes start at 1.
Some functions are available for use with arrays, such as index() and indexof().
You can use any delimiter with string arrays. However, to be natively read, a string array must use a pipe character as the delimiter.

Try it Out

Download the Array Examples script and import it into Studio. Many of the examples from this help page are available in Snippet actions in the example script. You can open the Snippet editor window and run the debugger to see the example.

Array Syntax Summary

Create a string array with one of the following syntaxes.

Assign a value to each element using its index:

ASSIGN <var>[<index1>] = "<value1>"

ASSIGN <var>[<index2>] = "<value2>"

ASSIGN <var>[<index3>] = "<value3>"

Assign all element values to a variable in a pipe-delimited string:

ASSIGN <var> = "<value1> | <value2> | <value3>"

Create a dynamic array with the following syntax:

DYNAMIC <object>

ASSIGN <object>.<member>[<index>].<sub-member>= "value"

Additional forms of dynamic arrays are supported.

To refer to a specific element in a string array, use this syntax:

<var>[index]

To refer to a specific element in a dynamic array, use this syntax:

ASSIGN <var> = <object>.<member>[<index>].<arrayElement>

Elements and Indexes

The values that an array holds are called elements. The script keeps track of the order of the elements in the array. Each element in an array has a numeric identifier, called an index number. The index is assigned automatically to each element based on its position in the array. If you rearrange, add, or remove elements, their indexes can change.

In Studio, array indexes start at 1. Indexes must be positive integers. You need to know the index to interact with a specific element in the array. You can use the indexof() function to determine an element's index, if you don't know it.

Refer to Individual Element of String Array

When referring to an individual element of a string array, use this syntax: <arrayElement>[<index>]. You can use this syntax on either side of the equals sign. For example, you can use it to assign a value to an element or to refer to an element's value, such as when assigning the value to another variable.

For example:

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

In this example, Beowulf's index is 1, Sir Gawain's is 2, and Byrtnoth's is 3. These elements have the same indexes when looking at the array in pipe-delimited format: name = "Beowulf|Sir Gawain|Byrhtnoth". To determine the indexes of an array in this format, count the elements from left to right, starting with 1.

Indexes are Filled in Numeric Order

Indexes are filled one by one in numeric order. If you reference an index that doesn't currently exist in the array, the script creates it and it will be empty unless you assign a value to it. The script creates any indexes that don't exist between the one you reference and the previous last element in the array. The elements the script adds to fill in indexes are empty. For example:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth" 
ASSIGN heroes[6] = "Lancelot"

The resulting array is heroes = "Beowulf|Sir Gawain|Byrhtnoth|||Lancelot". The script added elements for indexes 4 and 5, but because no value was assigned to them, they are empty.

Similarly, if you attempt to pull a value from an element that doesn't exist, that element is created. All elements between the one you attempted to reference and the previous last element are also created and will be empty.

If an empty array element is referenced in a context that expects a number, the script behaves as if the value were zero.

Determine the Next Unused Index

To avoid creating unnecessary empty elements in an array, you can determine the next unused index. You must count the elements in the array, then add 1 to that number. This gives you the next open index number.

To do this, use the size() function. For example:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"  
ASSIGN nextIndex = heroes.size() + 1
ASSIGN heroes[nextIndex] = Roland

In this example, heroes.size() returns the number of elements in the name array. The value of totalNames is 3. By adding one to it and using the nextIndex variable in place of the index number, you can add an element to the array.

You can also use the count() function.

String Arrays

String arrays can be defined in two ways. The first is to explicitly name each element individually. The following example shows a string array containing text values that are defined element by element.

ASSIGN heroes[1] = "Beowulf"
ASSIGN heroes[2] = "Sir Gawain" 
ASSIGN heroes[3] = "Byrhtnoth"

The number in square brackets after the array name is the index number of the element. This is the identifier for each element.

The second way to define a string array is with a pipe-delimited string using a single pipe character (|) between each element. This example shows the array from the first example defined as a pipe-delimited string. When you create a pipe-delimited string array, the values on right side of the statement must be enclosed in double quotes.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"

There is no difference between the functions and you can use them interchangeably. Both methods of defining the string array produce the same result, a variable that contains an array of elements.

Using the ASSIGN keyword when declaring a string array is not required. However, it's helpful to use it. Including ASSIGN makes the place in your script where you introduced the array easy to locate using Advanced Search. Without ASSIGN, you must search for the name of the array. The search results will contain every reference to the array in your script. When you include ASSIGN in your search term, the search returns only the results where the variable is explicitly assigned. To declare a variable without ASSIGN, use this syntax: <name> = "<value>"

Dynamic Arrays

Dynamic arrays can take several forms:

The dynamic data object contains an array. Each array element is also an object member.

DYNAMIC beowulfLocations 
ASSIGN beowulfLocations[1] = "Land of the Geats"
ASSIGN beowulfLocations[2] = "Heorot" 
ASSIGN beowulfLocations[3] = "Earnanæs"

The dynamic object contains a member that holds an array. The other members of the object may hold string or numeric values, or they could be other arrays.

DYNAMIC beowulfCharacteristics 
ASSIGN beowulfCharacteristics.foe[1].characteristics[1] = "Grendel"
ASSIGN beowulfCharacteristics.foe[1].characteristics[2] = "son of Cain"
ASSIGN beowulfCharacteristics.foe[2] = $"Grendel\'s mother" 
ASSIGN beowulfCharacteristics.foe[3] = "Dragon"

A string array holds elements that each contain a dynamic data object.
```
DYNAMIC epicPoems
ASSIGN epicPoems.poemName = "Beowulf"
DYNAMIC heroes 
ASSIGN heroes.heroName = "Beowulf"
DYNAMIC monsters
ASSIGN monsters.monsterName = "Grendel"
ASSIGN oldEnglish[1] = epicPoems
ASSIGN oldEnglish[2] = heroes
ASSIGN oldEnglish[3] = monsters
```
You can view the contents of the dynamic objects and the string array on the Variables as Tree tab in the Snippet editor window when you run the debugger.

This type of dynamic array cannot be used when you need your script to work with other systems, such as when connecting to APIs. The data that the string array holds cannot be serialized or converted into JSON or XML strings.

Reference an Array Element by Location

You can reference an element in a string or dynamic array using its location in the array, specified by its index. For example:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN currentName = heroes[2]

The value of currentName is Sir Gawain.

You can use a variable in place of the index number on either side of the equal sign in an ASSIGN statement. This allows you to refer to specific indexes without hard-coding the index in the script. For example:

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN location = 2
ASSIGN currentHero = heroes[location]
ASSIGN nextIndex = heroes.count() + 1
ASSIGN heroes[nextIndex] = "Roland"

The value of currentHero in this example is Sir Gawain. The last two lines of the above example show using a variable as the index on the left side of the ASSIGN statement. It also demonstrates using the count() function to return the number of elements in the array. This information is used to add a new element in the next empty index.

When you use a variable for the index number, you don't need to use curly brackets around the variable name. The script expects a numeric value between the square brackets in the array name. It assumes that anything that is not a number is a variable, so it looks for a variable by that name. There must be a corresponding variable declaration where you assign a numeric value. If there isn't one it results in the following error :

_ERR=In Snippet line 12: Array index must be >= 1.

If the Error branch for the Snippet action is connected, the script takes it when this error occurs.

Use FOREACH with a String Array

You can use a FOREACH statement with string arrays to iterate through each element.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
 FOREACH elem IN heroes 
{
   ASSIGN aName = elem 
}

In this example, elem and aName update with each iteration. The elem variable holds the current element that the FOREACH loop is processing. The script updates aName with the contents of elem. At the end of each iteration, elem and aName hold the same value, but in the middle of the iteration, elem holds the new value and aName the old value (or no value, in the case of the start of the first iteration).

You can see this clearly in the FOREACH Loop with a String Array snippet in the Array Examples script. To see the way the variables update, step through the snippet line by line.

Use FOR with a String Array

You can use a FOR loop with a string array to iterate through the array and perform a defined action a set number of times.

ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth|Lancelot"
FOR i = 1 TO heroes.count 
   {    
      item = "{heroes[i]}" 
   }

The result of this example is that Item updates upon each iteration of the FOR loop with the contents of the heroes array at the index location specified by the value of i. The FOR loop stops iterating after it reaches the end of the string array, as indicated by heroes.count.

You can see this loop in the FOR Loop with a String Array snippet in the Array Examples script.

Use Functions with Arrays

You can use functions with arrays. Use the name of the array with the index in square brackets, then add the function name using dot notation. This is shown in the following example:


ASSIGN heroes = "Beowulf|Sir Gawain|Byrhtnoth"
ASSIGN miniHero = "{heroes[2].lower}"
ASSIGN yellyHero = "{heroes[2].upper}"

The results of this example are miniHero = sir gawain and yellyHero = SIR GAWAIN.

Not all functions work with all arrays. Some only work with certain types of values. Verify the types that the function you want to use works with.

You can use functions with dynamic arrays. However, depending on the specific dynamic array and what it contains, you may need to use special object property .$value. Some functions won't work on an entire object. For example, you cannot use the lower() function on an array of objects. The script would ignore the function if you attempted this. In these cases, you must apply workarounds. For example, you can copy specific values from the objects in the array to a separate variable. You can then use lower() on the contents of the variable, and if needed, copy the converted value back into the object.

The functions in the following table are designed specifically to work with arrays. You test these functions in the Functions and Arrays snippet in the Array Examples script.

Function	Description
count()	Returns the number of elements in an array or object.
index(indexValue)	Returns the array element from the variable's contents according to the specified indexValue.
indexof(text)	Returns the character position of the specified text within a variable's contents.
size()	Returns the number of elements in an array.
split(delimiter)	Converts the contents of a variable into a pipe-delimited string that can be treated as an array. Replaces the existing, specified delimiter with a pipe character.