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. Available mode values: 1 Remove duplicates 2 Reverse the order of items 3 Remove empty items 4 Trim (Removes any trailing delimiter) 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)

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.

(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)

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)

ListFind(…)

Returns list items containing specified text

Description

ListFind(List, Search, Default, Return Mode, Match Mode) Argument Default is optional (defaults to Empty (Returns nothing)). Argument Return Mode is optional (defaults to 0). Argument Match Mode is optional (defaults to 0). "List" is the list to be searched and can be a literal given string, library field, or nested expression result. Only semi-colon delimited lists are accepted. "Search" is the character or string you wish to locate within the "List" value. The search performed is always case insensitive. "Default" specifies what the output should be if Search is not found. "Mode" has two available values, defaulting to 0 if not specified... 0 returns the text of the found list item and 1 returns the zero-based index number of the item found in the given list. If using Mode 1, to return the list index value, and a return of -1 is desired for any "not found" results, leave the Default value empty. Available Return Mode values: 0 Return the text of the found list item 1 Return the index of the found list item Available Match Mode values: 0 Partial Matching 1 Exact Matching As already mentioned, Search is always case insensitive, even when using Match Mode "1". It begins at the start of the string, and stops when it finds the first match. If Search appears later in the list, it is not reported. When using return mode 1, the zero based list index of the first item found is returned, and if not found, the Default value is returned if specified, or, if Default is left empty, -1 is returned. This is useful for combining with other zero-based functions such as ListItem(), where the index may not be known, but can be returned using ListFind().

Examples

ListFind(Rod;Jane;Freddy, Jane) Returns: Jane In this example, Default, Return Mode and Match Mode have not been specified, and so defaults to empty, zero and zero respectively. ListFind(Rod;Jane;Freddy, Bungle) Returns: Nothing In this example, Default, Return Mode and Match Mode have not been specified, and so defaults to empty, zero and zero respectively. "Bungle" is not found, so nothing at all is returned. ListFind(Rod;Jane;Freddy, Bungle, Bungle is not in this list) Returns: Bungle is not in this list In this example, Default has been specified, and will be returned if Search is not found. Neither Mode has been specified, and so both default to zero. "Bungle" is not found, so "Bungle is not in this list" is returned as the specified default. ListFind(Rod;Jane;Freddy, Bungle, Bungle is not in this list,1) Returns: Bungle is not in this list In this example, Default has been specified, so will be used even though Return Mode 1 has been specified to retrieve the item's list index #. As "Bungle" is not found, the specified default value, "Bungle is not in this list" is returned. ListFind(Rod;Jane;Freddy, Bungle,,1) Returns: -1 In this example, Default has not been specified. Return Mode 1 has been specified to retrieve the item's list index #. As "Bungle" is not found, -1 is returned. ListFind(Rod;Jane;Freddy, Freddy,,1) Returns: 2 In this example, Default has not been specified. Return Mode 1 has been specified to retrieve the item's list index #. The list index of 2 is returned as, starting from zero, "Freddy" is the third item in the list. ListFind(Rod;Jane;Freddy, Fred,,0,1) Returns: 2 In this example, Default has not been specified. Return Mode 0 has been specified to retrieve the item's text, and Match Mode 1 has been specified, indicating and exact match is required. Nothing is returned as Fred does not feature as an exact item in the list.

(Back to top)   (Function index)

ListFormat(…)

Outputs a given list in a reader friendly format

Description

ListFormat(List, Mode) "List" is the list to be worked on and can be a literal given string, library field, or nested expression result. Only semi-colon delimited lists are accepted. "Mode" has three available values, and has no default, so, must be specified. Available mode values: 0 Return the list as-is, adding a single space after each semicolon 1 Replaces semicolons with a comma and space, adding an ampersand before the last item 2 Replaces semicolons with a comma and space, adding an ampersand without comma before the last item

Examples

ListFormat(Rod;Jane;Freddy,0) Returns: Rod; Jane; Freddy ListFormat(Rod;Jane;Freddy,1) Returns: Rod, Jane, & Freddy ListFormat(Rod;Jane;Freddy,2) Returns: Rod, Jane & Freddy

(Back to top)   (Function index)

ListGrep(…)

Returns list items containing specified text

Description

ListGrep(List, Filter, Mode) Argument mode is optional (defaults to 0). The ListGrep() function searches a given list for all items containing specified text, returning results as a semi-colon delimted list. The source list can be given literally or as an existing list type library field, such as [Keywords] Available mode values: 0 Perform a case insensitive search 1 Perform a case sensitive search

Examples

ListGrep(redneck;blue;Red roses, red) Returns: redneck; Red roses In this example, Mode has not been specified, and so defaults to zero for a case insensitive search. ListGrep(redneck;blue;Red roses, red,1) Returns: redneck In this example, Mode 1 has been specified for a case-sensitive search, so, "Red roses" is not a match.

(Back to top)   (Function index)

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). Argument position accepts negative numbers, indicating that the search be performed from the end of the list, not the start, with -1 returning the last list item..

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)

ListLimit(…)

Returns a specified number of list items

Description

ListLimit(List, Limit, Start, Delimiter) Argument Start is optional (defaults to 0). Argument Delimiter is optional (defaults to ;). "List" is the source list to be capped. "Limit" is the number of items to return from List. Negative numbers can be used here to return items from the end of the List. "Start" is optional and defaults to zero (the beginning of the list). "Delimiter" is optional and defaults to a semi-colon if not specified. Notes: If a Start value that is outside the bounds of the source list is specified, for example, start at item 10 when the list only contains nine items, the function returns a null (empty) result. Start is a zero-based index, so a start value of "1" will begin from the second list item.

Examples

