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: 0 Include empty values 1 Exclude empty 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.

(Back to top)

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. 1 Remove duplicates 2 Reverse the order of 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.

(Back to top)

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: 0 Combine lists removing duplicates (order is preserved). 1 Output only items contained in both lists (order is preserved). 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.

(Back to top)

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.

(Back to top)

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.

(Back to top)

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: 0 Ascending sort 1 Descending sort 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.

(Back to top)

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.

(Back to top)

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.

(Back to top)

ListContains(…)

Checks for a value being in a list.

Description	listequal(list 1, list 2) 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.
Examples	listequal(a;b;c,a;b;c) Returns 1.

(Back to top)