Objet Collection

Les collections peuvent être utilisées pour stocker des éléments de différents types. Chaque élément est accessible par son index ou par une clé optionnelle qui lui est associée.

Un objet Collection a les méthodes suivantes :

• Add; insère un nouvel élément dans une collection. Facultativement, une valeur de chaîne peut être définie comme clé de l'élément.

• Count: renvoie le nombre d'éléments dans une collection.

• Item: renvoie l'élément de la collection en passant son index ou sa clé.

• Remove: supprime l'élément spécifié de la collection par son index ou sa clé.

Les éléments d'une collection sont accessibles soit par leurs indices (comme dans une matrice unidimensionnel basée sur 1), soit par leurs clés associées.

Le service ScriptForge Dictionary étend l'objet Collection en fournissant des fonctionnalités supplémentaires telles que la récupération et le remplacement de clés, ainsi que l'import/export vers des objets Array et des chaînes JSON.

Création d'une collection

Pour créer une Collection, utilisez le mot-clé New. L'exemple suivant crée un objet Collection et le remplit avec trois éléments :

    Dim myCollection as New Collection
    myCollection.Add("Some text")
    myCollection.Add(100)
    myCollection.Add(Array(1, 2, 3, 4))
    MsgBox myCollection.Count ' 3
  

Ajout d'éléments

La méthode Add peut être utilisée pour ajouter de nouveaux éléments dans l'objet Collection.

oCollection.Add(item, [key], [before|after])

item: l'élément à ajouter à la Collection. Peut être de n'importe quel type.

key: valeur de chaîne utilisée comme clé unique utilisée pour identifier cette valeur.

before, after: argument de mot-clé facultatif qui indique où le nouvel élément sera placé dans la Collection. Un seul des arguments before ou after peut être spécifié pour déterminer l'index ou la clé avant (ou après quoi) le nouvel élément doit être placé.

L'exemple ci-dessous ajoute deux éléments dans une Collection. Le premier a une clé qui lui est associée, alors que le second n'en a pas.

    Dim myCollection as New Collection
    myCollection.Add(100, "first")
    myCollection.Add(101)
  

La méthode Add prend également en charge les arguments de mots clés :

    myCollection.Add(item := 100, key := "first")
  

Les clés doivent être uniques dans un objet Collection. La comparaison entre les clés est insensible à la casse. L'ajout de clés dupliquées entraînera une erreur d'exécution.

L'exemple ci-dessous illustre comment utiliser les arguments des mots clés Before et After pour déterminer la position de l'élément qui est ajouté.

    Dim myCollection as Variant
    myCollection = New Collection
    myCollection.Add(item := 101, key := "first")
    myCollection.Add(item := 103, key := "third")
    myCollection.Add(item := 105, key := "fifth")
    MsgBox myCollection.Item(2) ' 103
    myCollection.Add(item := 102, key := "second", before := "third")
    MsgBox myCollection.Item(2) ' 102
    myCollection.Add(item := 104, key := "fourth", after := 3)
    MsgBox myCollection.Item(4) ' 104
  

Les éléments d'un objet Collection reçoivent une valeur d'index entière qui commence à 1 et correspond à l'ordre dans lequel ils ont été ajoutés.

Accéder aux éléments

Utilisez la méthode Item pour accéder à un élément donné par son index ou sa clé.

oCollection.Item(index)

oCollection.Item(key)

index: une valeur entière spécifiant l'index de l'élément à retourner.

key: une valeur de chaîne spécifiant la clé de l'élément à retourner.

    Dim myCollection as New Collection
    myCollection.Add(item := 101, key := "A")
    myCollection.Add(item := 102, key := "B")
    myCollection.Add(item := 103, key := "C")
    MsgBox myCollection.Item("A") ' 101
    MsgBox myCollection.Item(3)   ' 103
  

Supprimer des éléments

Utilisez la méthode Remove pour supprimer des éléments d'un objet Collection.

Les éléments peuvent être supprimés soit par leurs indices, soit par leurs valeurs clés.

oCollection.Remove(index)

oCollection.Remove(key)

index: une valeur entière spécifiant l'index de l'élément à supprimer.

key: une valeur de chaîne spécifiant la clé de l'élément à supprimer.

    Dim myCollection as New Collection
    myCollection.Add(item := 101, key := "first")
    myCollection.Add(item := 102, key := "second")
    myCollection.Add(item := 103, key := "third")
    MsgBox myCollection.Count ' 3
    ' Removes the  first value
    myCollection.Remove(1)
    ' Removes the value whose key is "third"
    myCollection.Remove("third")
    MsgBox myCollection.Count ' 1
  

Itérer sur tous les éléments

Il est possible d'utiliser une instruction For Each ... Next pour parcourir tous les éléments d'une Collection.

    Dim myCollection as New Collection
    myCollection.Add(item := 101, key := "A")
    myCollection.Add(item := 102, key := "B")
    myCollection.Add(item := 103, key := "C")
    For Each value In myCollection
        MsgBox value
    Next value
  

Effacer une collection

Pour supprimer tous les éléments d'un objet Collection, appelez la méthode Remove pour chaque élément, comme illustré dans l'exemple ci-dessous :

    ' Créer un exemple de collection avec deux entrées
    Dim myCollection as New Collection
    myCollection.Add(item := 10, key := "A")
    myCollection.Add(item := 11, key := "B")
    MsgBox myCollection.Count ' 2
    ' Supprime tous les éléments de la collection
    For i = myCollection.Count To 1 Step -1
    	myCollection.Remove(i)
    Next i
    MsgBox myCollection.Count ' 0