SAS Component Language Dictionary

NAMEDITEM

Returns the index of a named item in a list

Category:

List

Syntax
Details
Example
See Also

Syntax

index=NAMEDITEM(list-id,name<,occurrence
<,start-index<,forceup>>>);

index

contains the position of the item in the list, or 0 if the named item is not found.

Type: Numeric

list-id

is the identifier of the list that NAMEDITEM searches. An invalid list-id produces an error condition.

Type: Numeric or List

name

is the name of the item to search for. If name is specified, then trailing blanks are removed before the search. If name is blank, the first unnamed item is returned.

Type: Character

occurrence

specifies which occurrence of the named item to search for. The default, 1, specifies the first occurrence of the item.

Type: Numeric

start-index

specifies where in the list to begin searching for the item. By default, start-index is 1 (the first item). If start-index is positive, then the search begins at position start-index items from the beginning of the list. If start-index is negative, then the search begins at the item specified by ABS(start-index) items from the end of the list. An error condition results if the absolute value of start-index is zero or if it is greater than the number of items in the list.

Type: Numeric

forceup

can have one of the following values:

'Y'	specifies a case-insensitive search, which overrides the HONORCASE or NOHONORCASE list attribute.
'N'	specifies a search that uses the HONORCASE or NOHONORCASE list attribute and is the default action for lists when FORCEUP is not specified.
IGNORECASE	is an alias for NOHONORCASE.

Details

NAMEDITEM searches only the top level of the list specified by list-id. That is, it does not search sublists. Several functions that access items in a list by position have counterparts that access items by their names such as GETITEMC versus GETNITEMC. Because it is more efficient to retrieve an item by its position rather than by its name, you can use NAMEDITEM to find the position and then use the functions that access items by position rather than by name.

If occurrence and start-index are both positive or both negative, the search proceeds forward from the start-index item. For forward searches, the search continues only to the end of the list and does not wrap back to the front of the list. If occurrence or start-index is negative, the search is backwards. For backward searches, the search continues only to the beginning of the list and does not wrap back to the end of the list.

Example

Swap the numeric values associated with the first and last occurrence of the item named x :

/*  Return first occurrence of X.  */
first=getnitemn(listid,'X');
/*  Return last occurrence of X.   */
last=getnitemn(listid,'X',1,-1);
list=setnitemn(listid,last,'X');
list=setnitemn(listid,first,'X',1 -1);

The following example shows a slightly more efficient way to perform the swap operation. This method does not require a second search for the item, and it can also detect when item x does not exist in the list.

/*  Return the position number of the */
/* first item X. */
ifirst=nameditem(listid,'X');
if (ifirst>0) then
   do;
      first=getitemn(listid,ifirst);
/* Return the position of the last item X.*/
      ilast=nameditem(listid,'X',1,-1);
      list=setitemn(listid,getitemn(listid,ilast),
                   ifirst);
      list=setitemn(listid,first,ilast);
   end;

Note: This example checks to see whether there is at least one item named x but never checks to see whether there is another item named x . It assumes that there is at least one more item named X [cautionend]