Class

# Collection

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Used to store a set of related items in a larger structure. The concept of a <span class="title-ref">Collection</span> is similar to that of an array, except that each element in a <span class="title-ref">Collection</span> can be a different data type. A <span class="title-ref">Collection</span> can be thought of as an array of `variants</api/data_types/variant>`. Also, each element in a <span class="title-ref">Collection</span> can be named. Elements in a <span class="title-ref">Collection</span> can be referred to either by number or name.

<div class="tip">

<div class="title">

Tip

</div>

This class is primarily for Visual Basic compatibility. The `Dictionary</api/language/dictionary>` class provides the same functionality but with greater speed.

</div>

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                        | Parameters                                                                               | Returns                            | Shared |
|-----------------------------|------------------------------------------------------------------------------------------|------------------------------------|--------|
| `Add<collection.add>`       | Value As `Variant</api/data_types/variant>`, \[Key As `String</api/data_types/string>`\] |                                    |        |
| `Count<collection.count>`   |                                                                                          | `Integer</api/data_types/integer>` |        |
| `Item<collection.item>`     | index As `Integer</api/data_types/integer>`                                              | `Variant</api/data_types/variant>` |        |
| `Key<collection.key>`       | index As `Integer</api/data_types/integer>`                                              | `Variant</api/data_types/variant>` |        |
| `Remove<collection.remove>` | index As `Integer</api/data_types/integer>`                                              |                                    |        |

## Method descriptions

<div id="collection.add">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Collection.Add

**Add**(Value As `Variant</api/data_types/variant>`, \[Key As `String</api/data_types/string>`\])

> Adds *Value* as the last element of the <span class="title-ref">Collection</span>.
>
> If *Key* is provided, it may be used to refer to the element using the Item property. *Key* defaults to the empty string.
>
> The following code creates a <span class="title-ref">Collection</span>, populates it with both `string</api/data_types/string>` and numeric values, and displays each element in `TextFields</api/user_interface/desktop/desktoptextfield>` or a `Canvas</api/user_interface/desktop/desktopcanvas>` control (The picture "lois" has been added to the project). Note that a <span class="title-ref">Collection</span> is much like a database record.
>
> ``` xojo
> Var c As New Collection
> c.Add(1, "ID")
> c.Add("Lois Lane", "Name")
> c.Add("Reporter", "JobTitle")
> c.Add(85000, "Salary")
> c.Add(lois, "Picture")
> TextField1.Text = c.Item("ID")
> TextField2.Text = c.Item(2) ' returns "Lois Lane"
> TextField3.Text = c.Item("JobTitle")
> TextField4.Text = c.Item("Salary")
> Canvas1.Backdrop = c.Item("Picture")
> ```

<div id="collection.count">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Collection.Count

**Count** As `Integer</api/data_types/integer>`

> The number of elements in the <span class="title-ref">Collection</span>. Returns an `integer</api/data_types/integer>`. Each element is a *Value*, *Key* pair.
>
> The following code displays the value of Count in a `TextField</api/user_interface/desktop/desktoptextfield>`.
>
> ``` xojo
> Var c As New Collection
> c.Add(1, "ID")
> c.Add("Lois Lane", "Name")
> c.Add("Reporter", "JobTitle")
> c.Add(85000, "Salary")
> c.Add(lois, "Picture") ' lois is a Picture added to the project
> TextField1.Text = c.Item("ID")
> TextField2.Text = c.Item(2) ' returns "Lois Lane"
> TextField3.Text = c.Item("JobTitle")
> TextField4.Text = c.Item("Salary")
> Canvas1.Backdrop = c.Item("Picture")
>
> TextField5.Text = c.Count.ToString
> ```

<div id="collection.item">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Collection.Item

**Item**(index As `Integer</api/data_types/integer>`) As `Variant</api/data_types/variant>`

