UDF > Array >

_ArrayAdd

Ajoute une valeur sp�cifi�e � la fin d'un tableau existant 1D ou 2D

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

Param�tres

$aArray Tableau � modifier
$vValue Valeur(s) � ajouter, qui peut �tre un �l�ment simple, une cha�ne avec s�parateurs ou un tableau
$iStart [optionnel] Colonne o� l'ajout commence (tableau 2D seulement)
$sDelim_Item [optionnel] S�parateur � utiliser si la cha�ne a �t� �clat�e en �l�ments
$sDelim_Row [optionnel] S�parateur � utiliser si la cha�ne a �t� �clat�e en lignes de tableau (tableau 2D seulement)
$iForce [optionnel] Maintient le comportement par d�faut,
    ARRAYFILL_FORCE_DEFAULT (0)
Force l'addition de $vValue comme �l�ment unique,
    $ARRAYFILL_FORCE_SINGLEITEM (1)
Ou force le type de donn�es pour tous les �l�ments ajout�s
    $ARRAYFILL_FORCE_INT (2)
    $ARRAYFILL_FORCE_NUMBER (3)
    $ARRAYFILL_FORCE_PTR (4)
    $ARRAYFILL_FORCE_HWND (5)
    $ARRAYFILL_FORCE_STRING (6)
    $ARRAYFILL_FORCE_BOOLEAN (7)
Voir Remarques pour plus de d�tails

Valeur de retour

Succ�s: Retourne l'index du dernier �l�ment ajout�
�chec: Retourne -1 et d�finit @error <> 0
@error: 1 - $aArray n'est pas un tableau
2 - $aArray n'est pas un tableau de dimension 1 ou 2
3 - $vValue a trop de colonnes pour s'adapter � $aArray
4 - $iStart est en dehors des limites du tableau (2D seulement)
5 - Le nombre de dimensions des tableaux $aArray et $vValue ne correspondent pas

Remarques

Le mode d'insertion d�pend du type de $vValeur, mais l'utilisation de $iForce peut modifier ceci. Le comportement par d�faut est le suivant:

Tableaux 1D:
    El�ment unique - ajoute un �l�ment
    Cha�ne avec s�parateurs $sDelim_Item - ajoute autant d'�l�ments que de sous-cha�nes
    Tableau 1D de base 0 - ajoute autant d'�l�ments qu'il y a d'�l�ments dans le tableau

Tableaux 2D:
    Cha�ne avec s�parateurs $sDelim_Item - ajoute une ligne, les colonnes sont remplies si il y a assez de sous-cha�nes
    Cha�ne avec s�parateurs $sDelim_Row - ajoute autant de lignes que de sous-cha�nes, une seule colonne est remplie
    Cha�ne avec s�parateurs $sDelim_Item & Row - ajoute des lignes et des �l�ments, selon les sous-cha�nes
    Tableau 2D de base 0 - ajoute autant de lignes/colonnes que dans le tableau

Une cha�ne vide ("") est ajout�e s'il n'y a pas suffisamment d'�l�ments sp�cifi�s dans $vValeur. Les �l�ments en exc�s sont ignor�s.

La d�finition du param�tre $iForce peut modifier le comportement par d�faut de l'insertion ou modifier le type de donn�es pour les �l�ments ajout�s. Il peut �tre d�fini comme suit:
$ARRAYFILL_FORCE_DEFAULT (par d�faut):
    - Les �l�ments sont �clat�s de la mani�re d�crite ci-dessus. Les �l�ments uniques et les �l�ments d'un tableau conservent leurs types de donn�es - les cha�nes avec s�parateurs sont ajout�es sous forme de cha�nes.

$ARRAYFILL_FORCE_SINGLEITEM:
    - Si $aArray est un tableau 1D, $vValeur est ajout�e comme �l�ment unique.
    - Si $aArray est un tableau 2D, le param�tre est ignor�.

$ARRAYFILL_FORCE_INT, $ARRAYFILL_FORCE_NUMBER, $ARRAYFILL_FORCE_PTR, $ARRAYFILL_FORCE_HWND, $ARRAYFILL_FORCE_STRING, $ARRAYFILL_FORCE_BOOLEAN
    - Si $vValeur est un �l�ment unique, il est forc� dans le type de donn�es d�fini - par d�faut, il conserverait son type de donn�es existant.
    - Si $vValeur est une cha�ne avec s�parateurs, tous les �l�ments sont forc�s dans le type de donn�es sp�cifi� - par d�faut, ils seraient ajout�s au tableau sous forme de cha�nes. Si diff�rents types de donn�es sont n�cessaires pour les �l�ments, ils doivent �tre pass�s comme un tableau.
    - Si $vValeur est un tableau, le param�tre est ignor� et les �l�ments du tableau sont ajout�s en conservant leurs types de donn�es existants.

