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