List Manipulation Functions
- See also: Expression Language and Function Index
Media Center supports several different types of fields, one of them being the List type. A List type is a library field of type List, or an expression coerced into a list type.
The functions in this section provide the ability to manipulate lists and list items. A list is a sequence of strings, each separated from one another by an arbitrary delimiter. The default delimiter is a semicolon. Media Center does not make a strict distinction between a string and a list of strings. In fact, a list is just a string, and it is safe to think of a string as a list with zero or more arbitrary delimiter sequences. For example, the string "2013-08-17" can be thought of as a dash-delimited list with the three items "2013", "08" and "17".
This weak typing is very useful since a list, for example, "John; Sally" that contains the two items "John" and "Sally" can be manipulated not only using the list functions in this section, but because it is just a string, it can also be manipulated with string functions. For example, taking the same list above and combining it with the string "; Joe" adds a new item to the list "John; Sally; Joe", and removing the first 6 characters with RemoveLeft() would produce a now shortened string/list "Sally; Joe". The list manipulation functions make this job easier, especially when using the default semicolon delimiter. Furthermore, since any character or sequence of characters can be considered as a list delimiter, any string can be treated as a list, and the functions in this section can be used on any string as needed.
In some areas such as a panes column, or a category view, Media Center gives special treatment to List types. For example, using semicolon as the delimiter, a List will be automatically split apart into its individual items.
ListBuild(…)
- Constructs a list from a series of items.
| Description | listbuild(mode, delimiter, item1, item2, …)
The ListBuild() function constructs a list from item1, item2, ... using a supplied delimiter to separate the individual items in the resulting list. The construction mode affects how empty items are handled - they can be included or excluded. The mode typically used exclude empty items, so that lists do not contain empty slots. However, there are occasions when retaining empty slots is useful, such as when using a list to act like an array where data is stored in particular slots so that the ListItem() function may later retrieve values at a given index. It can also be useful when calculating several expressions and combining the results into a single list for presentation; by including all items, items can be made to line-up for visual inspection in a column. Available mode values:
The delimiter argument specifies the character or character sequence to be inserted in between items in the list. An unspecified delimiter will result in a delimiter-less concatenation of the supplied arguments item1, item2, etc. Argument delimiter is optional (defaults to EMPTY). | ||||
|---|---|---|---|---|---|
| Examples | listbuild(1, ;, Bennie, June)
Returns a standard semicolon-separated list containing two items Bennie; June. listbuild(1, \, [album artist (auto)], [album]) Builds a backslash-separated list combining the two fields album artist (auto) and album. This is useful for building panes column or categories hierarchies in a view. |
ListClean(…)
- Various list operations.
| Description | listclean(list, mode, delimiter)
The ListClean() function performs one of the operations specified by mode on the given list. The specified delimiter separates list items.
Argument delimiter is optional (defaults to SEMICOLON). | ||||
|---|---|---|---|---|---|
| Examples | listclean(c;b;c;a, 1)
Removes duplicates from the list, returning c;b;a. listclean(d;c;b;a, 2) Reverses the list items, returning a;b;c;d. listclean(\a\x\x\x\z, 1, \) Removes duplicates from a backslash-separated list, returning \a\x\z. |
ListCombine(…)
- Combines two delimited lists into a single delimited list.
| Description | listcombine(list1, list2, input delimiter, output delimiter, mode)
The ListCombine() function returns a single list after performing the operation specified by mode on the two lists list1 and list2. An input delimiter and an output delimiter may be specified. The input delimiter is effective for both list1 and list2, and the output delimiter will be used in the returned list, replacing the input delimiter from both list1 and list2. Available mode values:
Argument input delimiter is optional (defaults to SEMICOLON). Argument output delimiter is optional (defaults to SEMICOLON). Argument mode is optional (defaults to 0). | ||||
|---|---|---|---|---|---|
| Examples | listcombine(a;b;e, a;b;c;d)
Returns a;b;e;c;d. This example uses the default mode 0 to combine list1 with list2, preserving the order of items. The default ; input delimiter and output delimiter is used. listcombine(a;b;e, a;b;c;d, ;, ;, 1) Returns a;b. The input delimiter and output delimiter are both specified as ;, and mode 1 is used to produce a list of only items that exist in both list1 and list2. listcombine(a-c, c-f, -, ..., 0) Returns a...c...f. The input delimiter is -, while the output delimiter is ..., and mode 0 combines both lists. listcombine(a#@#c, c#@#f, #@#, ., 0) Returns a.c.f. This example demonstrates how to combine two lists with duplicates removed while replacing a multi-character input delimiter #@# with a single-character output delimiter .. listcombine([people], [places])&datatype=[list] The result here would be a single, semicolon delimited list containing all the list items from the [people] and [places] fields. For example, if [people] contains Family\Mum; Family\Dad; Family\Gran, and [places] contains UK\Scotland\Edinburgh; UK\Scotland\Edinburgh\Edinburgh Castle, the output list would be Family\Mum; Family\Dad; Family\Gran; UK\Scotland\Edinburgh; UK\Scotland\Edinburgh\Edinburgh Castle. Using the &datatype=[list] cast makes the expression split individual list items in a panes or categories view. |
ListCount(…)
- Returns the number of items in a list.
| Description | listcount(list, delimiter)
The ListCount() function returns the number of items that exist in a list delimited by delimiter. Argument delimiter is optional (defaults to SEMICOLON). |
|---|---|
| Examples | listcount([keywords])
Returns the number of keywords for the file. listcount([filename (path)], \) Returns the number of the directories in a Windows drive-based file path. The example demonstrates that non-List type fields can be used with the functions in this section. While the delimiter specified here is \, an escaped forward slash // could be used when applicable. |
ListItem(…)
- Returns an item from a location in a list.
| Description | listitem(list, position, delimiter)
The ListItem() function returns the item from the specified position in the list. Items in a list are zero-based, so the first item in the list is located at position 0. Nothing is returned with the position is outside the bounds of the list. Argument delimiter is optional (defaults to SEMICOLON). |
|---|---|
| Examples | listitem(a;b;c, 1)
Returns b, since position 1 is the second item in the list a;b;c. listitem(1:04:47, 2, :) Using the delimiter :, returns item at position 2, which is the seconds value 47 from the time 1:04:47. |
ListSort(…)
- Sort a list of values.
| Description | listsort(list, mode, delimiter)
The ListSort() function sorts a list in the order according to mode, using the specified delimiter. Available mode values:
Argument mode is optional (defaults to 0). Argument delimiter is optional (defaults to SEMICOLON). | ||||
|---|---|---|---|---|---|
| Examples | listsort(c;a;b)
Returns a;b;c, using the default ascending mode and (:) delimiter. listsort(Joe Baxter/, Sally Henson/, Sue Smith, 1, /,) Returns Sue Smith,Sally Henson,Joe Baxter. Note the requirement to escape the , characters within the list string and in the specified delimiter itself. listsort([artist];[composer]) Sorts the combined artist and composer lists in ascending order. Note the simple manual construction of a single List by combining the two List type fields, and forcing a ; between the two. |
ListLimit(…)
- Caps the number of items in a list.
| Description | listlimit(list, limit, start)
The ListLimit() function caps the number of items in a list.ca Argument limit defines the number of items to cap at. You can use negative numbers to return items from the end of a list. Argument start optionally defines the start item. |
|---|---|
| Examples |
listlimit(a;b;c,1,0) Returns a. listlimit(a;b;c,-1,0) Returns c. |
ListEqual(…)
- Checks for equality between two lists.
| Description | listequal(list 1, list 2)
The ListEqual() function checks for equality between two lists. Argument list 1 defines the first list. Argument list 2 defines the second list. |
|---|---|
| Examples |
listequal(a;b;c,a;b;c) Returns 1. |
ListContains(…)
- Checks for a value being in a list.
| Description | listcontains(list, value, flags)
The ListContains() function checks for a value in a list. Argument list defines the list. Argument value defines the value to search for. Argument flags defines the search flags. 1 for case sensitive. 2 for full match only |
|---|---|
| Examples |
listcontains(a;b;c,a) Returns 1. |
ListShuffle(…)
- Shuffles a list.
| Description | listshuffle(list)
The ListShuffle() function shuffles the given list. Argument delimiter is optional (defaults to SEMICOLON). |
|---|---|
| Examples | listshuffle(c;b;a)
Shuffles the list, returning some arrangement of the letters. |