Si $iForce est d�fini sur toute autre valeur, il est ignor�.

Notez que $ARRAYFILL_FORCE_BOOLEAN regarde les cha�nes litt�rales de la fa�on suivante:
- "True" et "1" comme True
- "False", "0" et "" (cha�ne vide) comme False

La fonction ne met PAS � jour le nombre des �l�ments dans le tableau, mais la valeur de retour de la fonction (en cas de succ�s) donne le nouvel index de ligne le plus �lev� du tableau.

En relation

_ArrayConcatenate, _ArrayDelete, _ArrayInsert, _ArrayPop, _ArrayPush

Exemples

Exemple 1

#include <Array.au3>
#include <MsgBoxConstants.au3>

Local $aArray_Base[2] = ["Org Item 0", "Org item 1"]
_ArrayDisplay($aArray_Base, "1D - Tableau de base")

; Ajoute un �l�ment unique
Local $aArray = $aArray_Base
Local $sSingleFill = "New Item 2"
_ArrayAdd($aArray, $sSingleFill)
_ArrayDisplay($aArray, "1D - Unique")

; Ajoute une cha�ne avec s�parateurs - chaque sous-cha�ne ins�re un nouvel �l�ment
$aArray = $aArray_Base
Local $sFill = ""
For $i = 1 To 5
    $sFill &= "New Item " & String($i + 1) & "|"
Next
$sFill = StringTrimRight($sFill, 1)
MsgBox($MB_SYSTEMMODAL, "Cha�ne avec s�parateurs � ajouter", $sFill)
_ArrayAdd($aArray, $sFill)
_ArrayDisplay($aArray, "1D - Cha�ne avec s�parateurs")

; Ins�re un tableau 1D - chaque sous-cha�ne ins�re un nouvel �l�ment
$aArray = $aArray_Base
Local $aFill[5]
For $i = 0 To 4
    $aFill[$i] = "New Item " & String($i + 2)
Next
_ArrayDisplay($aFill, "Tableau � ajouter")
_ArrayAdd($aArray, $aFill)
_ArrayDisplay($aArray, "1D - Tableau 1D")

Exemple 2

#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 - Tableau de base")

; Ajoute les sous-cha�nes de la cha�ne avec s�parateurs
$aArray = $aArray_Base
$sFill = "New Item 2 - 0|New Item 2 - 1"
_ArrayAdd($aArray, $sFill)
_ArrayDisplay($aArray, "2D - Cha�ne avec s�parateurs")

; Ajoute une ligne � partir d'un cha�ne avec s�parateurs - charg� en colonne 1
$aArray = $aArray_Base
$sFill = "New Item 2 - 1" & @CRLF & "New Item 3 - 1"
_ArrayAdd($aArray, $sFill, 1)
_ArrayDisplay($aArray, "2D - Ligne avec s�parateurs")

; Ajoute �l�ment & ligne de la cha�ne avec s�parateurs
$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 - El�ment & ligne avec s�parateurs")

; Ajoute un tableau 2D
$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 - Tableau 2D")

; Ajoute un tableau 2D - un seul �l�ment/colonne - charg� dans la colonne 1
$aArray = $aArray_Base
Local $aFill[2][1] = [["New Item 2 - 1"],["New Item 3 - 1"]]
_ArrayAdd($aArray, $aFill, 1)
_ArrayDisplay($aArray, "2D - Tableau 2D")

Exemple 3

#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 &= String($i) & "|" 
Next
; Enl�ve le dernier s�parateur
$sFill = StringTrimRight($sFill, 1)
MsgBox($MB_SYSTEMMODAL, "Cha�ne avec s�parateur � ajouter", $sFill)

; Ins�re des �l�ments � partir d'une cha�ne avec s�parateurs
$aArray = $aArray_Base
_ArrayAdd($aArray, $sFill)
_ArrayDisplay($aArray, "Converti en cha�ne")
; Mais converti en type de donn�e cha�ne lors de l'insertion
MsgBox($MB_SYSTEMMODAL, "R�sultat", "Donn�e:" & @TAB & $aArray[6] & @CRLF & "Type de donn�e:" & @TAB & VarGetType($aArray[6]))

; Ajoute des �l�mens � partir d'une cha�ne avec s�parateurs
$aArray = $aArray_Base
; Maintenant force le type de donn�es � Number
Local $hDataType = Number
_ArrayAdd($aArray, $sFill, Default, Default, Default, $hDataType)
_ArrayDisplay($aArray, "For�� � Number")
; Et le type de donn�e est for�� au type requis
MsgBox($MB_SYSTEMMODAL, "Resultat", "Donn�e:" & @TAB & $aArray[6] & @CRLF & "Type de donn�e:" & @TAB & VarGetType($aArray[6]))