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.
_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]))