|element||Any expression or comma-separated list of expressions. To include a comma within an element, make the element a quoted string.|
ListBuild takes one or more expressions and returns a list with one element for each expression.
Omitting an element expression yields an element whose value is undefined. For example, the following ListBuild statement produces a three-element list whose second element has an undefined value; referencing the second element with the List function will produce a Null Value error.
Invoking the ListBuild function with no arguments returns a list with one element whose data value is undefined.
An element of a list may itself be a list. For example, the following statement produces a three-element list whose third element is the two-element list, “Walnut,Pecan”:
MyList = ListBuild("Apple","Pear",ListBuild("Walnut","Pecan")) Println List(MyList,3)
Note that multi-element lists contain non-printing list encoding characters.
The result of concatenating two lists with the Binary Concatenate operator is another list. For example, the following two ListBuild statements produce the same list, “A,B,C”:
x = ListBuild("A","B") & ListBuild("C") y = ListBuild("A","B","C") If x=y Then Println "Lists are identical" Else Println "Lists not identical" End If
However, concatenating a string to a list does not create a valid list.
ListBuild uses an optimized binary representation to store data elements. For this reason, equivalency tests may not work as expected with some list data. Data that might, in other contexts, be considered equivalent, may have a different internal representation. For example, ListBuild(1) is not equal to ListBuild(“1”). This is shown in the following example:
x = ListBuild("1","2") y = ListBuild(1,2) If x=y Then Println "Lists are identical" Else Println "Lists not identical" End If
A Caché list can also be created using the ListFromString function, or extracted from another list using the List function.
The following examples demonstrates how to use the ListBuild function:
myList = ListBuild("Red","Blue","Green","Yellow") color4 = List(myList,4) 'returns value of the 4th element Println color4 sublist = List(myList,2,3) 'returns the 2nd and 3rd elements as a list Println List(sublist,1) 'prints Blue
Because multi-element lists contain non-printing list encoding characters, Println should only be used to display single list items.