Objeto Collection

Coleções podem ser usadas para armazenar itens de diferentes tipos. Cada item pode ser acessado por seu índice ou por uma chave opcional associada ao item.

Um objeto Collection possui os seguintes métodos:

Add: Insere um novo item na coleção. Opcionalmente, um valor textual (string) pode ser definido como a chave para acessar o item.
Count: Retorna o número de itens na coleção.
Item: Retorna o item na coleção correspondente ao índice ou chave passado como argumento.
Remove: Remove o item especificado da coleção usando seu índice ou chave.

Itens em uma coleção pode ser acessados tanto por seus índices (como em um Array com índices iniciando em 1) como por suas chaves associadas.

O serviço ScriptForge Dictionary estende o objeto Collection ao fornecer funcionalidades adicionais como a remoção e substituição de chaves e a importação/exportação de objetos Array e strings JSON.

Criando uma coleção

Para criar um objeto Collection utilize o comando New. O seguinte exemplo cria um objeto Collection e insere três itens:


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

Adicionando itens

O método Add pode ser usado para inserir novos itens ao objeto Collection.

Sintaxe:

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

Parâmetros:

item: Item a ser adicionado ao objeto Collection. Pode ser de qualquer tipo.

key: Valor string usado como chave única para identificar o item.

before, after: Argumentos opcionais que indicam onde o novo item será posicionado no objeto Collection. Apenas um dos argumentos before ou after pode ser especificado para determinar o índice ou chave antes (ou depois) do qual o novo item será posicionado.

Exemplo:

O exemplo abaixo insere dois elementos em um objeto Collection. O primeiro possui uma chave associada, porém o segundo não possui uma chave.


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

O método Add também suporta argumentos de palavras-chave.


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

Chaves devem ser únicas em um objeto Collection. A comparação entre chaves não é sensível à caixa. Inserir chaves duplicadas resultará em um erro de execução.

O exemplo abaixo ilustra como usar Before e After como argumentos de palavra-chave para determinar a posição do item que está sendo inserido.


    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

Itens em um objeto Collection recebem um valor de índice inteiro iniciando em 1, o qual corresponde à ordem em que foram adicionados à coleção.

Acessando itens

Use o método Item para acessar um item por meio de seu índice ou chave.

oCollection.Item(index)

oCollection.Item(key)

Parâmetros:

index: Valor inteiro especificando o índice do item a ser retornado.

key: String especificando a chave do item a ser retornado.

Exemplo:


    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

Removendo itens

Utilize o método Remove para excluir itens de um objeto Collection.

Sintaxe:

Itens podem ser removidos por seus índices ou chaves.

oCollection.Remove(index)

oCollection.Remove(key)

Parâmetros:

index: Valor inteiro especificando o índice do item a ser removido.

key: String especificando a chave do item a ser removido.

Exemplo:


    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

Iterando sobre todos os itens

É possível usar a instrução For Each ... Next para iterar sobre todos os itens de um objeto 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

Limpando uma coleção

Para remover todos os itens de um objeto Collection é necessário chamar o método Remove para todos os itens, conforme ilustrado no exemplo abaixo:


    ' Cria uma coleção com dois itens
    Dim myCollection as New Collection
    myCollection.Add(item := 10, key := "A")
    myCollection.Add(item := 11, key := "B")
    MsgBox myCollection.Count ' 2
    ' Remove todos os itens da coleção
    For i = myCollection.Count To 1 Step -1
    	myCollection.Remove(i)
    Next i
    MsgBox myCollection.Count ' 0

Função Array

Serviço ScriptForge.Dictionary