Objeto Collection

Collections can be used to store items of different types. Each item can be accessed by its index or by an optional key associated with it.

Un objeto Collection posee los métodos siguientes:

• Add: inserts a new item into the collection. Optionally a string value can be defined as the key to the item.

• Count: returns the number of items in the collection.

• Item: returns the item in the collection by passing its index or key.

• Remove: removes the specified item from the collection by its index or key.

Items in a Collection can be accessed either by their indices (as in a 1-based single-dimensional Array) or by their associated keys.

The ScriptForge Dictionary service extends the Collection object by providing supplemental features as key retrieval and replacement, as well as import/export to Array objects and JSON strings.

Crear una colección

To create a Collection use the New keyword. The following example creates a Collection object and populates it with three items:

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

Añadir elementos

The Add method can be used to add new items into the Collection object.

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

item: the item to be added to the Collection. May be of any type.

key: string value used as the unique key used to identify this value.

before, after: optional keyword argument that indicates where the new item will be placed in the Collection. Only one of the arguments before or after can be specified to determine the index or key before which (or after which) the new item is to be placed.

The example below adds two elements into a Collection. The first has a key associated with it, whereas the second does not.

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

El método Add admite asimismo argumentos en forma de palabras clave:

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

Keys must be unique in a Collection object. Comparison between keys is case-insensitive. Adding duplicated keys will result in a runtime error.

The example below illustrates how to use the Before and After keyword arguments to determine the position of the item that is being added.

    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
  

Items in a Collection object are assigned an integer index value that starts at 1 and corresponds to the order in which they were added.

Acceder a elementos

Use the Item method to access a given item by its index or key.

oCollection.Item(index)

oCollection.Item(key)

index: an integer value specifying the index of the item to be returned.

key: a string value specifying the key of the item to be returned.

    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
  

Quitar elementos

Sírvase del método Remove para eliminar elementos de un objeto Collection.

Es posible eliminar elementos tanto por sus índices como por sus claves.

oCollection.Remove(index)

oCollection.Remove(key)

index: an integer value specifying the index of the item to be removed.

key: a string value specifying the key of the item to be removed.

    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
  

Iterating Over all Items

It is possible to use a For Each ... Next statement to iterate over all items in a 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
  

Clearing a Collection

To remove all items from a Collection object call the Remove method for each item, as illustrated in the example below:

    ' Create a sample Collection with two entries
    Dim myCollection as New Collection
    myCollection.Add(item := 10, key := "A")
    myCollection.Add(item := 11, key := "B")
    MsgBox myCollection.Count ' 2
    ' Quita todos los elementos de la colección
    For i = myCollection.Count To 1 Step -1
    	myCollection.Remove(i)
    Next i
    MsgBox myCollection.Count ' 0