Contenuto

# Oggetto Collection

Potete usare le raccolte per memorizzare elementi di diverso tipo. Potete accedere a ogni elemento usando il suo indice o una chiave opzionale ad esso associata.

Un oggetto Collection possiede i seguenti metodi:

- Add: inserisce un nuovo elemento nella raccolta. Facoltativamente potete definire una stringa come chiave per l'elemento.

- Count: restituisce il numero di elementi nella raccolta.

- Item: restituisce un elemento della raccolta in base al suo indice o alla sua chiave.

- Remove: elimina l'elemento specificato dalla raccolta in base al suo indice o alla sua chiave.

Potete accedere agli elementi di una raccolta sia tramite il loro indice (come in una matrice unidimensionale con indice a partire da 1), sia tramite la chiave a essi associata.

Il servizio ScriptForge Dictionary estende l'oggetto Collection fornendo funzionalità supplementari come la ricerca e sostituzione delle chiavi o l'importazione/esportazione di oggetti Array e stringhe in formato JSON.

## Creazione di una raccolta

Per creare una raccolta (Collection) usate la parola chiave New. L'esempio seguente crea un oggetto Collection e lo riempie con tre elementi:

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

## Aggiunta di elementi

Potete usare il metodo Add per aggiungere nuovi elementi all'oggetto Collection.

### Sintassi:

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

### Parametri:

item: l'elemento da aggiungere all'oggetto Collection. Può essere di qualunque tipo.

key: stringa usata come chiave univoca per identificare questo valore.

before, after: argomento opzionale a parola chiave che indica il punto in cui l'elemento sarà inserito all'interno dell'oggetto Collection. Potete precisare solo uno degli argomenti before o after per determinare l'indice o la chiave prima (o dopo) il quale inserire il nuovo elemento.

### Esempio:

L'esempio sottostante aggiunge due elementi in un oggetto Collection. Il primo ha una chiave ad esso associata, mentre il secondo ne è privo.

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

Il metodo Add supporta anche degli argomenti a parola chiave:

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

All'interno di un oggetto Collection le chiavi devono essere univoche. Il confronto tra le chiavi non distingue tra lettere maiuscole e minuscole. L'aggiunta di chiavi duplicate comporterà un errore in fase di esecuzione.

L'esempio seguente illustra come usare gli argomenti a parola chiave Before e After per determinare la posizione dell'elemento che viene aggiunto.

        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

Agli elementi in un oggetto Collection è assegnato un numero intero come valore dell'indice a partire da 1, e che corrisponde all'ordine con cui sono stati inseriti.

## Accesso agli elementi

Usate il metodo Item per accedere a un determinato elemento in base al suo indice o alla sua chiave.

oCollection.Item(index)

oCollection.Item(key)

### Parametri:

index: un numero intero che specifica l'indice dell'elemento da restituire.

key: una stringa che specifica la chiave dell'elemento da restituire.

### Esempio:

        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

## Eliminazione di elementi

Usate il metodo Remove per eliminare degli elementi da un oggetto Collection.

### Sintassi:

Potete eliminare gli elementi usando il loro indice o la loro chiave.

oCollection.Remove(index)

oCollection.Remove(key)

### Parametri:

index: un numero intero che specifica l'indice dell'elemento da eliminare.

key: una stringa che specifica la chiave dell'elemento da eliminare.

### Esempio:

        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

## Iterazione su tutti gli elementi

Potete usare un'istruzione For Each ... Next per effettuare un'iterazione su tutti gli elementi di un oggetto 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

## Ripulitura di una raccolta

Per eliminare tutti gli elementi di un oggetto Collection richiamate il metodo Remove per ogni elemento, come illustrato nell'esempio sottostante:

        ' Crea una raccolta di esempio con due elementi
        Dim myCollection as New Collection
        myCollection.Add(item := 10, key := "A")
        myCollection.Add(item := 11, key := "B")
        MsgBox myCollection.Count ' 2
        ' Elimina tutti gli elementi dalla raccolta
        For i = myCollection.Count To 1 Step -1
        	myCollection.Remove(i)
        Next i
        MsgBox myCollection.Count ' 0

Argomenti correlati

Funzione Array

Servizio ScriptForge.Dictionary