Obsah

# Objekt Collection

Kolekce lze používat k uchování položek různých typů. Ke každé položce lze přistupovat pomocí jejího indexu nebo pomocí volitelného klíče, který k ní je přiřazen.

Objekt Collection má následující metody:

- Add: vloží do kolekce novou položku. Volitelně lze definovat řetězec, který bude klíčem položky.

- Count: vrátí počet položek v kolekci.

- Item: vrátí položku kolekce podle jejího indexu nebo klíče.

- Remove: odstraní z kolekce položku určenou podle jejího indexu nebo klíče.

K položkám v kolekci lze přistupovat buď pomocí jejích indexů (jako v jednorozměrném poli číslovaném od 1), nebo pomocí přiřazených klíčů.

Služba ScriptForge Dictionary rozšiřuje objekt Collection o dodatečné funkce jako získávání a nahrazování klíčů nebo import a export do objektů polí a řetězců JSON.

## Vytvoření kolekce

Objekt Collection vytvoříte pomocí klíčového slova New. V následujícím příkladu je vytvořen objekt Collection a naplněn třemi položkami:

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

## Přidání položek

K přidávání nových položek do objektu Collection se používá metoda Add.

### Syntaxe:

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

### Parametry:

item: položka, která se má do objektu Collection přidat. Může být jakéhokoliv typu.

key: řetězec použitý jako jedinečný klíč identifikující tuto hodnotu.

before, after: klíčové slovo pro nepovinný argument, který určuje, kam se nová položka v objektu Collection umístí. Zadán může být pouze jediný z argumentů before a after. Argument určuje index nebo klíč, před který (či za který) se nová položka umístí.

### Příklad:

V tomto příkladu se do objektu Collection přidají dva prvky. K prvnímu je přiřazen klíč, zatímco ke druhému není.

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

Metoda Add podporuje také argumenty s klíčovými slovy:

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

Klíče musí být v rámci objektu Collection jedinečné. Při porovnávání klíčů se nerozlišuje velikost písmen. Přidání duplicitního klíče způsobí běhovou chybu.

Následující příklad ukazuje, jak použít pro určení umístění přidávané položky argumenty before a after.

        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

Položkám v objektu Collection jsou přiřazeny hodnoty celočíselných indexů, které začínají od 1 a odpovídají pořadí, v němž byly položky přidány.

## Přístup k položkám

K přístupu k položce podle indexu nebo klíče se používá metoda Item.

oCollection.Item(index)

oCollection.Item(key)

### Parametry:

index: celočíselná hodnota určující index položky, která se má vrátit.

key: řetězec určující klíč položky, která se má vrátit.

### Příklad:

        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

## Odstranění položek

K odstranění položek z objektu Collection se používá metoda Remove.

### Syntaxe:

Položky lze odstraňovat buď podle indexů, nebo podle klíčů.

oCollection.Remove(index)

oCollection.Remove(key)

### Parametry:

index: celočíselná hodnota určující index položky, která se má odstranit.

key: řetězec určující klíč položky, která se má odstranit.

### Příklad:

        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

## Iterování přes všechny položky

Přes všechny položky v objektu Collection lze iterovat pomocí příkazu For Each ... Next.

        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

## Vymazání kolekce

Chcete-li všechny položky objektu Collection vymazat, zavolejte pro každou z nich metodu Remove, jak ukazuje následující příklad:

        ' Vytvoří ukázkovou kolekci se dvěma položkami
        Dim myCollection as New Collection
        myCollection.Add(item := 10, key := "A")
        myCollection.Add(item := 11, key := "B")
        MsgBox myCollection.Count ' 2
        ' Odstraní z kolekce všechny položky
        For i = myCollection.Count To 1 Step -1
        	myCollection.Remove(i)
        Next i
        MsgBox myCollection.Count ' 0

Související témata

Funkce Array

Služba ScriptForge.Dictionary