Examples of Returning Elements with $LIST
The following examples use the 2-argument form of $LIST to return a list element:
The following two $LIST statements return “Red”, the first element in the list. The first returns the first element by default, the second returns the first element because the position argument is set to 1:
SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
WRITE $LIST(colorlist),!
WRITE $LIST(colorlist,1)
The following two $LIST statements return “Orange”, the second element in the list. The first counts from the beginning of the list, the second counts backwards from the end of the list:
SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
WRITE $LIST(colorlist,2),!
WRITE $LIST(colorlist,*-4)
The following examples use the 3-argument form of $LIST to return one or more elements as an encoded list string. Because a list contains non-printing encoding character, you must use $LISTTOSTRING to convert the sublist to a printable string.
The following two $LIST statements return “Blue”, the fifth element in the list as an encoded list string. The first counts from the beginning of the list, the second counts backwards from the end of the list. Because the element is specified as a range, it is retrieved as a list consisting of one element:
SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
WRITE $LISTTOSTRING($LIST(colorlist,5,5))
WRITE $LISTTOSTRING($LIST(colorlist,*-1,*-1))
The following example returns “Red,Orange,Yellow”, a three-element string beginning with the first element and ending with the third element in the list:
SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
WRITE $LISTTOSTRING($LIST(colorlist,1,3))
The following example returns “Green,Blue,Violet”, a three-element string beginning with the fourth element and ending with the last element in the list:
SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
WRITE $LISTTOSTRING($LIST(colorlist,4,*))
The following example returns a list element from a property:
SET cfg=##class(%iKnow.Configuration).%New("Trilingual",1,$LB("en","fr","es"))
WRITE $LIST(cfg.Languages,2)
Examples of Replacing, Removing, or Appending Elements with SET $LIST
The following example shows SET $LIST replacing the second element:
SET fruit=$LISTBUILD("apple","onion","banana","pear")
WRITE !,$LISTTOSTRING(fruit,"/")
SET $LIST(fruit,2)="orange"
WRITE !,$LISTTOSTRING(fruit,"/")
The following example shows SET $LIST replacing the second and third elements:
SET fruit=$LISTBUILD("apple","potato","onion","pear")
WRITE !,$LISTTOSTRING(fruit,"/")
SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")
WRITE !,$LISTTOSTRING(fruit,"/")
The following example shows SET $LIST replacing the second and third elements with four elements:
SET fruit=$LISTBUILD("apple","potato","onion","pear")
WRITE !,$LISTTOSTRING(fruit,"/")
SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach","tangerine")
WRITE !,$LISTTOSTRING(fruit,"/")
The following example shows SET $LIST appending an element to the end of the list:
SET fruit=$LISTBUILD("apple","orange","banana","peach")
WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
SET $LIST(fruit,*+1)="pear"
WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)
The following example shows SET $LIST appending an element three positions past the end of the list:
SET fruit=$LISTBUILD("apple","orange","banana","peach")
WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
SET $LIST(fruit,*+3)="tangerine"
WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)
The following four examples show SET $LIST using *-n syntax to replace elements by offset from the end of the list. Note that SET $LIST(x,*-n) and SET $LIST(x,n,*-n perform different operations: SET $LIST(x,*-n) replaces the value of the specified element; SET $LIST(x,n,*-n) deletes the specified range of elements, then appends the specified list.
To replace the next-to-last element with a single value, use SET $LIST(x,*-1):
SET fruit=$LISTBUILD("apple","banana","orange","potato","pear")
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
SET $LIST(fruit,*-1)="peach"
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
To remove a single element by offset from the end of the list, use SET $LIST(x,*-n,*-n)="":
SET fruit=$LISTBUILD("apple","banana","orange","potato","pear")
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
SET $LIST(fruit,*-1,*-1)=""
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
To replace a single element by offset from the end of the list with a list of elements, use SET $LIST(x,*-n,*-n)=list:
SET fruit=$LISTBUILD("apple","banana","potato","orange","pear")
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
SET $LIST(fruit,*-2,*-2)=$LISTBUILD("peach","plum","quince")
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
To replace a single element by offset from the end of the list with a sublist, use SET $LIST(x,*-n)=list:
SET fruit=$LISTBUILD("apple","banana","potato","orange","pear")
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
SET $LIST(fruit,*-2)=$LISTBUILD("peach","plum","quince")
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
The following example shows SET $LIST removing elements from the list, beginning with the third element through the end of the list:
SET fruit=$LISTBUILD("apple","orange","onion","peanut","potato")
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")
SET $LIST(fruit,3,*)=""
WRITE !,"list length is ",$LISTLENGTH(fruit)," "
WRITE $LISTTOSTRING(fruit,"/")