List.insert Function

Format

i = list_name.insert(index, value ‖ list_name);

Description

The List.insert function inserts a single value (the numeric or string expression value) or a List of values (list_name) at the position in the List referenced by the numeric expression index. The type of the inserted value or List must match the type of the receiving List. List index values are one-based, so the index must be between 1 and one past the length of the List. If the index is 1, the values are inserted at the beginning of the List. If the value is List.length() + 1, the values are inserted at the end of the List (as would happen with the List.add function).

Return Value

The function returns the number of the values inserted into the List. The function returns 0 if the index is not valid. If the List is read-only, the function returns default.

Example

List string eligible_head_names;

do numeric counter = 1 while counter <= count(PERSON_REC)

if AGE(counter) >= 15 and USUAL_MEMBER(counter) = 1 then

// insert the names in sorted order
numeric insert_index;

do insert_index = 1 while insert_index <= eligible_head_names.length()
and eligible_head_names(insert_index) <= NAME(counter)
enddo;

eligible_head_names.insert(insert_index, NAME(counter));

endif;

enddo;

See also: List Object, List.add Function