Insert a new value at the specified position of a 1D or 2D array
#include <Array.au3>
_ArrayInsert ( ByRef $aArray, $vRange [, $vValue = "" [, $iStart = 0 [, $sDelim_Item = "|" [, $sDelim_Row = @CRLF [, $iForce = $ARRAYFILL_FORCE_DEFAULT]]]]] )
| $aArray | Array to modify |
| $vRange | Position(s) at which to insert item(s) - see Remarks for format |
| $vValue | [optional] Value(s) to add - can be a single variable, a delimited string or a 1D array |
| $iStart | [optional] Column in which insert is to begin (2D array only) |
| $sDelim_Item | [optional] Delimiter used if a string is to be split into items |
| $sDelim_Row | [optional] Delimiter used if a string is to be split into rows (2D only) |
| $iForce | [optional] Maintains default behaviour, $ARRAYFILL_FORCE_DEFAULT (0) Forces $vValue addition as a single item, $ARRAYFILL_FORCE_SINGLEITEM (1) Or forces datatype for all added items $ARRAYFILL_FORCE_INT (2) $ARRAYFILL_FORCE_NUMBER (3) $ARRAYFILL_FORCE_PTR (4) $ARRAYFILL_FORCE_HWND (5) $ARRAYFILL_FORCE_STRING (6) See Remarks for more details |
| Success: | the new size of the array. |
| Failure: | 0 and sets the @error flag to non-zero. |
| @error: | 1 - $aArray is not an array 2 - $aArray is not a 1D or 2D array 3 - $vRange incorrectly formatted (incorrect character or unordered) 4 - $vRange is not a 1D array or has only 1 element 5 - $vRange limits outside array bounds 6 - $iStart outside array bounds (2D only) 7 - $vValue not 2D array (2D only) 8 - $vValue has too many columns to fit into $aArray |
$vRange can be a string containing the rows above which a row is to to be inserted. It can be a single number or a range denoted by the first and last lines separated by a hyphen (-) - multiple items are separated by a semi-colon (;).
$vRange can also be a 1D array containing the rows above which a row is to to be inserted with the count in the [0] element].
In either case, the rows must be in ascending order but can be duplicated.
If $vValue is a delimited string all items are inserted into the array as strings. This can be over-ridden by using the $hDataType parameter which forces the items into the required datatype. Note that all items in the delimited string are converted - if the items are of different datatypes then they must be passed as an array so that their specific datatype is conserved.
Insertion mode depends on $vValue type, but using $iForce can affect this. Default behaviour is as follows:
1D arrays:
Single item - inserts 1 element containing $vValue
$sDelim_Item delimited string - matches insertion lines to items in the string
0-based 1D array - matches insertion lines to elements in the array
2D arrays:
Single item - inserts 1 row containing $vValue in the first column
$sDelim_Item delimited string - inserts 1 row at first insertion line, columns filled if enough items
$sDelim_Row delimited string - matches insertion lines to items in the string, only 1 column filled
Double-delimited string - matches insertion lines to string split on $sDelim_Row, columns to string split on $sDelim_Item
0-based 2D array - matches insertion lines to rows in the array, columns to columns in the array
An empty string ("") is added if there are insufficient items specified in $vValue. Excess items are ignored.
Setting the $iForce parameter can change the default insertion behaviour or amend the datatype for added items. It can be set as follows:
- $ARRAYFILL_FORCE_DEFAULT (default):
- Items are split as described above. Single items and array elements retain their datatypes - delimited strings are added as strings.
- $ARRAYFILL_FORCE_SINGLEITEM:
- If $aArray is 1D, $vValue is inserted as a single element.
- if $aArray is 2D the parameter is ignored.
- $ARRAYFILL_FORCE_INT, $ARRAYFILL_FORCE_NUMBER, $ARRAYFILL_FORCE_PTR, $ARRAYFILL_FORCE_HWND, $ARRAYFILL_FORCE_STRING
- If $vValue is a single item, it is forced into the defined datatype - by default it would retain its existing datatype.
- If $vValue is a delimited string, all items are forced into the specified datatype - by default they would be inserted into the array as strings. If different datatypes are required for the items they must be passed as an array.
- If $vValue is an array, the parameter is ignored and the array elements are inserted retaining their existing datatypes.
If $iForce is set to any other value it is ignored.
The function does NOT update any count element within the array, but the return value of the function (if successful) gives the new highest row index of the array.
_ArrayAdd, _ArrayDelete, _ArrayPop, _ArrayPush
#include <Array.au3>
Local $aArray_Base[10] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
_ArrayDisplay($aArray_Base, "1D - Original")
; Insert single item
Local $aArray = $aArray_Base
_ArrayInsert($aArray, 2, "Insert above 2")
_ArrayDisplay($aArray, "1D - Single item")
; Insert delimited string using range array
$aArray = $aArray_Base
Local $aRange[4] = [3, 3, 5, 9]
Local $sFill = "Insert above 3|Insert above 5|Insert above 9"
_ArrayInsert($aArray, $aRange, $sFill)
_ArrayDisplay($aArray, "1D - Delim String")
; Insert 1D array using range string
$aArray = $aArray_Base
Local $aFill[4] = ["Insert above 2", "Insert above 6.1", "Insert above 6.2", "Insert above 7"]
_ArrayInsert($aArray, "2;6;6;7", $aFill)
_ArrayDisplay($aArray, "1D - 1D array")
; Insert 1D array as single item
$aArray = $aArray_Base
Local $aFill[4] = ["Insert 0", "Insert 1", "Insert 2", "Insert 3"]
_ArrayInsert($aArray, "2", $aFill, Default, Default, Default, $ARRAYFILL_FORCE_SINGLEITEM)
_ArrayDisplay($aArray, "1D - Single Item")
_ArrayDisplay(($aArray)[2], "Internal array")
#include <Array.au3>
Local $aArray_Base[10][3]
For $i = 0 To 9
For $j = 0 To 2
$aArray_Base[$i][$j] = $i & " - " & $j
Next
Next
_ArrayDisplay($aArray_Base, "2D - Original")
; Insert single item
Local $aArray = $aArray_Base
_ArrayInsert($aArray, 7, "Insert above 7-0")
_ArrayDisplay($aArray, "2D - Single item")
; Insert single item in defined column
$aArray = $aArray_Base
_ArrayInsert($aArray, 3, "Insert above 3-1", 1)
_ArrayDisplay($aArray, "2D - Defined column")
; Insert item delimited string - inserted as 1 row - other rows filled with ""
$aArray = $aArray_Base
Local $sFill = "Above 3-0|Above 3-1|Above 3-2"
_ArrayInsert($aArray, "3;5;9", $sFill)
_ArrayDisplay($aArray, "2D - Item delim string")
; Insert row delimited string using range array - inserted as 3 rows, other cols filled with ""
$aArray = $aArray_Base
Local $aRange[4] = [3, 3, 5, 9]
$sFill = "Above 3-2" & @CRLF & "Above 5-2" & @CRLF & "Above 9-2"
_ArrayInsert($aArray, $aRange, $sFill, 2) ; Insert in column 2
_ArrayDisplay($aArray, "2D - Item delim string")
; Insert item as row delimited string - inserted as 4 rows
$aArray = $aArray_Base
$sFill = "Above 3-0|3-1|3-2" & @CRLF & "Above 5a|5-1a|5-2a" & @CRLF & "Above 5b|5-1b|5-2b" & @CRLF & "Above 9|9-1|9-2"
_ArrayInsert($aArray, "3;5;5;9", $sFill)
_ArrayDisplay($aArray, "2D - Item & row delim string")
; Insert 2D array
$aArray = $aArray_Base
Local $aFill_1D[3][3] = [["Above 2", "2-1", "2-2"], ["Above 3", "3-1", "3-2"], ["Above 4", "4-1", "4-2"]]
_ArrayInsert($aArray, "2-4", $aFill_1D)
_ArrayDisplay($aArray, "2D - 2D Array")
#include <Array.au3>
#include <MsgBoxConstants.au3>
Local $aArray_Base[2][2] = [["Org Item 0 - 0", "Org Item 0 - 1"], ["Org Item 1 - 0", "Org Item 1 - 1"]]
Local $aArray
Local $sFill = 1 & @CRLF & 2 ; Note added as number datatype here
MsgBox($MB_SYSTEMMODAL, "Delimited string to add", $sFill)
; Add items by delimited string
$aArray = $aArray_Base
_ArrayInsert($aArray, "0;1", $sFill)
_ArrayDisplay($aArray, "Converted to string")
; But converted to string datatype here
MsgBox($MB_SYSTEMMODAL, "Result", "Data:" & @TAB & $aArray[2][0] & @CRLF & "Datatype:" & @TAB & VarGetType($aArray[2][0]))
; Add items by delimited string
$aArray = $aArray_Base
; Now force datatype to be retained
Local $hDataType = Number
_ArrayInsert($aArray, "0;1", $sFill, Default, Default, Default, $ARRAYFILL_FORCE_NUMBER)
_ArrayDisplay($aArray, "Forced to number")
; And datatype is retained
MsgBox($MB_SYSTEMMODAL, "Result", "Data:" & @TAB & $aArray[2][0] & @CRLF & "Datatype:" & @TAB & VarGetType($aArray[2][0]))