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) $ARRAYFILL_FORCE_BOOLEAN (7) 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, $ARRAYFILL_FORCE_BOOLEAN
- 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.
Note that $ARRAYFILL_FORCE_BOOLEAN regards literal strings as follows:
- "True" and "1" as True
- "False", "0" and "" (empty string) as False
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.
_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]))