Adds a specified value at the end of an existing 1D or 2D array
#include <Array.au3>
_ArrayAdd ( ByRef $aArray, $vValue [, $iStart = 0 [, $sDelim_Item = "|" [, $sDelim_Row = @CRLF [, $iForce = $ARRAYFILL_FORCE_DEFAULT]]]] )
$aArray | Array to modify |
$vValue | Value(s) to add - can be a single item, a delimited string or an array |
$iStart | [optional] Column in which addition 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 index of last added item. |
Failure: | -1 and sets the @error flag to non-zero. |
@error: | 1 - $aArray is not an array 2 - $aArray is not a 1 or 2 dimensional array 3 - $vValue has too many columns to fit into $aArray 4 - $iStart outside array bounds (2D only) 5 - Number of dimensions for $avArray and $vValue arrays do not match |
Addition mode depends on $vValue type, but using $iForce can affect this. Default behaviour is as follows:
1D arrays:
Single item - adds 1 element
$sDelim_Item delimited string - adds as many elements as items
0-based 1D array - adds as many elements as items
2D arrays:
$sDelim_Item delimited string - adds 1 row, columns filled if enough items
$sDelim_Row delimited string - adds as many rows as items, only 1 column filled
$sDelim_Item & Row delimited string - adds rows and items, depending on split points
0-based 2D array - adds as many rows/columns as in 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 added 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 added to 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 added retaining their existing datatypes.
If $iForce is set to any other value it is ignored.
_ArrayConcatenate, _ArrayDelete, _ArrayInsert, _ArrayPop, _ArrayPush
#include <Array.au3>
#include <MsgBoxConstants.au3>
Local $aArray_Base[2] = ["Org Item 0", "Org item 1"]
_ArrayDisplay($aArray_Base, "1D - Base array")
; Add a single item
Local $aArray = $aArray_Base
Local $sSingleFill = "New Item 2"
_ArrayAdd($aArray, $sSingleFill)
_ArrayDisplay($aArray, "1D - Single")
; Add a delimited string - each item adds new element
$aArray = $aArray_Base
Local $sFill = ""
For $i = 1 To 5
$sFill &= "New Item " & $i + 1 & "|"
Next
$sFill = StringTrimRight($sFill, 1)
MsgBox($MB_SYSTEMMODAL, "Delimited string to add", $sFill)
_ArrayAdd($aArray, $sFill)
_ArrayDisplay($aArray, "1D - Delim string")
; Add a 1D array - each element adds new element
$aArray = $aArray_Base
Local $aFill[5]
For $i = 0 To 4
$aFill[$i] = "New Item " & $i + 2
Next
_ArrayDisplay($aFill, "Array to add")
_ArrayAdd($aArray, $aFill)
_ArrayDisplay($aArray, "1D - 1D array")
#include <Array.au3>
Local $aArray, $sFill
Local $aArray_Base[2][2] = [["Item 0 - 0", "Item 0 - 1"], ["Item 1 - 0", "Item 1 - 1"]]
_ArrayDisplay($aArray_Base, "2D - Base array")
; Add item delimited string
$aArray = $aArray_Base
$sFill = "New Item 2 - 0|New Item 2 - 1"
_ArrayAdd($aArray, $sFill)
_ArrayDisplay($aArray, "2D - Item delimited")
; Add row delimited string - load in col 1
$aArray = $aArray_Base
$sFill = "New Item 2 - 1" & @CRLF & "New Item 3 - 1"
_ArrayAdd($aArray, $sFill, 1)
_ArrayDisplay($aArray, "2D - Row Delimited")
; Add item & row delimited string
$aArray = $aArray_Base
$sFill = "New Item 2 - 0|New Item 2 - 1" & @CRLF & "New Item 3 - 0|New Item 3 - 1"
_ArrayAdd($aArray, $sFill)
_ArrayDisplay($aArray, "2D - Item & row Delimited")
; Add a 2D array
$aArray = $aArray_Base
Local $aFill[2][2] = [["New Item 2 - 1", "New Item 2 - 2"], ["New Item 3 - 1", "New Item 3 - 2"]]
_ArrayAdd($aArray, $aFill)
_ArrayDisplay($aArray, "2D - 2D Array")
; Add a 2D array - Single item/column - load in col 1
$aArray = $aArray_Base
Local $aFill[2][1] = [["New Item 2 - 1"], ["New Item 3 - 1"]]
_ArrayAdd($aArray, $aFill, 1)
_ArrayDisplay($aArray, "2D - 2D Array")
#include <Array.au3>
#include <MsgBoxConstants.au3>
Local $aArray_Base[2] = ["Org Item 0", "Org item 1"]
Local $aArray
Local $sFill = ""
For $i = 2 To 6
$sFill &= $i & "|" ; Note variables added as number datatype here
Next
$sFill = StringTrimRight($sFill, 1)
MsgBox($MB_SYSTEMMODAL, "Delimited string to add", $sFill)
; Add items by delimited string
$aArray = $aArray_Base
_ArrayAdd($aArray, $sFill)
_ArrayDisplay($aArray, "Converted to string")
; But converted to string datatype when inserted
MsgBox($MB_SYSTEMMODAL, "Result", "Data:" & @TAB & $aArray[6] & @CRLF & "Datatype:" & @TAB & VarGetType($aArray[6]))
; Add items by delimited string
$aArray = $aArray_Base
; Now force datatype to Number
_ArrayAdd($aArray, $sFill, Default, Default, Default, $ARRAYFILL_FORCE_NUMBER)
_ArrayDisplay($aArray, "Forced to number")
; And datatype is forced to required type
MsgBox($MB_SYSTEMMODAL, "Result", "Data:" & @TAB & $aArray[6] & @CRLF & "Datatype:" & @TAB & VarGetType($aArray[6]))