The insert() function inserts the element referenced by str.exp into a specific attribute, value, or subvalue location in dyn.array.exp.
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)
| 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. |
-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.
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)
Array references, Array variable, Assignment, Attribute count expression, del statement, delete() function, extract() function, BASIC functions, ins statement, locate statement, ereplace() function, Statements and functions, String expressions, Subvalue count expressions, Value count expression