Обект Collection

В колекциите можете да съхранявате елементи от различни типове. Достъпът до всеки елемент може да се осъществява чрез индекса му или чрез незадължителен ключ, свързан с него.

Обектите от тип Collection имат следните методи:

Add: вмъква нов елемент в колекцията. По желание може да се зададе низова стойност като ключ на елемента.
Count: връща броя на елементите в колекцията.
Item: връща елемента от колекцията по подаден индекс или ключ.
Remove: премахва указания елемент от колекцията по индекса или ключа му.

Достъпът до елементите в обект от тип Collection може да се осъществява или по индексите им (като в едномерен масив, индексиран от 1), или по свързаните с тях ключове.

Услугата ScriptForge Dictionary разширява обекта Collection с допълнителни функции като извличане и замяна на ключове, както и импортиране/експортиране към обекти от тип Array и низове във формат JSON.

Създаване на колекция

За да създадете обект от тип Collection, използвайте ключовата дума New. Следващият пример създава обект Collection и го попълва с три елемента:


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

Добавяне на елементи

Методът Add служи за добавяне на нови елементи в обекта от тип Collection.

Синтаксис:

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

Параметри:

item: елементът, който да бъде добавен към обекта Collection. Може да бъде от произволен тип.

key: низова стойност, използвана като уникален ключ за идентифициране на този елемент.

before, after: незадължителен аргумент с ключова дума, който указва къде в обекта Collection ще бъде поставен новият елемент. Може да бъде зададен само един от аргументите before или after, за да се определи индексът или ключът, преди който (или след който) да бъде вмъкнат новият елемент.

Пример:

Примерният код по-долу добавя два елемента в обект от тип Collection. Първият е асоцииран с ключ, а вторият не е.


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

Методът Add поддържа и аргументи с ключови думи:


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

Ключовете трябва да бъдат уникални в рамките на обекта Collection. Сравняването на ключове е нечувствително към регистъра. Добавянето на дублирани ключове ще предизвика грешка по време на изпълнение.

Следващият пример илюстрира употребата на аргументите с ключови думи Before и 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

На елементите в обект от тип Collection се присвояват целочислени индексни стойности, които започват от 1 и съответстват на реда на добавяне.

Достъп до елементи

За достъп до даден елемент по индекса или ключа му използвайте метода Item.

oCollection.Item(index)

oCollection.Item(key)

Параметри:

index: целочислена стойност, указваща индекса на елемента, който да бъде върнат.

key: низова стойност, указваща ключа на елемента, който да бъде върнат.

Пример:


    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

Премахване на елементи

Методът Remove служи за изтриване на елементи от обект от тип Collection.

Синтаксис:

Елементите могат да се премахват по индекс или по ключ.

oCollection.Remove(index)

oCollection.Remove(key)

Параметри:

index: целочислена стойност, указваща индекса на елемента, който да бъде премахнат.

key: низова стойност, указваща ключа на елемента, който да бъде премахнат.

Пример:


    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

Итериране през всички елементи

С оператора For Each ... Next може да се обходят всички елементи в даден обект от тип 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

Изчистване на колекция

За да премахнете всички елементи от обект Collection, използвайте метода Remove за всеки от елементите, както е показано в следния пример:


    ' Създаване на примерна колекция с два елемента
    Dim myCollection as New Collection
    myCollection.Add(item := 10, key := "A")
    myCollection.Add(item := 11, key := "B")
    MsgBox myCollection.Count ' 2
    ' Премахва всички елементи в колекцията.
    For i = myCollection.Count To 1 Step -1
    	myCollection.Remove(i)
    Next i
    MsgBox myCollection.Count ' 0

Функция Array

ScriptForge.Dictionary service