This function tests if a list in a field or named variable, with a specified delimiter, has an item equalling, containing, starting with or ending with specified data.
The comparison operation may be performed case insensitive and/or diacritic insensitive.
If the trimmed option is set, leading spaces in the lists and in the match against data fields will be ignored at runtime.
All text fields may contain any of the escape sequences described in Escape Sequences. All fields are reevaluated whenever appropriate.
If the Remove option is specified, the first matched item will be removed from the list.
If trimmed is specified the new list will have the trimmed values.
If the Save index to option is specified, the index of the first matched item will be saved to the specified track or named variable. Note the result will be set to empty if no match is made. If you also specify the Save all indexes option, all matching indexes will be saved as opposed to only the first. The saved value is a list using the default list delimiter (\~) to separate the indexes. Note that when Remove is enabled, the returned index or indexes reflect the original indexes before the items were removed. Note that if the statement is processing more than one file it makes no sense to save the indexes to a named variable unless escape sequences are used to differentiate them for each file.
If the Save item to option is specified, the matched item will be saved to the specified track or named variable. Note the result will be set to empty if no match is made. This is typically only useful when testing if the data is contained. Note that if the statement is processing more than one file it makes no sense to save the item to a named variable unless escape sequences are used to differentiate them for each file.
If the delimiter resolves to be empty when the action is executed, a default (\~) will be assumed.
The following special considerations apply:
When a list is in a named variable, unless the per file test option is set, the operation is only performed once. per file test is a somewhat escoteric option which only makes sense if your want to evaluate items using escape sequences on a per file basis. This setting will rarely be needed.
When the function is being executed on a per file basis, ie. the list is either not in a named variable or per file test is enabled, you can elect to specify that the result should effectively be true if any file results in true. If the Any setting is not enabled, the result will effectively be true only if all files are true.
The result of the test can be Set, Anded or Ored into the action test state. When the function is being executed on a per file basis you can also save the result to a specified track variable. The result will be Set, Anded or Ored.
Example: Assume the Artist field contains a list of artists separated by commas. You want to ensure that the Album Artist, if present in the list always comes first. Further, you want to ensure that every comma is followed by a space. The following action will implement the desired functionality:
Test if any list in field Artist delimiter "," has an item containing case and diacritic insensitive
trimmed "\[Album Artist]", remove (Set test state and Variable 1)
if Variable 1 is true
Add "\[Album Artist]" to the start of the list in field Artist delimiter ","
endif
Build List with delimiter ", " in field Artist from field Artist (As found)
(case and diacritic insensitive) string delimiter ",", grouped