Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

$LIST ($LI)

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.

  • $LIST(list) returns the first element string in the list.

  • $LIST(list,position) returns the element indicated by the specified position. The position parameter must evaluate to an integer.

  • $LIST(list,position,end) returns a “sublist” (an encoded list string) containing the elements of the list from the specified start position through the specified end position.

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:

  • greater than position, an encoded string containing a list of elements is returned.

  • equal to position, an encoded string containing the one element is returned.

  • less than position, the null string ("") is returned.

  • greater than the number of elements in list, it is equivalent to specifying the final element in the list.

  • negative one (–1), it is equivalent to specifying the final element in the list.

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

Next section$LISTBUILD ($LB)
Previous sectionLES
FeedbackOpens in a new tab