SAS Component Language Dictionary

INSERTC, INSERTL, INSERTN, and INSERTO

Insert a value into an SCL list

Category:

List

Syntax
Details
Examples
	Example 1: Using the INSERTC Function
	Example 2: Using the INSERTL Function
	Example 3: Using the INSERTN Function
	Example 4: Using the INSERTO Function
See Also

Syntax

rc=INSERTC(list-id,cval<,index<,name>>);

rc=INSERTL(list-id,sublist-id<,index<,name>>);

rc=INSERTN(list-id,nval<,index<,name>>);

rc=INSERTO(list-id,object-id<,index<,name>>);

rc

is the list-id, which is the identifier of the modified list.

Type: Numeric

list-id

is the identifier of the list into which to insert the item. An invalid list-id produces an error condition.

Type: Numeric or List

cval

is the character value to insert into the list with INSERTC.

Type: Character

sublist-id

is the identifier of the sublist to insert into the list with INSERTL. An invalid sublist-id produces an error condition.

Type: Numeric

nval

is the numeric value to insert into the list with INSERTN.

Type: Numeric

object-id

is the identifier of the object to insert into the list with INSERTO. An invalid object-id produces an error condition.

Type: Numeric or Object

index

is the position at which to insert the item into the list. The position can be specified as a positive or negative number. By default, index is 1 (the first item). If index is a positive number, then the item is at position index from the beginning of the list. If index is a negative number, then the item is at position ABS(index) from the end of the list. Index must be in the range [-(n+1),-1] or [1,n+1] where n is the length of the list. An error condition results if the absolute value for index is zero or if it is greater than the number of items in the list.

Type: Numeric

name

is the name to assign to the item. If name is omitted, a name is not assigned to the item.

Type: Character

Details

The item is inserted such that after you insert an item at position index, you can retrieve it from position index with any of these functions.

These functions do not make a copy of the list. The insertion is performed in place. You can append an item to an SCL list of length n by inserting at index=n+1 or at index=-1.

Note: The return value of these functions is not used to indicate whether an error has been detected. When an error occurs, the program simply halts. [cautionend]

An error condition results if

the list has any of the following attributes:
- NOUPDATE
- FIXEDLENGTH
- CHARONLY, and you use an insert function other than INSERTC
- NUMONLY, and you use an insert function other than INSERTN
- SASNAMES, and name is omitted or is not a valid SAS name
- NODUPNAMES, and name duplicates the name of a list item.
the absolute value for index is greater than 1 plus the number of items in the list or is 0.
you attempt to insert a local list into a global list with INSERTL.

You can use HASATTR to check the attributes of a list or list item. To change attributes, use SETLATTR.

Examples

Example 1: Using the INSERTC Function

Insert CANADA as the third item in the list:

listid=insertc(listid,'CANADA',3);

After this insertion, return the value that was third in the list before the insertion of CANADA shifted the value from the third to the fourth position:

cval=getitemc(listid,4);

Example 2: Using the INSERTL Function

Insert the sublist NEWLIST as the third item from the end of the list:

listid=insertl(listid,newlist,-3);

Example 3: Using the INSERTN Function

Assume that the list MYLIST contains four items, named A, B, C, and D, with the values 1, 4, 9, and 16, respectively. Insert two new items: a string at the default position 1 (the beginning of the list), and a number at position -1 (the end of the list). The new number is given the name E.

call putlist(mylist,'Before: ',0);
mylist=insertc(mylist,'Squares');
mylist=insertn(mylist,25, -1,'E');
call putlist(mylist,'After: ',0);

This program produces the following output:

Before: (A=1
         B=4
         C=9
         D=16
         )[3]
After: ('Squares'
        A=1
        B=4
        C=9
        D=16
        E=25
        )[3]

Note: [3] is the list identifier that was assigned when this example was run and may be different each time the example is run. [cautionend]

Example 4: Using the INSERTO Function

Create the list MYLIST, insert the item whose identifier is stored in the variable MYOBJECT, and assign the name My Object to the item:

declare sashelp.fsp.object myobject = _new_ sashelp.fsp.object(),
        list mylist;
mylist=makelist();
rc=inserto(mylist,myobject,-1,'My Object');