Caché Basic Reference
ListBuild
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Creates a list of elements.
Synopsis
ListBuild(element[,element][,element][...])
Arguments
element Any expression or comma-separated list of expressions. To include a comma within an element, make the element a quoted string.
Description
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.
Println List(ListBuild("Red",,"Green"),2)
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.
Examples
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.
See Also