Caché Basic Reference
[Home] [Back] [Next]
InterSystems: The power behind what matters   

Returns elements from a list.

list An expression that evaluates to a valid list. A Caché list must be created using ListBuild or ListFromString, or extracted from another list using List.
position Optional — An integer that specifies the position of the list element to return, or the beginning of a sublist range if end is specified. Specify an expression that evaluates to a non-zero positive integer. You can use –1 to specify the last element in the list. If position is not specified, it defaults to 1 (the first element in list).
end Optional — An integer that specifies the position of the list element which is the final element in the sublist range. Specify an expression that evaluates to an integer. Use –1 to specify the last element in the list.
List returns elements from a list. The elements returned depend on the specified arguments.
You can also use ListNext to sequentially return elements from a 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")
Println List(myList, 2) 'prints Blue
subList = List(myList,2,4)
Println List(subList, 2) 'prints Green
In the following example, subList is not a valid list argument, because a List returns a single element as an ordinary string, not an encoded list string:
myList = ListBuild("Red", "Blue", "Green", "Yellow")
subList = List(myList,2)
Println List(subList,1)  ' INVALID OPERATION
Attempting to use the List function on an ordinary string generates a runtime error.
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 argument 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), as shown in the following example:
MyList = ListBuild("A","B","C")
x = List(MyList,2)
y = List(MyList,2,2)
If x=y Then
  Println "Lists are identical"
  Println "Lists not identical"
End If
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.
Note that 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. 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.
fruit = ListBuild("apple","banana","pear")
PrintLn List(fruit,1)
PrintLn List(fruit,1,1)
List Errors
The following List argument values generate an error:
Setting List
You can use List on the left of the equal sign to replace a specified element in a list with another element value. You can perform the following operations:
To replace the final element in a list use a position of -1. Note that List(inlint,-1)=value and List(inlint,-1,-1)=value perform different operations: List(inlint,-1)=value replaces the value of the last element; List(inlint,-1,-1)=value deletes the last element, then appends the specified list.
To remove the final element of a list, use List(inlint,-1,-1)="".
The following examples demonstrates how to use the List function:
myList = ListBuild("Red","Blue","Green","Yellow")
color4 = List(myList,4) ' returns value of the 4th element
Println color4             ' prints Yellow
sublist = List(myList,2,3) ' returns the 2nd and 3rd elements as a list
Println List(sublist,1)    ' prints Blue
Because multi-element lists contain non-printing list encoding characters, Println should only be used to display single list items.
See Also

Send us comments on this page
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA