Objeto de coleção

As coleções podem ser utilizadas para armazenar itens de diferentes tipos. É possível aceder a cada item através do seu índice ou de uma chave opcional que lhe esteja associada.

Um objeto Collection possui os seguintes métodos:

• Adicionar: insere um novo item na coleção. Opcionalmente, pode definir-se um valor de cadeia de caracteres como chave do item.

• Count: devolve o número de itens na coleção.

• Item: devolve o item da coleção ao passar o seu índice ou chave.

• Remover: remove o item especificado da coleção pelo seu índice ou chave.

É possível aceder aos elementos de uma coleção quer através dos seus índices (tal como num array unidimensional com indexação a partir de 1), quer através das chaves que lhes estão associadas.

O serviço ScriptForge Dictionary alarga o objeto Collection, fornecendo funcionalidades adicionais, tais como a recuperação e substituição de chaves, bem como a importação/exportação para objetos Array e cadeias de caracteres JSON.

Criar uma coleção

Para criar uma Collection, utilize a palavra-chave New. O exemplo seguinte cria um objeto Collection e preenche-o com 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
  

Adicionar artigos

O método Add pode ser utilizado para adicionar novos itens ao objeto Collection.

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

item: o item a ser adicionado à Coleção. Pode ser de qualquer tipo.

chave: valor de cadeia de caracteres utilizado como chave única para identificar este valor.

before, after: argumento opcional que indica onde o novo item será colocado na Coleção. Apenas um dos argumentos before ou after pode ser especificado para determinar o índice ou a chave antes da qual (ou após a qual) o novo item deve ser colocado.

O exemplo abaixo adiciona dois elementos a uma Collection. O primeiro tem uma chave associada, ao passo que o segundo não tem.

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

O método Add também suporta argumentos-chave:

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

As chaves devem ser únicas num objeto Collection. A comparação entre chaves não distingue maiúsculas de minúsculas. A adição de chaves duplicadas resultará num erro de execução.

O exemplo abaixo ilustra como utilizar os argumentos-chave Before e After para determinar a posição do item que está a ser adicionado.

    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
  

Aos elementos de um objeto Collection é atribuído um valor de índice inteiro que começa em 1 e corresponde à ordem em que foram adicionados.

Aceder a itens

Utilize o método Item para aceder a um determinado item pelo seu índice ou chave.

oCollection.Item(index)

oCollection.Item(key)

índice: um valor inteiro que especifica o índice do item a ser devolvido.

key: um valor de cadeia de caracteres que especifica a chave do item a ser devolvido.

    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
  

Remover itens

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

Os elementos podem ser removidos quer pelos seus índices, quer pelos valores das chaves.

oCollection.Remove(index)

oCollection.Remove(key)

índice: um valor inteiro que especifica o índice do item a remover.

chave: um valor de cadeia de caracteres que especifica a chave do item a remover.

    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
  

Percorrer todos os itens

É possível utilizar uma instrução For Each ... Next para percorrer todos os itens de uma 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
  

Limpar uma coleção

Para remover todos os itens de um objeto Collection, chame o método Remove para cada item, conforme ilustrado no exemplo abaixo:

    ' Criar uma coleção de exemplo com duas entradas
    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