List manipulation is one of the most powerful abilities in Yate's action suite. A list by itself is a nebulous concept as any field or named variable can be considered a list. In most list action statements, the delimiter or delimiters used in the list can be set. Most list statements provide default list delimiters which vary depending on the function. The default list delimiters were chosen more for the unlikelihood of them naturally occurring in data as opposed to any aesthetic reasons. The default list delimiters are available as escape sequences so that you do not have to hard code them in statements.
The default list delimiters and their associated escape sequences are as follows:
In all list statements, list indexes are zero based. ie. the first item is at index zero.
The easiest way to construct a list is via the Build List statement. The statement allows you to construct a list ordering the components in a variety of ways. It also enforces the uniqueness of items in the final list. For example to create a sorted list of all unique artists in selected tracks where each track may have more than one artist separated by the multi value delimiter:
When executing stepwise and the source is a field, the Build List statement can selectively process only those files which have a track variable containing a value of true (a non zero integer value).
Adding items to a list is done via the Add to List statement. Typically you add to the end of a list, but the statement can also add to the start or even insert and item at a specified index.
You can use the Count Items statement to determine the number of items in a list. The statement can count the items based on a single string delimiter or based on multiple characters which are delimiters.
The List Contains Test statement can be used to determine if a list contains an item. It can also be used to remove an item and to return its index in the list. You can even perform contained tests for an item and optionally return the matched item.
If you want to remove an item you can use the above statement as discussed or if you know its index in the list you can use a Remove Lists Item at Index statement.
The Set List Index statement can be used to an items at a specific index in a list.
The List Combine statement is used to perform operations on two lists. It can produce the union or intersection of two lists and can be used to remove all items in one list from another. Without operating on multiple items as in the Build List statement, this statement can also force a set to contain only unique items. This statement is a useful means of adding an item to a list only if is not already in the list. Simply think of the item being combined as a list with one item. For example:
Assuming that Item to be Added does not contain a ⏎ character, you will be ading a single item to My List if it is not already present.
Lists can be sorted by the Sort List statement.
Yate also provides the ability to main a list in which you read/write individual elements based on a key. Think of these as Mac property lists or Windows ini files. A Yate key-value list is simply a list with two columns where the List Key statement interprets the first column as a key and the second column as a value. Using this statement you can get or set the value of any key. You can also remove an item based on the key. key-value lists can be constructed with keys and values obtained from fields with the Build Key List statement.
If you want a list of all keys or values in such a list, you can use the List from Column statement to produce yet another list containing only keys or values. Remember that the keys are in column 0 and the values are in column 1.
All lists can be used to successively call an action for every element in the list via a Repeat With statement.