> Refers to an element of a <span class="title-ref">Collection</span> by the value of its Key.
>
> The following code displays the elements in the <span class="title-ref">Collection</span> using Item.
>
> ``` xojo
> Var c As New Collection
> c.Add(1, "ID")
> c.Add("Lois Lane", "Name")
> c.Add("Reporter", "JobTitle")
> c.Add(85000, "Salary")
> c.Add(lois, "Picture") ' lois is a Picture added to the project
> TextField1.Text = c.Item("ID")
> TextField2.Text = c.Item(2) ' returns "Lois Lane"
> TextField3.Text = c.Item("JobTitle")
> TextField4.Text = c.Item("Salary")
> Canvas1.Backdrop = c.Item("Picture")
> ```

<div id="collection.key">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Collection.Key

**Key**(index As `Integer</api/data_types/integer>`) As `Variant</api/data_types/variant>`

> Refers to the key for an element of a <span class="title-ref">Collection</span>. *index* is 1-based.
>
> The following code fetches some elements in the \`Collection\`:
>
> ``` xojo
> Var c As New Collection
> c.Add(1, "ID")
> c.Add("Lois Lane", "Name")
> c.Add("Reporter", "JobTitle")
> c.Add(85000, "Salary")
> Var name As String = c.Item(2) ' returns "Lois Lane"
> Var nameKey As String = c.Key(2) ' returns "Name"
> ```

<div id="collection.remove">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

Collection.Remove

**Remove**(index As `Integer</api/data_types/integer>`)

> Removes the element of a <span class="title-ref">Collection</span> specified by the value of its Key.
>
> This code removes the first element.
>
> ``` xojo
> Var c As New Collection
> .
> .
> c.Remove(1)
> ```
>
> If you want to use the Item or Remove methods to refer to an item, use parentheses around the parameter passed to the method. This is because the compiler doesn't know which data type you are passing. For example, use
>
> ``` xojo
> c.Remove("Name")
> ```
>
> rather than
>
> ``` xojo
> c.Remove "Name"
> ```

## Notes

The `Dictionary</api/language/dictionary>` class provides all the functionality of the <span class="title-ref">Collection</span> class and offers several advantages: With the <span class="title-ref">Collection</span> class, the time taken to locate an item is a function of the number of items in the <span class="title-ref">Collection</span> because the search is sequential. A `Dictionary</api/language/dictionary>` uses a hash table, making the time (relatively) independent of the number of items. It is designed for high-speed lookups. Also, the key parameter in a `Dictionary</api/language/dictionary>` is a `Variant</api/data_types/variant>`, but is a `String</api/data_types/string>` in the <span class="title-ref">Collection</span> class. Therefore, we recommend that you use the `Dictionary</api/language/dictionary>` class rather than the <span class="title-ref">Collection</span> class whenever possible.

## Sample code

The following example creates a <span class="title-ref">Collection</span>, populates it with both `string</api/data_types/string>` and numeric values, and displays each element in `TextFields</api/user_interface/desktop/desktoptextfield>` or a `Canvas</api/user_interface/desktop/desktopcanvas>` control (The picture "lois" has been added to the project). Note that a <span class="title-ref">Collection</span> is much like a database record.

``` xojo
Var c As New Collection
c.Add(1, "ID")
c.Add("Lois Lane", "Name")
c.Add("Reporter", "JobTitle")
c.Add(85000, "Salary")
c.Add(lois, "Picture") ' lois is a Picture added to the project
TextField1.Text = c.Item("ID")
TextField2.Text = c.Item(2) ' returns "Lois Lane"
TextField3.Text = c.Item("JobTitle")
TextField4.Text = c.Item("Salary")
Canvas1.Backdrop = c.Item("Picture")
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

If you want to use the Item or Remove methods to refer to an item, use parentheses around the parameter passed to the method. This is because the compiler doesn't know which data type you are passing. For example, use

``` xojo
c.Remove("Name")
```

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

rather than

``` xojo
c.Remove "Name"
```

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | All                   |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `Dictionary</api/language/dictionary>`, `Variant</api/data_types/variant>` classes; `VarType</api/language/vartype>` function; `Nil</api/language/nil>` datatype

</div>