Conteúdo

# 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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

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)

### Parâmetros:

í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.

### 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

## Remover itens

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

### Sintaxe:

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

oCollection.Remove(index)

oCollection.Remove(key)

### Parâmetros:

í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.

### 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

## 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

Tópicos relacionados

Função de matriz

ScriptForge.Dicionário serviço

Necessitamos da sua ajuda!