###User Defined Function###
_ArrayAdd

###Description###
Adds a specified value at the end of an existing 1D or 2D array

###Syntax###
#include <Array.au3>
_ArrayAdd ( ByRef $aArray, $vValue [, $iStart = 0 [, $sDelim_Item = "|" [, $sDelim_Row = @CRLF [, $hDataType = 0]]]] )


###Parameters###
@@ParamTable@@
$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)
$hDataType
	[optional] Variable to which a datatype function (e.g. Number, HWnd) has been assigned.  If $vValue is a delimited string, forces items into that datatype.
@@End@@

###ReturnValue###
@@ReturnTable@@
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 1D or 2D 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
@@End@@


###Remarks###
If $vValue is a delimited string all items are added to 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.

Addition mode depends on $vValue type:

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.


###Related###
_ArrayConcatenate, _ArrayDelete, _ArrayInsert, _ArrayPop, _ArrayPush


###Example###
@@IncludeExample@@
