Insert - method of the PmArray object

Description:

Adds one or more items/rows into the array. The array is enlarged by the added items/rows.

Syntax:

Empty Insert(Long nPos, Variant vValues, [Long nType])

Parameters:

nPos	(Long) The index of the item/row to be added. The current item/row on this index and following items will be shifted behind the added items/rows. The index of the first, not yet existing item/row at the end can also be entered, then add it to that position at the end. The -2 value means adding to the end.
vValues	(Variant) Represents the values of added items/rows or their number. The meaning depends on the parameter nType and also on the array type (1-dimensional array or 2-dimensional array).
nType	[optional] (Long) The parameter specifies meaning of the vValues parameter. 0 (default) - Adds always 1 item/row and sets the values from the vValues parameter. For 1-dimensional array the vValues parameter can contain any value and it will be added as a single entry. For 2-dimensional array, the vValues parameter must contain a single row (1-dimensional array) and this is added as a single row. The size of the added array must be equal to the number of columns of the array. 1 - Adds multiple items/rows at once and sets the values from the vValues parameter. For 1-dimensional array, the vValues parameter must contain 1-dimensional array with the items. For 2-dimensional array, the vValues parameter must contain 2-dimensional array with rows. The number of columns of the added array must be equal to the number of columns of the array. 2 - Adds one or more items/rows and sets empty values to items (undefined). For 1-dimensional array, the vValues parameter must contain a number with the number of blank items being added. For 2-dimensional array, the vValues parameter must contain a number with the number of blank rows being added.

Note:

The Insert method allows adding items to the beginning, to the end and aslo to the inside of an existing array and the Remove method allows removing items from beginning, from the end and aslo from the inside of an existing array.

However, this method is very slow for large arrays and not suitable for fast automatic processing of data arrays. It is better to allocate a larger array size in advance and after filling it with values, remove the empty items by the Remove method. See Example2.

For 2-dimensional arrays, it is necessary to follow the principle of correct order of array dimensions (columns, rows). See (Col,Row) - 2-dimensional array meaning an array of rows.

This method is also functional in Web panels.

Example1:

Adds a2 array into a1 array to position 2

JavaScriptSelect and copy to clipboard



var a1 = Pm.Array1(0, 10, 20, 30);

var a2 = Pm.Array1(12, 13, 14);

a1.Insert(2, a2, 0);
  // Result: (0, 10, (12, 13, 14), 20, 30)

// or

a1.Insert(2, a2, 1);
  // Result: (0, 10, 12, 13, 14, 20, 30)

Example2:

Adds three empty items to the end of the 1-dimensional array (undefined)

JavaScriptSelect and copy to clipboard



var a1 = Pm.Array1(0, 10, 20, 30);

a1.Insert(-2, 3, 2);
  // Result: (0, 10, 20, 30, , , )

Example3:

Inserts a row into a 2-dimensional array

JavaScriptSelect and copy to clipboard



var a1 = Pm.CreatePmArray(2, 2, 3);

a1.SetItem(1, 0, 0);

a1.SetItem(11, 1, 0);

a1.SetItem(2, 0, 1);

a1.SetItem(22, 1, 1);

a1.SetItem(3, 0, 2);

a1.SetItem(33, 1, 2);


var a2 = Pm.Array1(9, 99);


// Inserts a row into a 2-dimensional array

// to the beginning

a1.Insert(0, a2, 0);


// Adds a2 array into a1 array to position 2

a1.Insert(2, a2, 0);


// to the end

a1.Insert(-2, a2, 0);


// 3 rows with empty values at position 2

a1.Insert(2, 3, 2);

Example4:

Inserts another 2-dimensional array into the 2-dimensional array

JavaScriptSelect and copy to clipboard



var a1 = Pm.CreatePmArray(2, 2, 3);

a1.SetItem(1, 0, 0);

a1.SetItem(11, 1, 0);

a1.SetItem(2, 0, 1);

a1.SetItem(22, 1, 1);

a1.SetItem(3, 0, 2);

a1.SetItem(33, 1, 2);


var a2 = Pm.CreatePmArray(2, 2, 2);

a2.SetItem(9, 0, 0);

a2.SetItem(99, 1, 0);

a2.SetItem(8, 0, 1);

a2.SetItem(88, 1, 1);


// Inserts another 2-dimensional array into the 2-dimensional array

// to the beginning

a1.Insert(0, a2, 0);


// to position 2

a1.Insert(2, a2, 0);


// to the end

a1.Insert(-2, a2, 0);