====== Insert function  ======


 
==== Description ====
 
Insert a field, value, or subvalue into a dynamic array.
 
==== Syntax ====
 
//new_array// = **Insert**(//string//, //field//, //value//, //subvalue//, //new//)
 
==== Parameters ====
 
The Insert function has the following parameters.

^ Parameter                           ^ Description                                                                                                                                                               ^
| //String//                          | //string// designates the dynamic array that is to be searched. This parameter is not modified.                                                                           |
| //field//, //value//, //subvalue//  | The second, third, and fourth expressions are delimiters. Their respective numeric values determine whether the new data is inserted as a field, a value, or a subvalue.  |
| //new//                             | The data to insert                                                                                                                                                        |



For instance, this example statement:\\ \\ F = Insert(A, 2, 0, 0, NEW)\\ \\ inserts NEW as a field. When both the //value// and //subvalue// are 0 (zero), the new data is inserted before the second field (specified by the field) of dynamic array A. F is assigned the new array.\\ \\ This example:\\ \\ V = Insert(A, 2, 3, 0, NEW)\\ \\ inserts NEW as a value. When only the //subvalue// is 0 (zero), the new data is inserted before the third value of the second field (specified by the value) of dynamic array A. V is assigned the new entire array.\\ \\ This example:\\ \\ S = Insert(A, 2, 3, 1, NEW)\\ \\ inserts NEW as a subvalue. When all three delimiter expressions have a non-zero value, the new data is inserted before the first subvalue of the second value of the third field (specified by the subvalue) of dynamic array A. S is assigned the new array.


If the second, third, or fourth expression has a -1 (minus one) value, the new data is inserted after the specified field, value, or subvalue delimiter. For example:\\ \\ F = Insert(A, -1, 0, 0, NEW)\\ \\ appends NEW as a field to the end of the array.


The //field// is the highest level delimiter while //subvalue// is the lowest level delimiter. If a higher level delimiter has a 0 (zero) value while a lower level delimiter has a non-zero value, the zero delimiter is assumed to be 1 (one). As in this example:\\ \\ S=Insert(A, 0, 0, 2, B)\\ \\ is assumed to be\\ \\ S=Insert(A, 1, 1, 2, B)\\

 
==== See Also ====
 
[[delete_function|Delete()]], [[replace|Replace()]]
 
==== Example ====
 
<code>
X = "A,B,C"
Convert ',' to @FM in X
Y = Insert(X, -1,0,0,"D")
Convert @FM to ',' in Y
/* Result:
Y = "A,B,C,D" */

X = "A,B,D"
Convert ',' to @VM In X
Y = Insert(X, 1,3,0,'C')
Convert @VM to ',' in Y
/* Result:
Y = "A,B,C,D" */
</code>