Most list manipulation functions have two forms depending upon whether the name attribute is included in the function element:
If included in the function element, the name is expected to resolve to a variable containing a list. In this case, the referenced variable is destructively modified. The following example modifies the list stored in the someList variable and adds two elements:
<append name=’someList’> <s>Hello</s> <s>World</s> </append>
If the name is not included in the function element, a new list is constructed. In the following example, a new list is created by combining the elements of the list stored in the someList variable with two additional elements. The value of the someList variable is not modified.
<append> <ref>someList</ref> <s>Hello</s> <s>World</s> </append>
Use the following functions to manipulate list elements.
Appends a value to a list. The argument list takes one of two forms depending on the presence of the name attribute. If name is not specified, then the first argument must be a list and the remaining arguments are elements to append to that list. A copy of the list is returned, the original list is not modified. If the name argument is used, then all arguments are considered objects to be appended to the list contained in the variable with that name. The list is modified without being copied.
The following expression makes a copy of the list contained in the variable srclist then appends one element.
<append> <ref>srclist</ref> <s>oranges</s> </append>
The following expression modifies an existing list by appending a value.
<set name= ’somelist’> <List> <s>We</s> <s>say</s> </List> </set> <append name= ’somelist’> <s>Hello</s> <s>World</s> </append> <ref>someList</ref>
Merges the elements in multiple lists. If the name attribute is specified, an existing list is modified. Otherwise, a new list is created.
The following expression creates a new list by combining the elements in srclist with three additional elements.
<appendAll> <ref>srclist</ref> <list> <s>apples</s> <s>oranges</s> <s>peaches</s> </list> </appendAll>
The following expression adds three elements to the list stored in the variable srclist.
<appendAll name=’srclist’> <list> <s>apples</s> <s>oranges</s> <s>peaches</s> </list> </appendAll>
first argument– list or string
second argument– any object to search for in the list or a substring to search for in the string
This function returns:
1 -- list contains a given value or the string contains the given substring
The following expression returns 1.
<contains> <list> <s>apples</s> <s>oranges</s> </list> <s>apples</s> </contains>
The following expression returns 1
<contains> <s>foobar</s> <s>foo</s> </contains>
Takes two list arguments.
This function returns:
1 -- the list contains all elements contained in another list
0 (zero) -- the list does not contain all elements contained in the second list
The following expression returns 0.
<containsAll> <ref>fruitlist</ref> <list> <s>oranges</s> <s>wiper blades</s> </list> </containsAll>
first argument– list to be searched
second argument– an element or a list of elements to search for in the first list
This function returns:
1 -- first list contains any elements that are contained in a second list.
0 (zero) -- first list does not contain any elements that are contained in a second list.
The following expression returns 1.
<containsAny> <ref>fruitlist</ref> <list> <s>oranges</s> <s>wiper blades</s> </list> </containsAny>
Filters duplicate elements from a list. Given a list, it returns a new list in which duplicate entries have been removed.
<filterdup> <list> <s>apples</s> <s>oranges</s> <s>apples</s> </list> </filterdup>
This expression returns the following list.
<list> <s>apples</s> <s>oranges</s> </list>
You can also use this function to manipulate an existing list rather than creating a new list.
<filterdup name = ’namedlist’/>
Filters null elements from a list.
This function returns a single list removing all null elements (when given one list).
<filternull> <list> <s>apples</s> <null> <s>oranges</s> <null/> </list> </filternull>
This expression returns the following list.
<list> <s>apples</s> <s>oranges</s> </list>
You can also use this function to manipulate an existing list rather than creating a new list.
<filternull name = ’namedlist’/>
Returns the string value of the subexpression with $() variable references expanded.
<expand><s>$(sample)</s></expand>
Retrieves the value of the nth element in the list. The list indexes starts count from zero (0). Arguments are a list and an integer.
<get> <list> <s>apples</s> <s>oranges</s> </list> <i>1</i> </get>
This expression returns <s>oranges</s>
first argument– a list value to search
second argument– value for which to search
third argument– (optional) starting index
This function returns either the ordinal position of a list element that matches a given value or -1 (the given value is not in the list).
The following expression returns 1.
<indexOf> <list> <s>apples</s> <s>oranges</s> </list> <s>oranges</s> </indexOf>
The following expression returns 3.
<indexOf> <list <s>apples</s> <s>oranges</s> </list> <s>oranges</s> <i>2</i> </indexOf>
Inserts a value into the list. Elements following the insertion index down are shifted to make room for the new element.
first argument– a list to which an element is inserted
second argument– integer specifying position in the list at which to insert the new element
third argument– value to insert into the list
<insert> <list> <s>apples</s> <s>oranges</s> </list> <i>1</i> <s>wiper blades</s> </insert>
This expression returns the following list.
<list> <s>apples</s> <s>wiper blades</s> <s>oranges</s> </list>
This function can also take a named list.
<insert name=’name_of_list’> <! -- position in which to insert the list> <! -- value to insert> </insert>
<insert name=’variable name of list’> <!--the position at which to insert --> <--!the value to insert --> </insert>
Returns the number of elements in the list. You can also use this function to return the length of a string.
first argument– list or string
The following expression returns 2.
<length> <list> <s>apples</s> <s>oranges</s> </list> </length>
<length> <s>Hello world!</s> </length>
This expression returns a value of 11.
Removes one or more elements from a list. The argument list takes one of two forms depending on the presence of the name attribute. If name is not specified, then the first argument must be a list and the remaining arguments are elements that are removed from that list. A copy of the list is returned. (The original list is not modified.) If the name argument is used, then all arguments are considered objects to be removed from the list contained in the variable with that name. The list is modified without being copied.
The following expression makes a copy of the list contained in the variable srclist, then removes one element and returns the copy of the list.
<remove> <ref>srclist</ref> <s>oranges</s> </remove>
The following expression modifies an existing list by removing a value.
<set name= ’somelist’> <List> <s>We</s> <s>say</s> </List> </set> <remove name= ’somelist’> <s>say</s> <s>say</s> </remove> <ref>someList</ref>
Removes all elements contained in one list from another list. If the name attribute is specified, an existing list is modified. Otherwise, a new list is created.
The following expression creates a new list by removing the elements in srclist along with three additional elements.
<removeAll> <ref>srclist</ref> <list> <s>apples</s> <s>oranges</s> <s>peaches</s> </list> </removeAll>
The following expression removes three elements in the list stored in the variable srclist.
<removeAll name=’srclist’> <list> <s>apples</s> <s>oranges</s> <s>peaches</s> </list> </removeAll>
This expression results in the following list.
<list> <s>wiper blades</s> </list>
Computes the intersection of two lists, and returns elements contained in both lists.
This function has two variants.
Sets a named list to an intersection of it and the another list.
<retainAll name=’variable name of list’> <!-- the other list--> </retainAll>
Returns the intersection of two lists.
<retainAll> <!-- the first list> <!-- second list--> </retainAll>
Assigns a value into a specified position in a list, overwriting its current value. If necessary, the list is extended to contain the indexed element. New elements created during list extension will be null.
first argument– list
second argument– integer specifying position in the list at which to insert the new element, starting with zero.
third argument– element
<setlist> <list> <s>apples</s> <s>oranges</s> <s>wiper blades</s> </list> <i>2</i> <s>bassoons</s> </setlist>
This expression results in the following list and returns null.
<list> <s>apples</s> <s>oranges</s> <s>bassoons</s> </list>
<setlist> <list> <s>apples</s> <s>oranges</s> <s>wiper blades</s> </list> <i>5</i> <s>bassoons</s> </setlist>
This expression results in the following list and returns null.
<list> <s>apples</s> <s>oranges</s> <s>wiper</> </null> </null> <s>bassoons</s> </list>