Spis treści

# Obiekt Collection

Kolekcje mogą służyć do przechowywania elementów różnego typu. Dostęp do każdego elementu można uzyskać za pomocą jego indeksu lub opcjonalnego klucza z nim powiązanego.

Obiekt Collection ma następujące metody:

- Add: wstawia nowy element do kolekcji. Opcjonalnie wartość ciągu może być zdefiniowana jako klucz do elementu.

- Count: zwraca liczbę elementów w kolekcji.

- Item: zwraca element w kolekcji, przekazując jego indeks lub klucz.

- Remove: usuwa określony element z kolekcji według jego indeksu lub klucza.

Dostęp do elementów w kolekcji można uzyskać za pomocą ich indeksów (jak w jednowymiarowej tablicy opartej na 1) lub powiązanych z nimi kluczy.

Usługa ScriptForge Dictionary rozszerza obiekt Collection, udostępniając dodatkowe funkcje jako klucz pobieranie i zastępowanie, a także import/eksport do obiektów tablicowych i łańcuchów JSON.

## Tworzenie kolekcji

Aby utworzyć Collection, użyj słowa kluczowego New. Poniższy przykład tworzy obiekt Collection i zapełnia go trzema elementami:

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

## Dodawanie elementów

Metoda Add może być użyta do dodania nowych elementów do obiektu Collection.

### Składnia:

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

### Parametry:

item: element, który ma zostać dodany do Collection. Może być dowolnego typu.

key: wartość ciągu używana jako unikalny klucz używany do identyfikacji tej wartości.

before, after: opcjonalne słowo kluczowe, które wskazuje, gdzie nowy element zostanie umieszczony w Collection. Tylko jeden z argumentów before lub after może być podany w celu określenia indeksu lub klucza, przed którym (lub po którym) ma zostać umieszczona nowa pozycja.

### Przykład:

Poniższy przykład dodaje dwa elementy do Collection. Z pierwszym skojarzony jest klucz, a z drugim nie.

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

Metoda Add obsługuje również argumenty słów kluczowych:

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

Klucze muszą być unikalne w obiekcie Collection. W porównaniu kluczy wielkość liter nie jest rozróżniana. Dodanie zduplikowanych kluczy spowoduje błąd w czasie wykonywania.

Poniższy przykład ilustruje, jak używać argumentów słów kluczowych Before i After w celu określenia pozycji dodawanego elementu.

        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

Elementom w obiekcie Collection przypisywana jest wartość indeksu liczb całkowitych, która zaczyna się od 1 i odpowiada kolejności, w jakiej zostały dodane.

## Dostęp do elementów

Użyj metody Item, aby uzyskać dostęp do danego elementu za pomocą jego indeksu lub klucza.

oCollection.Item(index)

oCollection.Item(key)

### Parametry:

index: wartość całkowita określająca indeks elementu, który ma zostać zwrócony.

key: wartość ciągu określająca klucz elementu, który ma zostać zwrócony.

### Przykład:

        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

## Usuwanie elementów

Użyj metody Remove, aby usunąć elementy z obiektu Collection.

### Składnia:

Elementy można usuwać na podstawie ich indeksów lub wartości kluczy.

oCollection.Remove(index)

oCollection.Remove(key)

### Parametry:

index: wartość całkowita określająca indeks pozycji do usunięcia.

key: wartość ciągu określająca klucz elementu do usunięcia.

### Przykład:

        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

## Iteracja po wszystkich elementach

Możliwe jest użycie instrukcji For Each ... Next do iteracji po wszystkich elementach w 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

## Czyszczenie kolekcji

Aby usunąć wszystkie elementy z obiektu Collection, wywołaj metodę Remove dla każdego elementu, jak pokazano w poniższym przykładzie:

        ' Utwórz przykładową kolekcję z dwoma wpisami
        Dim myCollection as New Collection
        myCollection.Add(item := 10, key := "A")
        myCollection.Add(item := 11, key := "B")
        MsgBox myCollection.Count ' 2
        ' Usuwa wszystkie elementy w kolekcji
        For i = myCollection.Count To 1 Step -1
        	myCollection.Remove(i)
        Next i
        MsgBox myCollection.Count ' 0

Tematy pokrewne

Instrukcja Array

Usługa ScriptForge.Dictionary