List-Structure String Operations
ObjectScript defines a special kind of string called a list, which consists of an encoded list of substrings, known as elements. These InterSystems IRIS lists can only be handled using the following list functions:
-
List creation:
-
$LISTBUILD creates a list by specifying each element as a parameter value.
-
$LISTFROMSTRING creates a list by specifying a string that contains delimiters. The function uses the delimiter to divide the string into elements.
-
$LIST creates a list by extracting it as a sublist from an existing list.
-
List data retrieval:
-
$LIST returns a list element value by position. It can count positions from the beginning or the end of the list.
-
$LISTNEXT returns list element values sequentially from the beginning of the list. While both $LIST and $LISTNEXT can be used to sequentially return elements from a list, $LISTNEXT is significantly faster when returning a large number of list elements.
-
$LISTGET returns a list element value by position, or returns a default value.
-
$LISTTOSTRING returns all of the element values in a list as a delimited string.
-
List manipulation:
-
SET $LIST inserts, updates, or deletes elements in a list. SET $LIST replaces a list element or a range of list elements with one or more values. Because SET $LIST can replace a list element with more than one element, you can use it to insert elements into a list. Because SET $LIST can replace a list element with a null string, you can use it to delete a list element or a range of list elements.
-
List evaluation:
-
$LISTVALID determines if a string is a valid list.
-
$LISTLENGTH determines the number of elements in a list.
-
$LISTDATA determines if a specified list element contains data.
-
$LISTFIND determines if a specified value is found in a list, returning the list position.
-
$LISTSAME determines if two lists are identical.
Because a list is an encoded string, InterSystems IRIS treats lists slightly differently than standard strings. Therefore, you should not use standard string functions on lists. Further, using most list functions on a standard string generates a <LIST> error.
The following procedure demonstrates the use of the various list functions:
ListTest() PUBLIC {
// set values for list elements
SET Addr="One Memorial Drive"
SET City="Cambridge"
SET State="MA"
SET Zip="02142"
// create list
SET Mail = $LISTBUILD(Addr,City,State,Zip)
// get user input
READ "Enter a string: ",input,!,!
// if user input is part of the list, print the list's content
IF $LISTFIND(Mail,input) {
FOR i=1:1:$LISTLENGTH(Mail) {
WRITE $LIST(Mail,i),!
}
}
}
This procedure demonstrates several notable aspects of lists:
For more detailed information on list functions see the corresponding reference pages in the ObjectScript Reference.
Sparse Lists and Sublists
A function that adds an element value to a list by position will add enough list elements to place the value in the proper position. For example:
SET $LIST(Alphalist,1)="a"
SET $LIST(Alphalist,20)="t"
WRITE $LISTLENGTH(Alphalist)
Because the second $LIST in this example creates list element 20, $LISTLENGTH returns a value of 20. However, elements 2 through 19 do not have values set. Hence, if you attempt to display any of their values, you will receive a <NULL VALUE> error. You can use $LISTGET to avoid this error.
An element in a list can itself be a list. To retrieve a value from a sublist such as this, nest $LIST function calls, as in the following code:
SET $LIST(Powers,2)=$LISTBUILD(2,4,8,16,32)
WRITE $LIST($LIST(Powers,2),5)
This code returns 32, which is the value of the fifth element in the sublist contained by the second element in the Powers list. (In the Powers list, the second item is a sublist of two raised to the first through fifth powers, so that the first item in the sublist is two to the first power, and so on.)
