List type

A variable of type list collects a set of integral type values. The list type is an abstract data type and you cannot use a list variable directly with the standard C unary or binary operators.

You can use the following operations for the list type:

• A constructor function, list() to create a new list variable if its not defined before, if the variable is already defined - it should be cleared.
• A concatenation function, append to add an item to the list or to join two lists together.
• The "=" operator that allows a list to be assigned to another.
• A set of aggregation functions that operate on a list variable and return a scalar (integer) value like sum, avg, min, max and so on.

Although, you can use a list variable to collect any integral value, the values are always saved as 64-bit signed integers.

The list() function returns a new empty new list which must be assigned to a variable of list type. This will create a new variable of type list if the list variable on the left-hand side of the assignment operator had not been previously assigned to a list. It may also be assigned to an existing list variable in which case, any values collected in the target list are discarded. Further, a variable can be declared to be of type list by declaring it as follows anywhere in the Vue script:

       __list l_opens;

The effect of this is as if the list() function was invoked in the @@BEGIN probe and the return value assigned to this list variable.

The following example creates a new list variable called l_opens:

l_opens = list();

The list function can be invoked from any clause. If you specify an existing list name when invoking the list function, the existing list is cleared.

You can use theappend() function to add a value to a list variable. Each call to the append function adds a new value to the set of values already saved in the list variable. The following example shows how the size of the list variable grows with each call to the append function:

	append(l_opens, n_opens1); /* l_opens = {n_opens1} */ 
	append(l_opens, n_opens2); /* l_opens = {n_opens1, n_opens2} */ 
	append(l_opens, n_opens3); /* l_opens = {n_opens1, n_opens2, n_opens3} */ 
	append(l_opens, n_opens4); /* l_opens = {n_opens1, n_opens2, n_opens3, n_opens4} */ 

The second parameter to the append() function can also be a variable of type list which will append all its values to the target list specified by the first parameter. So append can also be used to join two lists.

In the following example, the contents of list b are added to list a:

a=list()
b=list()
append(a,b)

You can also use append to join two lists. The first argument is the target list and the second is the list source list. In the following example, the contents of list b are added to list a:

a=list()
b=list()
append(a,b)

The append() function has no return value.

A list can be assigned to another list using the assignment operator. The original values in the target list are destroyed. In the following example, the contents of the l_opens2 list are lost (the items are removed) and the contents of the l_opens list are copied over to the l_opens2 list.

	l_opens2 = list(); 
	append(l_opens2, n_opens5); 

	l_opens2 = l_opens; 
   /* l_opens and l_opens2 => {n_opens1, n_opens2, n_opens3, n_opens4}  */ 

The aggregation functions can be applied on a list variable as shown in the following examples:

	/* below we assume n_opens1=4, n_opens2=6, n_opens3=2 and n_opens4 = 4
	 * at the time they were added to the l_opens list variable 
	 */ 
	x = avg(l_opens); /* this will set x to 4 */ 
	y = min(l_opens); /* this will set y to 2 */ 
	z = sum(l_opens); /* this will set z to 16 */ 
	a = count(l_opens) /* this will set a to 4 */ 

A list variable is useful when accurate aggregate values need to be recorded. List variables are updated atomically, so use them only when required, as they are less efficient than regular variables.