INSERT Function

The INSERT function inserts an attribute, value, or subvalue into a specified position in a dynamic array.

Format

array = INSERT(array , attr# [,value# [,subval#]] ,|; expr)

Parameter(s)

array	Dynamic array to be changed.
attr#	An expression evaluating to the attribute number. The attr# may be greater than or equal to 1, or less than 0. If attr# evaluates to a negative number, the attribute is appended to the end of the array. If attr# evaluates to a number greater than the number of attributes in the array, the data is appended to the end of the array, with the appropriate number of empty attributes inserted.
value#	An expression evaluating to the value number. If value# is omitted or equal to 0, the value is inserted before the attribute. If value# evaluates to a negative number, it is appended at the end of the attribute. If value# evaluates to a number greater than the number of values in the attribute, the data is appended to the end of the attribute, with the appropriate number of empty values inserted.
subval#	An expression evaluating to the subvalue number. If subval# is omitted or equal to 0, the subvalue is inserted before the value. If subval# evaluates to a negative number, it is appended to the end of the value. If subval# evaluates to a number greater than the number of subvalues in the value, the data is appended to the end of the value, with the appropriate number of empty subvalues inserted.
expr	An expression evaluating to the data to be inserted.

Description

The INSERT function inserts a new attribute, value, or subvalue into the specified dynamic array. Either a comma or a semicolon can separate the subvalue expression from the replacement data, but if the subvalue is omitted then a semicolon must be used.

If an attribute, value, or subvalue expression evaluates to a noninteger value, it is truncated to an integer value.

The LOCATE statement may be particularly useful with the INSERT function to insert array elements in an ascending or descending order. See LOCATE Statement for more information.

The INSERT function has an equivalent in the INS statement, which uses angle brackets similar to the EXTRACT angle brackets. See INS Statement for more information.

Example

In this application the user creates an alphabetical list of each item-ID in the file CUSTOMERS. The file is selected, and when each item-ID is read, the LOCATE statement is used to find its alphabetical position. The INSERT function is then used to insert the current ID in the proper position.

EQUATE TRUE TO 1, FALSE TO 0

OPEN "CUSTOMERS" TO CUSTFILE ELSE

ABORT 201, "CUSTOMERS"

END

SELECT CUSTFILE TO LIST

ALPH.LIST = ""

END.OF.LIST = FALSE

LOOP

READNEXT ID FROM LIST ELSE

END.OF.LIST = TRUE

END

UNTIL END.OF.LIST DO

LOCATE ID IN ALPH.LIST BY "AL" SETTING POSITION THEN

PRINT ID : " DUPLICATE ENTRY! POSSIBLE FILE CORRUPTION"

ABORT

END ELSE

ALPH.LIST = INSERT(ALPH.LIST , POSITION ; ID)

END

REPEAT