Array functions

This section contains brief descriptions of the functions that return information about a specified array.

Function What it does
arraytostring Given array data, the beginning pattern, the ending pattern, and the separator, returns a string.
elementcount Returns the number of non-null or non-empty elements in an array.
nextelement Given an array field and an index into the array, returns the next non-empty and non-null entry, or zero if none is available.

elementcount

Returns the number (integer) of non-null or non-empty elements in the array. Note that sizeof (<array_field>) returns the current size of the array, but some of the elements might be empty or null entries in the array. For attachment arrays, the empty attachment is considered empty.
elementcount(array_field)
where array_field is the data field that contains the source data.
Some examples are:
A = ("", , "", "alpha", ,"") => elementcount(A) = 1; sizeof (A) = 6
B = (0 , , 0 , 100    , , 0) => elementcount(B) = 4; sizeof (B) = 6

Note that an empty string is not counted in string arrays, but every number is counted in numeric arrays. In other words, there are no empty numbers.

This function is useful to handle participant and attachment arrays.

nextelement

Given an array field and an index into the array, this function returns the next non-empty and non-null entry or zero if none is available. If the integer expression is zero, it returns the first non-empty non-null element.
nextelement(array_field, index_expr)
where:
Table 1. Table of parameters and description for the nextelement function
Parameter Description
array_field    The data field that contains the source data.
index_expr The index that should be used to start the search. If it is zero, then it will start the search from the beginning of the array.
For example, using the arrays
A = ("", , "", "alpha",,"")          B =(0 , , 0 , 100    , , 0)

nextelement (A, 0) = 4
nextelement (A, 4) = 0

nextelement (B, 0) = 1
nextelement (B, 1) = 3
nextelement (B, 3) = 4
nextelement (B, 4) = 6
nextelement (B, 6) = 0
Note: Process array indexes start at one, but index zero is used to search for the first non-empty, non-null element.

This function is useful to handle participant and attachment arrays.

arraytostring

This function converts array data to a string.
arraytostring(array_field, begin_expr, end_expr, separator_expr)
where:
Table 2. Parameters and description for arraytostring function
Parameter Description
array_field    The data field that contains the source data.
begin_expr The text string that marks the beginning of the array.
end_expr The text string that marks the end of the array.
separator_expr The text string that is used to separate the elements in the array.
For example, given data field MyStringArray with content {1,2,3}, you would use the following command to return string data:
  • arraytostring(MyStringArray, "{ ", " }", ",") returns { 1,2,3 }
This function can be used to return a string from an array of data fields in an XML schema in MyXMLField.
arraytostring(MyXMLField, ("<tag><value>", "</value></tag>", "</value><value>")
Schema example