Syntax Supported by the IML Procedure and the iml Action
LISTINSERTITEM Call
CALL LISTINSERTITEM (list, position, v <, flag> ) ;
This subroutine is supported by the IML procedure and the iml action.
The ListInsertItem subroutine adds a new item to a list. For examples and a general discussion of using lists, see Chapter 9, Lists and Data Structures (SAS/IML User's Guide).
The ListInsertItem subroutine inserts an item into a list. If the list has k items, you can insert a new item in positions 
. If you insert an item at position i where 
, then the existing items at positions 
are shifted to the right to make room for the new item. In other words, the new item is inserted prior to the existing item in the specified position, and the length of the list increases by one.
The subroutine takes the following arguments:
- list
specifies an existing list.
- position
specifies the position where the item is to be inserted. Existing items at or subsequent to that position are shifted to the right. For example, the position 1 indicates that the item is inserted at the beginning of the list.
- v
specifies a SAS/IML variable or literal that will become a new list item. The value of v can be a matrix, table, list, or any other valid SAS/IML type, including an empty matrix.
- flag
-
controls what happens to v. Valid values are:
- 'c'
copies the data in v into the list. The v symbol is unchanged by the call. This is the default behavior.
- 'm'
moves the data in v into the list. The v symbol is freed after the call.
L = ListCreate();
call ListAddItem(L, 1:3);
call ListAddItem(L, {"Cat" "Dog"});
mat = {1 2, 3 4};
call ListInsertItem(L, 2, mat); /* insert 2x2 matrix in 2nd position */
The ListInsertItem function is more efficient than list concatenation. Although you can also insert the matrix by using the syntax L = L[1] || [mat] || L[2], that syntax is inefficient and should be avoided.