Builds a list of elements from the specified expressions.
SET $LISTBUILD
When used on the left side of the equal sign in a SET command, the $LISTBUILD function extracts multiple elements from a list as a single operation. The syntax is as follows:
SET $LISTBUILD(var1,var2,...)=list
The var arguments of SET $LISTBUILD are a comma-separated list of variables, each of which is set to the value of the list element in the corresponding position. Thus, var1 is set to the value of the first list element, var2 is set to the value of the second list element, and so forth. The var arguments do not have to be existing variables; the variable is defined when SET $LISTBUILD assigns it a value.
-
The number of var arguments may be less than or greater than the number of list elements. Unspecified var values retain their prior value; if previously undefined they remain undefined. Compare this behavior with SET $LISTGET. Excess list elements are ignored.
-
The var arguments and/or the list elements may contain omitted values, represented by placeholder commas. An omitted var argument is undefined. An omitted list element causes the corresponding var value to retain its prior value; if previously undefined it remains undefined. Compare this behavior with SET $LISTGET.
SET $LISTBUILD is an atomic operation. The maximum number of var arguments in a compiled program is 1024. The maximum number of var arguments when executed from the Terminal is 128. Attempting to exceed these limits results in a <SYNTAX> error.
If a var argument is an object property (object.property) the property must be multidimensional. Any property may be referenced as an i%property instance variable within an object method.
In the following examples, $LISTBUILD (on the right side of the equal sign) creates a list with four elements.
In the following example, SET $LISTBUILD extracts the first two elements from a list into two variables:
SET colorlist=$LISTBUILD("red","blue","green","white")
SET $LISTBUILD(a,b)=colorlist
WRITE "a=",a," b=",b /* a="red" b="blue" */
In the following example, SET $LISTBUILD extracts elements from a list into five variables. Because the specified list does not have a 5th element, the corresponding var variable (e) contains its prior value:
SET (a,b,c,d,e)=0
SET colorlist=$LISTBUILD("red","blue","green","white")
SET $LISTBUILD(a,b,c,d,e)=colorlist
WRITE "a=",a," b=",b," c=",c," d=",d," e=",e
/* a="red" b="blue" c="green" d="white" e=0 */
In the following example, SET $LISTBUILD extracts elements from a list into four variables. Because the specified list does not have a 3rd element, the corresponding var variable (c) contains its prior value:
SET (a,b,c,d)=0
SET colorlist=$LISTBUILD("red","blue",,"white")
SET $LISTBUILD(a,b,c,d)=colorlist
WRITE "a=",a," b=",b," c=",c," d=",d
/* a="red" b="blue" c=0 d="white" */
In the following example, SET $LISTBUILD extracts elements from a list into four variables. Because the 3rd list element value is a nested list, the corresponding var variable (c) contains a list value:
SET (a,b,c,d)=0
SET colorlist=$LISTBUILD("red","blue",$LISTBUILD("green","yellow"),"white")
SET $LISTBUILD(a,b,c,d)=colorlist
WRITE "a=",a," b=",b," c=",c," d=",d
/* a="red" b="blue" c=$LB("green","yellow") d="white" */
Examples
Many of the examples shown here use the $LISTTOSTRING function to convert the $LISTBUILD return value for display; $LISTBUILD returns an encoded string that cannot be displayed directly.
The following example produces the three-element list "Red,Blue,Green":
SET colorlist=$LISTBUILD("Red","Blue","Green")
WRITE $LISTTOSTRING(colorlist,"^")
The following example creates a list of six numeric elements that display as "3^0^44^5.6^33^400". Note that $LISTBUILD encodes numeric element values based on an optimized binary representation, which may not be the same as canonical form. List display functions such as $LIST and $LISTTOSTRING return numeric element values in canonical form:
SET numlist=$LISTBUILD(003,0.00,44.0000000,5.6,+33,4E2)
WRITE $LISTTOSTRING(numlist,"^")
Omitting Elements
Omitting an element expression defines an encoded element, but the data value of that element is undefined.
In the following example, the $LISTBUILD statements both produce a valid three-element list whose second element has an undefined value. Omitting an element and specifying an undefined variable for an element produces exactly the same result. $LISTBUILD can take an undefined variable as a list element without generating an error and the resulting list passes the $LISTVALID test. However, referencing an undefined list element with a list function such as $LIST or $LISTTOSTRING generates a <NULL VALUE> error:
KILL a
SET list1=$LISTBUILD("Red",,"Green")
SET list2=$LISTBUILD("Red",a,"Green")
WRITE "List lengths:",$LISTLENGTH(list1)," ",$LISTLENGTH(list2),!
IF $LISTVALID(list1)=1,$LISTVALID(list2)=1 {
WRITE "These are valid lists",! }
IF list1=list2 {WRITE "and they're identical"}
ELSE {WRITE "They're not identical"}
The following example shows that an undefined element can be specified at the end of a list, as well as within a list. A list with trailing undefined elements is a valid list. However, referencing this undefined element with any list function generates a <NULL VALUE> error:
KILL z
SET list3=$LISTBUILD("Red",)
SET list4=$LISTBUILD("Red",z)
WRITE "List lengths:",$LISTLENGTH(list3)," ",$LISTLENGTH(list4),!
IF $LISTVALID(list3)=1,$LISTVALID(list4)=1 {
WRITE "These are valid lists",! }
IF list3=list4 {WRITE "and they're identical"}
ELSE {WRITE "They're not identical"}
However, the following example produces a three-element list whose second element has a data value: the empty string. No error condition occurs when referencing the second element:
SET list5=$LISTBUILD("Red","","Green")
SET list5len=$LISTLENGTH(list5)
WRITE "List length: ",list5len,!
FOR i=1:1:list5len {
WRITE "Element ",i," value: ",$LIST(list5,i),! }
Lists with No Data or Null String Data
Any list created using $LISTBUILD contains at least one encoded list element. That element may or may not contain data. Because $LISTLENGTH counts elements, not data, any list created using $LISTBUILD has a list length of at least 1.
Referencing a $LISTBUILD element whose data value is undefined generates a <NULL VALUE> error. The following are all valid $LISTBUILD statements that create “empty” lists. However, attempting to reference an element is such a list results in a <NULL VALUE> error:
TRY {
SET x=$LISTBUILD(UndefinedVar)
SET y=$LISTBUILD(,)
SET z=$LISTBUILD()
IF $LISTVALID(x)=1,$LISTVALID(y)=1,$LISTVALID(z)=1 {
WRITE "These are valid lists",! }
WRITE "$LB(UndefinedVar) contains ",$LISTLENGTH(x)," elements",!
WRITE "$LB(,) contains ",$LISTLENGTH(y)," elements",!
WRITE "$LB() contains ",$LISTLENGTH(z)," elements",!
/* Attempt to use null lists */
WRITE "$LB(UndefinedVar) list value ",$LISTTOSTRING(x,"^"),!
WRITE "$LB(,) list value ",$LISTTOSTRING(y,"^"),!
WRITE "$LB() list value ",$LISTTOSTRING(z,"^"),!
}
CATCH exp { WRITE !!,"In the CATCH block",!
IF 1=exp.%IsA("%Exception.SystemException") {
WRITE "System exception",!
WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
WRITE "Location: ",exp.Location,!
WRITE "Code: "
}
ELSE { WRITE "Some other type of exception",! RETURN }
WRITE exp.Code,!
WRITE "Data: ",exp.Data,!
RETURN
}
The following are valid $LISTBUILD statements that create a list element that contains data, though this data has a null string value:
SET x=$LISTBUILD("")
WRITE "list contains ",$LISTLENGTH(x)," elements",!
WRITE "list value is ",$LISTTOSTRING(x,"^"),!
SET y=$LISTBUILD($CHAR(0))
WRITE "list contains ",$LISTLENGTH(y)," elements",!
WRITE "list value is ",$LISTTOSTRING(y,"^")
Concatenating Lists
The result of concatenating two lists with the Concatenate operator (_) is a list that combines the two lists.
In the following example, concatenating two lists creates a list that is identical to a list with the same elements created using LISTBUILD:
SET list1=$LISTBUILD("A","B")
SET list2=$LISTBUILD("C","D","E")
SET clist=list1_list2
SET list=$LISTBUILD("A","B","C","D","E")
IF clist=list {WRITE "they're identical",!}
ELSE {WRITE "they're not identical",!}
WRITE "concatenated ",$LISTTOSTRING(clist,"^"),!
WRITE "same list as ",$LISTTOSTRING(list,"^")
You cannot concatenate a string to a list. Attempting to do so generates a <LIST> error the first time you attempt to access the result:
TRY {
SET list=$LISTBUILD("A","B")_"C"
WRITE "$LISTBUILD completed without error",!
SET listlen=$LISTLENGTH(list)
WRITE "$LISTLENGTH completed without error",!
SET listval=$LISTTOSTRING(list,"^")
WRITE "$LISTTOSTRING completed without error",!
}
CATCH exp { WRITE !!,"In the CATCH block",!
IF 1=exp.%IsA("%Exception.SystemException") {
WRITE "System exception",!
WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
WRITE "Location: ",exp.Location,!
WRITE "Code: "
}
ELSE { WRITE "Some other type of exception",! RETURN }
WRITE exp.Code,!
WRITE "Data: ",exp.Data,!
RETURN
}
For further details on concatenation, see String Concatenate (_).