ROTLIST

ROTLIST

Rotates the items in an SCL list

Category: List

Syntax
Details
Example
See Also

Syntax

list-id=ROTLIST(list-id<,n>);

list-id

is the identifier of the list to rotate. The function returns the list identifier that is passed in. An invalid list-id produces an error condition.

Type: Numeric or List

n

is the number of times to rotate the list. The default is 1.

Type: Numeric

Details

The items are rotated the number of times specified by n. If the value for n is positive, the items are rotated from right to left. This means that each rotation moves the item at the front of the list to the end of the list (that is, from position 1 to position -1). If the value for n is negative, the items are rotated from left to right. This moves the item at the end of the list to the front of the list (that is, from position -1 to position 1).

When a list is rotated, item names and attributes are moved along with the elements.

Fetching a named item from a list that has more than one item of the same name may return a different item from the list after rotating than was returned before rotating.

ROTLIST does not make a copy of the list before rotating the items in the list. The list is modified in place. To keep a copy of the original list, use COPYLIST before ROTLIST.

An error condition results if the list has the NOUPDATE attribute.

To check a list's attributes, use HASATTR. To change these attributes, use SETLATTR.

Example

Manipulate the list identified by LISTID, which contains the five character values A, B, C, D, and E. Display the list, rotate it right to left one time and display that list, and then rotate it left to right twice and display that list.

call putlist(listid,'Input list=');
listid = rotlist(listid); /* Rotate 1 time */
call putlist(listid,'Rotated  1=');
listid = rotlist(listid,-2);
call putlist(listid,'Rotated -2=');

The preceding statements produce the following changes. The net result is that the list is rotated backwards one time.

Input list=('A' 'B' 'C' 'D' 'E')[3]
Rotated  1=('B' 'C' 'D' 'E' 'A')[3]
Rotated -2=('E' 'A' 'B' 'C' 'D')[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]

See Also

Chapter Contents
Previous
Next
Top of Page