insert() Function

The insert() function inserts the element referenced by str.exp into a specific attribute, value, or subvalue location in dyn.array.exp.

Syntax

insert(dyn.array.exp, ac.exp; str.exp)

insert(dyn.array.exp, ac.exp, vc.exp; str.exp)

insert(dyn.array.exp, ac.exp, vc.exp, sc.exp; str.exp)

Parameter(s)

dyn.array.exp	Dynamic array in which the element will be inserted.
ac.exp	Attribute in which the element will be inserted.
vc.exp	Value in which the element will be inserted.
sc.exp	Subvalue in which the element will be inserted.
str.exp	Element to insert in the dynamic array.

Description

-1 can be specified as the attribute count expression, value count expression, or subvalue count expression. Position -1 inserts the expression as the last element in the respective location.

0 can be specified as the attribute count expression. Position 0 inserts the expression as the first attribute. A 0 as the value count expression, or the subvalue count expression is ignored.

Unlike the replace() function, which changes the contents of a dynamic array element without changing its logical position or any other element, the insert() function inserts the results of str.exp at the specified location and all following information at that dynamic array level (attribute, value, or subvalue) is shifted one position higher in the array. If an attribute count expression of 1 is specified, the expression is inserted before attribute 1, shifting attribute 1 to attribute 2.

The insert(), replace(), and delete() functions force the entire dynamic array (string) to be rebuilt.

Example(s)

These examples are exactly the same. They insert the current value of name in attribute 1 of the array, customer.item. Every other value in attribute 1 shifts right by one position. (Value 1 becomes value 2, and so on.) The values of attribute 1 are shifted, but the other attributes in the item maintain their relative position.

customer.item = insert(customer.item,1,1,0,name)

customer.item = insert(customer.item,1,1;name)