...

Function: addElement()

Adds a value to the end of a list and returns the list. If the list provided is empty (that is, list is the empty list [ ], or the value  _NULL ), the list returned will contain a single value: [value].

Syntax

addElement(list, value)

Examples

addElement([ ], 4)

Adds 4 as a new entry in an empty list, and returns the result: [ 4 ].

addElement($list, $value)

Adds $value as a new entry at the end of $list, and returns the list. If the list provided is empty (that is $list is the value _NULL ), the list returned will contain a single value $value. 

Often it is helpful to iterate over an existing list in order to build a new list, as in the following example:

forEach($name, in.name, 
	if ($name != _NULL, 
		addElement($usableNames, $name) 
	)
)

Using the forEach function we go through every name provided in the variable in.name. We want to get a list of all the names which are not null, so for each one we test the value using the condition $name != _NULL. If the name is not null, we add it to a list called $usableNames using addElement().

ifNull(in.rate, addElement($errors,"Missing rate value"))

If in.rate is not found then an error message is added to a list of errors found so far. This An If() condition is a useful way of building up a list of problems which are found as a stream table is processed, which can then be formatted into a list of errors recorded on a Stream.

listToString() can be used to format a list (of errors, say) into a string that can be recorded in a string-valued field on a record. Given a list like:

$errors = ["Bad input", "Missing rate value"],

the expression

listToString($errors, "\n") and listToString($errors, ", ") 

will generate output strings like:

"Bad input

Missing rate value"

and

"Bad input, Missing rate value" 

respectively.

See Also

• Functions
• Array Handling Functions
• ScriptingExpressions and PhixScripts