ListLimit([Actors],5) Returns a semi-colon delimited list of the first five actors from the [Actors] list. ListLimit([Actors],-5) Returns a semi-colon delimited list of the last five actors from the [Actors] list. ListLimit([Actors],5,3) Returns a semi-colon delimited list of five actors from the [Actors] list, starting from the fourth item in that [Actors] list.

(Back to top)   (Function index)

ListMath(…)

Returns a specified number of list items

Description	ListMath(List, Mode) Available mode values: 0 Math function "Min" 1 Math function "Max" 2 Math function "Sum" 3 Math function "Average" Notes: List can be a mix of numeric and textual items. Any textual list items are evaluated as zero.
Examples	ListMath(1;two;2;three;3;4;5,0) Returns zero as the words "two" and "three" evaluate to zero. ListMath(1;two;2;three;3;4;5,1) Returns 5. ListMath(1;two;2;three;3;4;5,2) Returns 15. ListMath(1;two;2;three;3;4;5,3) Returns 2.142857 (15/7)

(Back to top)   (Function index)

ListMix(…)

Combine corresponding values from multiple lists into a new list, using a template to process each item.

Description

ListMix(template, mode, list1, [list2, ... listN]) Argument mode is optional (defaults to 0). The ListMix() function processes the elements of one or more lists, returning a new list where each element is similar to the provided template modified with the elements of the list argument(s). The number of list arguments to be mixed is variable, but at least one must be provided. The lists can have different lengths, with mode controlling the length of the returned list. The first element of the returned list is generated by applying the first element of each provided list to the template; the second element is generated using the second element(s) of the list(s), and so on until all elements are processed, according to mode. The template is a text string with placeholders like [L1], [L2], etc, indicating where the elements of the provided lists should be inserted. [L1] refers to elements of list1, [L2] refers to list2, and so on. The special placeholder [N] refers to the item number within the resulting list. A template is also itself an Expression, so it can contain other functions/expressions. A template can be escaped using the escape sequence /#template#/. This is usually not required but may be useful to enter templates containing functions, commas, or other special symbols. The default semi-colon list delimiter is used for both input and output lists. Available mode values: 0 Return as many elements as the longest provided list 1 Return as many elements as the shortest provided list 2 Return as many elements as the first provided list

Examples

ListMix(Actor #[N] is [L1],, a;b;c) Returns Actor #1 is a; Actor #2 is b; Actor #3 is c This example uses mode 0 and demonstrates the usage of [N] and [L1] on a single list. ListMix([L1][L2]=[L3], 0, a;b;c;d, 1;2;3;4;5, blue;red;green) Returns a1=blue; b2=red; c3=green; d4=; 5= Mode 0 returns 5 elements which is the length of the longest list. Note that on the last two the missing values on the template are also missing on the output. ListMix([L1][L2]=[L3], 1, a;b;c;d, 1;2;3;4;5, blue;red;green) Returns a1=blue; b2=red; c3=green Mode 1 returns only 3 elements, the length of the shortest list. ListMix([L1][L2]=[L3], 2, a;b;c;d, 1;2;3;4;5, blue;red;green) Returns : a1=blue; b2=red; c3=green; d4= Mode 2 returns only 4 elements, the length of the first list. ListMix(FixCase([L1],3)=Math([L2]*[L3]),, aa;bb;cc, 10;20;30, 5;4;3) Returns : AA=50; BB=80; CC=90 This example uses two different functions on the template to further transform each element of the lists before inserting it into the output. ListMix(<img src=tooltip:actors\[L1]>, 1, [Actors], 1;2;3;4;5) Returns (example): <img src=tooltip:actors\Daisy Ridley>;<img src=tooltip:actors\Adam Driver>;<img src=tooltip:actors\John Boyega>;<img src=tooltip:actors\Oscar Isaac>;<img src=tooltip:actors\Mark Hamill> This example transforms the [Actors] field into a list of <img> tags ready to load the actor thumbnails into the Theather View or Movie Tooltip. It uses mode 1 (shortest list) with a dummy [L2] list of 5 elements to make sure the resulting list is at most 5 items long. An alternative way to accomplish the same would be to use ListLimit([Actors],5) as [L1].

(Back to top)   (Function index)

ListRemove(…)

Removes a string from a list.

Description

ListRemove(List, String, List Item, Mode) Argument mode is optional (defaults to 0). The ListRemove() function removes a given string from a list. Available mode values: 0 Searches for a given string, removing it if found 1 Zero-based index mode, will remove the specified list item 2 Performs a substring search and remove Notes The List Item argument is only required when using Mode 1, remembering that the list items are numbered starting from zero. When using mode zero, the search performed is case insensitive When using mode zero, the string to be removed must match the whole list item, otherwise, nothing is removed. When using mode 1, the List Item zero-based number is specified in place of String. When using mode 2, wherever the specified substring is found, that entire list entry is removed. See 3rd example below.

Examples

listremove(This;Is;a;List,is) Returns "This;a;List" This example defaults to mode 0. Note that "is" in "List" and and "This" are not removed, and the search is case insensitive. listremove(a;b;c;d;e;f;g,5,1) Returns a;b;c;d;e;g Mode 1 has been specified, which is a zero-based index mode, so "f" has been removed from the list as it is the fifth list item. listremove(This;Is;a;List,is,2) Returns "a" This example uses mode 2 which performs a substring search for "is", removing This, Is and List, leaving just "a". The search is case insensitive.

(Back to top)   (Function index)

ListShuffle(…)

Shuffles a list.

Description	listshuffle(list) The ListShuffle() function shuffles the given list.
Examples	listshuffle(c;b;a) Shuffles the list, returning some arrangement of the letters.

(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)