Caché MultiValue Basic Reference
$LIST ($LI)
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Returns elements in a list.
Synopsis
$LIST(list,position,end)
$LI(list,position,end)
Parameters
list An expression that resolves to a Caché list. Because lists contain encoding, list must be created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
position Optional — The starting position in the specified list. An expression that resolves to an integer. Valid values are -1 and positive integers.
end Optional — The ending position in the specified list. An expression that resolves to an integer. Valid values are -1, 0, and positive integers.
Description
$LIST returns elements from a list. The elements returned depend on the parameters used.
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. The following are valid list arguments:
myList = $LISTBUILD("Red","Blue","Green","Yellow")
PRINT $LIST(myList,2);    ! prints Blue
subList = $LIST(myList,2,4)
PRINT $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:
myList = $LISTBUILD("Red","Blue","Green","Yellow")
subList = $LIST(myList,2)
PRINT $LIST(subList,1)
The second $LIST generates a <LIST> error.
position
The position of a list element to return. List elements are counted from 1. If position is omitted, the first element is returned. If the value of position is 0 or greater than the number of elements in the list, Caché issues a <NULL VALUE> error. If the value of position is negative one (–1), $LIST returns the final element in the list.
If the end parameter is specified, position specifies the first element in a range of elements. 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 not identical to $LIST(x,2,2).
end
The position of the last element in a range of elements. You must specify position to specify end. 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.
If the value of end is:
When specifying end, you can specify a position value of zero (0). In this case, 0 is equivalent to 1.
Examples
The following two PRINT statements both return “RED”, the first element in the list. The first writes the first element by default, the second writes the first element because the position parameter is set to 1:
PRINT $LIST($LISTBUILD("RED","BLUE","GREEN"))
PRINT $LIST($LISTBUILD("RED","BLUE","GREEN"),1)
The following example returns “Blue”, the second element in the list:
x=$LISTBUILD("Red","Blue","Green")
PRINT $LIST(x,2)
The following example returns “Green White”, a two-element list string beginning with the first element and ending with the second element in the list.
x=$LISTBUILD("Green ","White ","Brown ","Black ")
PRINT $LIST(x,1,2)
The following example returns “Brown Black”, a two-element list string that begins with the third element and ends with the last element in the list:
x=$LISTBUILD("Green ","White ","Brown ","Black ")
PRINT $LIST(x,3,-1)
Notes
Invalid Parameter Values
If the expression in the list parameter does not evaluate to a valid list, a <LIST> error occurs.
x=CHAR(0):CHAR(0):CHAR(0):CHAR(1):CHAR(16):CHAR(27):CHAR(134):CHAR(240)
a=$LIST(x,2);    ! generates a LIST error
If the value of the position parameter or the end parameter is less than -1, invoking the $LIST function generates a <RANGE> error.
If the value of the position parameter refers to a nonexistent list member and no end parameter is used, invoking the $LIST function generates a <NULL VALUE> error.
list2=$LISTBUILD("Brown","Black")
PRINT $LIST(list2,3);    ! generates a NULL VALUE error
x=$LIST(list2,0);        ! generates a NULL VALUE error
If the value of the position parameter identifies an element with an undefined value, invoking the $LIST function also generates a <NULL VALUE> error.
PRINT $LIST("");    ! generates a NULL VALUE error
x=$LISTBUILD("A",,"C")
PRINT $LIST(x,2);   ! generates a NULL VALUE error
Two-Parameter and Three-Parameter $LIST
$LIST(list,1) is not equivalent to $LIST(list,1,1) because the former returns a string, while the latter returns a single-element list string. Furthermore, the first can receive a <NULL VALUE> error, whereas the second cannot; if there are no elements to return, it returns a null string.
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.
y=$LISTBUILD("ABC":CHAR(68),"XYZ")
z=$LISTBUILD("ABC":CHAR(960),"XYZ")
PRINT "The ASCII list y elements: "
PRINT $LIST(y,1)
PRINT $LIST(y,2)
PRINT "The Unicode list z elements: "
PRINT $LIST(z,1)
PRINT $LIST(z,2)
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.
See Also