This function adds an item to the start or end of a list or inserts it at a specified index in a list. The list can be in a field or named variable.
When inserting at a specified index, there are no invalid indexes. An index value less or equal to 0 is treated the same as adding to the start of the list. An index value greater or equal to the number of items in the list is treated the same as adding to the end of the list.
The delimiter used to separate the item being added from the destination cannot be empty. If the delimiter resolves to be empty when the action is executed, a default (\~) will be assumed.
By default, when adding to a list in a named variable, only one item is added regardless of the number of files being processed. You can override this behaviour and force all files to be enumerated by specifying the Enumerate all files option. This only has an effect when executing stepwise.
You can optionally specify that an item should only be added if it is not empty.
You can also specify that an item should only be added to the list if it is not already present anywhere in the list. This match can be case insensitive and/or diacritic insensitive. When case or diacritic insensitive is enabled, it is possible that a matching item in the list has a different representation than the item you specified to add. If you enable the Replacing option, the first matched item in the list will be replaced with the add item. If you enable the All option, all existing occurrences will be replaced with the add item.
All text fields may contain any of the escape sequences described in Escape Sequences.
Note that where running stepwise all text fields, with the exception of the data field, are only processed for escape characters once based on the contents of the first file.
There is no way to differentiate between an empty list and a list which contains an element which is empty. In Yate there is no means of having a list which contains a single empty item. Typically this is not a problem. However, if you are going to successively add items to a list, any of which can be empty, this can be an issue. For example if a list is empty and you successively add three empty items, the list will still be empty. If this is a potential issue set the list to a non empty item before you start the adds and then remove the first item.
Set named variable 'test' to "X"
Add "" to the end of the list in named variable 'test' delimiter "⏎"
Add "" to the end of the list in named variable 'test' delimiter "⏎"
Add "" to the end of the list in named variable 'test' delimiter "⏎"
Remove the item at index "0" from the list in named variable 'test' delimiter "⏎"
The above example results in test being set to ⏎⏎ which is three empty items.