test

Sun Identity Manager Deployment Reference

List Manipulation Expressions

Most list manipulation functions have two forms depending upon whether the name attribute is included in the function element:

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.

append Function

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.

Example 1

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>

Example 2

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>

appendAll Function

Merges the elements in multiple lists. If the name attribute is specified, an existing list is modified. Otherwise, a new list is created.

Example 1

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>

Example 2

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>

contains Function

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

Example 1

The following expression returns 1.

<contains>
   <list>
      <s>apples</s>
      <s>oranges</s>
   </list>
   <s>apples</s>
</contains>

Example 2

The following expression returns 1

<contains>
   <s>foobar</s>
   <s>foo</s>
</contains>

containsAll Function

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

Example

The following expression returns 0.

<containsAll>
   <ref>fruitlist</ref>
   <list>
      <s>oranges</s>
      <s>wiper blades</s>
   </list>
</containsAll>

containsAny Function

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.

Example

The following expression returns 1.

<containsAny>
   <ref>fruitlist</ref>
   <list>
      <s>oranges</s>
      <s>wiper blades</s>
   </list>
</containsAny>

filterdup Function

Filters duplicate elements from a list. Given a list, it returns a new list in which duplicate entries have been removed.

Example 1

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

Example 2

You can also use this function to manipulate an existing list rather than creating a new list.

<filterdup name = ’namedlist’/>

filternull Function

Filters null elements from a list.

This function returns a single list removing all null elements (when given one list).

Example

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

Example 2

You can also use this function to manipulate an existing list rather than creating a new list.

<filternull name = ’namedlist’/>

expand Function

Returns the string value of the subexpression with $() variable references expanded.

Example

<expand><s>$(sample)</s></expand>

get Function

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.

Example

<get>
   <list>
      <s>apples</s>
      <s>oranges</s>
   </list>
   <i>1</i>
</get>

This expression returns <s>oranges</s>

indexOf Function

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

Example 1

The following expression returns 1.

<indexOf>
   <list>
      <s>apples</s>
      <s>oranges</s>
   </list>
   <s>oranges</s>
</indexOf>

Example 2

The following expression returns 3.

<indexOf>
   <list
      <s>apples</s>
      <s>oranges</s>
   </list>
   <s>oranges</s>
<i>2</i>
</indexOf>

insert Function

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

Example 1

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

Example 2

<insert name=’variable name of list’>
   <!--the position at which to insert -->
   <--!the value to insert -->
</insert>

length Function

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

Example 1

The following expression returns 2.

<length>
   <list>
      <s>apples</s>
      <s>oranges</s>
   </list>
</length>

Example 2

<length>
   <s>Hello world!</s>
</length>

This expression returns a value of 11.

remove Function

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.

Example 1

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>

Example 2

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>

removeAll Function

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.

Example 1

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>

Example 2

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>

retainAll Function

Computes the intersection of two lists, and returns elements contained in both lists.

This function has two variants.

Example 1

Sets a named list to an intersection of it and the another list.

<retainAll name=’variable name of list’>
<!-- the other list-->
</retainAll>

Example 2

Returns the intersection of two lists.

<retainAll>
   <!-- the first list>
   <!-- second list-->
</retainAll>

setlist Function

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

Example 1

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

Example 2

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