Function Reference


_ArrayInsert

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

Parameters

$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

Return Value

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

Remarks

$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.

Related

_ArrayAdd, _ArrayDelete, _ArrayPop, _ArrayPush

Example

Example 1

#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")

Example 2

#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")

Example 3

#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]))