Caché ObjectScript Reference
$LIST
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Returns or replaces elements in a list.
Synopsis
$LIST(list,position,end) 
$LI(list,position,end)  

SET $LIST(list,position,end)=value 
SET $LI(list,position,end)=value
Parameters
list An expression that evaluates to a valid list. Because lists contain encoding, list must be created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST. In SET $LIST syntax, list must be a variable or a multi-dimensional property.
position
Optional — An integer code specifying the starting position in list. Permitted values are n (count from beginning of list), * (last element in list), and *-n (relative offset count backwards from end of list). SET $LIST syntax also supports *+n (relative offset integer count of elements to append beyond the end of list). Thus, the first element in the list is 1, the second element is 2, the last element in the list is *, and the next-to-last element is *-1. If position is a fractional number, it is truncated to its integer part. If position is omitted, it defaults to 1.
-1 may be used in older code to specify the last element in the list. This deprecated use of -1 should not be combined with *, *-n, or *+n relative offset syntax.
end Optional — An integer code specifying the ending position of a sublist of list. Used with position. Uses the same values as position.
Description
$LIST can be used in two ways:
Returning List Elements
$LIST returns list elements. The elements returned depend on the parameters used.
Note:
$LIST should not be used in a loop structure to return multiple successive element values. While this will work, it is highly inefficient, because $LIST must evaluate the list from the beginning with each iteration. The $LISTNEXT function is a far more efficient way to return multiple successive element values.
Parameters
list
An encoded list string containing one or more elements. Lists can be created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list by using the $LIST function.
When returning an element (or elements), list can be a variable or an object property.
When $LIST is used with SET on the left hand side of the equals sign to replace an element (or elements), list can be a variable or a multidimensional property reference; it cannot be a non-multidimensional object property.
The following are valid list arguments:
   SET myList = $LISTBUILD("Red","Blue","Green","Yellow")
   WRITE !,$LIST(myList,2)   ; prints Blue
   SET subList = $LIST(myList,2,4)
   WRITE !,$LIST(subList,2)  ; prints Green
 
In the following example, subList is not a valid list argument, because it is a single element returned as an ordinary string, not an encoded list string:
   SET myList = $LISTBUILD("Red","Blue","Green","Yellow")
   SET subList = $LIST(myList,2)
   WRITE $LIST(subList,1)
In SET $LIST syntax form, list cannot be a non-multidimensional object property.
position
The position (element count) of the list element to return (or replace). A single element is returned as a string. List elements are counted from 1. If position is omitted, $LIST returns the first element.
If the end parameter is specified, position specifies the first element in a range of elements. A range of elements is always returned as an encoded list string. Even when only one element is returned (when position and end are the same number) this value is returned as an encoded list string. Thus, $LIST(x,2) is the same element, but not the same data value as $LIST(x,2,2).
end
The position of the last element in a range of elements, specified as an integer. You must specify position to specify end. If end is a fractional number, it is truncated to its integer part.
When end is specified, the value returned is an encoded list string. Because of this encoding, such strings should only be processed by other $LIST functions.
Deprecated –1 Values
In older code, a position or end value of -1 represents the last element in the list. A value of -1 cannot be used with *, *+n, or *-n syntax.
Specifying *-n and *+n Parameter Values
When using a variable to specify *-n or *+n, you must always specify the asterisk and a sign character in the parameter itself.
The following are valid specifications of *-n:
  SET count=2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LIST(alph,*-count)
 
  SET count=-2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LIST(alph,*+count)
 
The following is a valid specification of *+n:
  SET count=2
  SET alph=$LISTBUILD("a","b","c","d")
  SET $LIST(alph,*+count)="F"
  WRITE $LISTTOSTRING(alph,"^",1)
 
Whitespace is permitted within these parameter values.
$LIST Errors
The following $LIST parameter values generate an error:
Replacing Elements Using SET $LIST
When $LIST is used with SET on the left hand side of the equals sign, list can be a valid variable name. If the variable does not exist, SET $LIST defines it. The list parameter can also be a multidimensional property reference; it cannot be a non-multidimensional object property. Attempting to use SET $LIST on a non-multidimensional object property results in an <OBJECT DISPATCH> error.
You cannot use SET (a,b,c,...)=value syntax with $LIST (or $PIECE or $EXTRACT) on the left of the equals sign, if the function uses relative offset syntax: * representing the end of a string and *-n or *+n representing relative offset from the end of the string. You must instead use SET a=value,b=value,c=value,... syntax.
You can also use $LISTUPDATE to replace one or more elements in a list or append element to a list by element position. $LISTUPDATE replaces list elements, performing a boolean test for each element replacement. Unlike SET $LIST, $LISTUPDATE does not modify the initial list, but returns a copy of that list with the specified element replacements.
Two Parameter Operations
You can perform the following two-parameter operations. Note that two-parameter operations specify an element value as a string. Specifying an element value as a list creates a sublist within the list.
Three Parameter Operations
You can perform the following three-parameter (range) operations. Note that range operations specify an element values as a list, even when specifying a single element value.
Examples
Examples of Returning Elements with $LIST
The following examples use the 2-parameter form of $LIST to return a list element as a string:
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 parameter is set to 1. The value is returned as a string:
   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. The value is returned as a string:
   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LIST(colorlist,2),!
   WRITE $LIST(colorlist,*-4)
 
The following examples use the 3-parameter 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 list 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 list 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,"/")
 
Notes
Unicode
If one Unicode character appears in a list element, that entire list element is represented as Unicode (wide) characters. Other elements in the list are not affected.
The following example shows two lists. The y list consists of two elements which contain only ASCII characters. The z list consists of two elements: the first element contains a Unicode character ($CHAR(960) = the pi symbol); the second element contains only ASCII characters.
   IF $SYSTEM.Version.IsUnicode()  {
   SET y=$LISTBUILD("ABC"_$CHAR(68),"XYZ")
   SET z=$LISTBUILD("ABC"_$CHAR(960),"XYZ")
   WRITE !,"The ASCII list y elements: "
   ZZDUMP $LIST(y,1)
   ZZDUMP $LIST(y,2)
   WRITE !,"The Unicode list z elements: "
   ZZDUMP $LIST(z,1)
   ZZDUMP $LIST(z,2)
   }
   ELSE {WRITE "This example requires a Unicode installation of Caché"}
 
Note that Caché encodes the first element of z entirely in wide Unicode characters. The second element of z contains no Unicode characters, and thus Caché encodes it using narrow ASCII characters.
$LIST Compared with $EXTRACT and $PIECE
$LIST determines an element from an encoded list by counting elements (not characters) from the beginning (or end) of the list.
$EXTRACT determines a substring by counting characters from the beginning (or end) of a string. $EXTRACT takes as input an ordinary character string.
$PIECE determines a substring by counting user-defined delimiter characters within the string. $PIECE takes as input an ordinary character string containing multiple instances of a character (or string) intended for use as a delimiter.
$LIST cannot be used on ordinary strings. $PIECE and $EXTRACT cannot be used on encoded lists.
See Also