Returns an element in a list, or a specified default value if the requested element is undefined.
SET $LISTGET
When used on the left side of the equal sign in a SET command, the $LISTGET function extracts multiple elements from a list as a single operation. The syntax is as follows:
SET $LISTGET(var1,var2,...)=list
The var arguments of SET $LISTGET 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 $LISTGET assigns it a value.
-
The number of var arguments may be less than or greater than the number of list elements. Unspecified var values are assigned the null string value: if previously defined, the prior value is replaced with the null string; if previously undefined, the variable is defined. Compare this behavior with SET $LISTBUILD. 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 be set to the null string: if previously defined, the prior value is deleted; if previously undefined, the variable is defined. Compare this behavior with SET $LISTBUILD.
SET $LISTGET 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 $LISTGET extracts the first two elements from a list into two variables:
SET colorlist=$LISTBUILD("red","blue","green","white")
SET $LISTGET(a,b)=colorlist
WRITE "a=",a," b=",b /* a="red" b="blue" */
In the following example, SET $LISTGET extracts elements from a list into five variables. Because the specified list does not have a 5th element, the corresponding var variable (e) is defined, with a value of the null string (""):
SET (a,b,c,d,e)=0
SET colorlist=$LISTBUILD("red","blue","green","white")
SET $LISTGET(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= */
In the following example, SET $LISTGET extracts elements from a list into four variables. Because the specified list does not have a 3rd element, the corresponding var variable (c) is defined with a value of the null string (""):
SET (a,b,c,d)=0
SET colorlist=$LISTBUILD("red","blue",,"white")
SET $LISTGET(a,b,c,d)=colorlist
WRITE "a=",a," b=",b," c=",c," d=",d
/* a="red" b="blue" c= d="white" */
In the following example, SET $LISTGET 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 $LISTGET(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
The $LISTGET functions in the following example return the value of the list element specified by position (the position default is 1):
SET list=$LISTBUILD("A","B","C")
WRITE !,$LISTGET(list) ; returns "A"
WRITE !,$LISTGET(list,1) ; returns "A"
WRITE !,$LISTGET(list,3) ; returns "C"
WRITE !,$LISTGET(list,*) ; returns "C"
WRITE !,$LISTGET(list,*-1) ; returns "B"
The $LISTGET functions in the following example return a value upon encountering the undefined 2nd element in the list. The first two returns a question mark (?), which the user has defined as the default value. The second two returns a null string because the user has not specified a default value:
WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2,"?"),!
WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1,"?"),!
WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2),!
WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1)
The following example returns all of the element values in the list. It also lists the positions before and after the ends of the list. Where a value is non-existent, it returns the default value:
SET list=$LISTBUILD("a","b",,"d",,,"g")
SET llen=$LISTLENGTH(list)
FOR x=0:1:llen+1 {
WRITE "position ",x,"=",$LISTGET(list,x," no value"),!
}
WRITE "end of the list"
The following example returns all of the element values in the list in reverse order. Where a value is omitted, it returns the default value:
SET list=$LISTBUILD("a","b",,"d",,,"g")
SET llen=$LISTLENGTH(list)
FOR x=0:1:llen {
WRITE "position *-",x,"=",$LISTGET(list,*-x," no value"),!
}
WRITE "beginning of the list"
The $LISTGET functions in the following example return the list element value of the null string; they do not return the default value:
WRITE "returns:",$LISTGET($LB(""),1,"no value"),!
WRITE "returns:",$LISTGET($LB(""),*,"no value"),!
WRITE "returns:",$LISTGET($LB(""),*-0,"no value")
The $LISTGET functions in the following example all return the default value:
WRITE $LISTGET("",1,"no value"),!
WRITE $LISTGET($LB(),1,"no value"),!
WRITE $LISTGET($LB(UndefinedVar),1,"no value"),!
WRITE $LISTGET($LB(,),1,"no value"),!
WRITE $LISTGET($LB(,),*,"no value"),!
WRITE $LISTGET($LB(,),*-1,"no value"),!
WRITE $LISTGET($LB(""),2,"no value"),!
WRITE $LISTGET($LB(""),*-1,"no value")