Class # Dictionary --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description An object that contains a list of *key-value* pairs. Both keys and values are `Variants`. ASCII `String` keys are case-insensitive, but non-ASCII `String` keys can be case-sensitive. `String` keys are encoding-sensitive. ## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |---------------------------------|------------------------------------|-----------|--------| | `BinCount` | `Integer` | | | | `KeyCount` | `Integer` | ✓ | | ## Methods

table-centered_column_4

| Name | Parameters | Returns | Shared | |----------------------------------------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------|--------| | `Clone` | | Dictionary | | | `Constructor` | keyComparison As `Dictionary.KeyComparisonDelegate` | | | | `Constructor` | `ParamArray` entries As `Pair` | | | | `HasKey` | key As `Variant` | `Boolean` | | | `Iterator` | | `Iterator` | | | `Key` | index As `Integer` | `Variant` | | | `Keys` | | `Variant()` | | | `Lookup` | key As `Variant`, defaultValue As `Variant` | `Variant` | | | `Remove` | key As `Variant` | | | | `RemoveAll` | | | | | `Value` | key As `Variant` | `Variant` | | | | key As `Variant`, `Assigns` value As `Variant` | | | | `Values` | | `Variant()` | | ## Delegate Methods

table-centered_column_4

| Name | Parameters | Returns | |-----------------------------------------------------------|-----------------------------------------------------------------------------------------------|------------------------------------| | `KeyComparisonDelegate` | leftKey As `Variant`, rightKey As `Variant` | `Integer` | ## Property descriptions

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

forsearch

Dictionary.BinCount **BinCount** As `Integer` > The number of bins the hash table uses. This is a measure of the hash table size, independent of the number of items the Dictionary contains. > > Normally, you do not need to be concerned with bins and the hash table. BinCount would be of use to you only if you have very large dictionaries consisting of thousands of entries and you want to try to optimize performance. > > If you set BinCount to a positive value, the Dictionary will use that number of bins regardless of the number of items in the Dictionary. > > If you set BinCount to a value equal to or less than zero, the Dictionary will pick whatever value it thinks is appropriate for the number of items in the Dictionary. It will dynamically change the number of bins as items are added or removed from the Dictionary (or until you assign a positive value to BinCount). > > The latter is the default behavior. > > This example sets the number of bins: > > ``` xojo > Var d As New Dictionary > d.BinCount = 100 > ```

forsearch

Dictionary.KeyCount **KeyCount** As `Integer` > The number of *key-value* pairs in the Dictionary. > > This property is read-only. > > Returns the actual Count, not the Ubound of an array. > > The following code displays the number of *key-value* pairs: > > ``` xojo > Var d As New Dictionary > ' display the entries for the dictionary > MessageBox(d.KeyCount.ToString) > ``` ## Method descriptions

forsearch

Dictionary.Clone **Clone** As Dictionary > Returns a copy of the contents of the Dictionary allowing it to be manipulated independently of the original. Because any Dictionary items that are objects are really just references to the object, while the references themselves are duplicated, the objects they reference are not. Changing an object in one will change it in the other. > > In the example code below, the Dictionary (reservation1) is cloned into reservation2. The item "Name" in reservation2 is changed to `Samwise Gamgee` which leaves the "Name" value unchanged in reservation1. However, because a `DateTime` is an object, the "Date" item in reservation2 is still the same as it is in reservation1 because it's a reference a `DateTime` object and not a copy of it. In the last line of the example, a new `DateTime` object is created using `DateTime.AddInterval` to create a `DateTime` that is 1 year later. At that point, the two "Date" items point to two different `DateTime` objects. > > ``` xojo > Var today As DateTime = DateTime.Now > Var reservation1 As New Dictionary > reservation1.Value("Name") = "Frodo Baggins" > reservation1.Value("Date") = today > > Var reservation2 As Dictionary > reservation2 = reservation1.Clone > reservation2.Value("Name") = "Samwise Gamgee" > > reservation2.Value("Date") = reservation2.Value("Date").DateTimeValue.AddInterval(1) > ``` > > If you prefer to copy objects referenced in a Dictionary, you will have to handle that yourself. > > For example, if the last line in the example above was replaced by the following line, the "Date" value would be a copy of the original rather than a reference to it. > > ``` xojo > reservation2.Value("Date") = New DateTime(reservation1.Value("Date").DateTimeValue) > ```

forsearch

Dictionary.Constructor **Constructor**(keyComparison As `Dictionary.KeyComparisonDelegate`) >

> >

> > Note > >

> > `Constructors` are special methods called when you create an object with the `New` keyword and pass in the parameters above. > >

> > Creates a Dictionary that gives you control over how key uniqueness is determined. For example, you'd use this if you wanted to create case-sensitive keys. > >

> >

> > Important > >

> > This constructor is not currently supported for Android. > >

forsearch

Dictionary.Constructor **Constructor**(`ParamArray` entries As `Pair`) > The parameter is the list of `Pairs` that will make up the Dictionary. > > This example passes the specs for a rectangle as as a list of `Pairs`. The *key*s are Top, Left, Width, and Height and the values are the values that belong to each *key* value. > > ``` xojo > Var d As New Dictionary("left" : 0, "top" : 10, "width" : 300, "height" : 300) > ```

forsearch

Dictionary.HasKey **HasKey**(key As `Variant`) As `Boolean` > Returns `True` if *key* is in the Dictionary and `False` if it is not. > > Returns a `Boolean`. The HasKey function is encoding-sensitive. The Dictionary works off hash functions and the hash of a UTF-16 string is vastly different from the hash of a UTF-8 string. > > This example checks to see if the key corresponding to the passed color is in the Dictionary. > > ``` xojo > If d.HasKey(Color.Red) Then > MessageBox(d.Value(Color.Red)) > Else > MessageBox("The Red Key is not in the dictionary.") > End If > ```

forsearch

Dictionary.Iterator **Iterator** As `Iterator` > Allows iterating through all of the items in the Dictionary with `For...Each`.

forsearch

Dictionary.Key **Key**(index As `Integer`) As `Variant` > Returns the value of *key* for the item in the Dictionary at the index passed. > > Keys are not case-sensitive, but they are encoding-sensitive. If there is no item in the Dictionary at the index passed, a call generates an `OutOfBoundsException` error. > > ``` xojo > Var d As New Dictionary > d.Value(Color.Red) = "This is pure red." > d.Value(Color.Blue) = "This is pure blue." > MessageBox(d.Value(d.Key(1))( ' retrieves "This is pure blue." > ```

forsearch

Dictionary.Keys **Keys** As `Variant()` > Returns an array of keys allowing you to iterate through all the key/value pairs in the Dictionary. > > The order is stable and matches the order returned by the `Values` method at least until the Dictionary is modified. Use this method with `For Each` or `For...Next` to loop through all the keys. Keys are not case-sensitive, but they are encoding-sensitive. > > Suppose you have a Dictionary wordCounts whose keys are words, and whose values are the number of occurrences of the key in some text. You can produce a list of words sorted by count as follows. > > ``` xojo > Var word() As String > Var count() As Integer > > For Each key As Variant In wordCounts.Keys > word.Add(key) > count.Add(wordCounts.Value(key)) > Next > > count.SortWith(word) > ```

forsearch

Dictionary.Lookup **Lookup**(key As `Variant`, defaultValue As `Variant`) As `Variant` > Looks up the passed value of *Key*. Returns a `Variant`. > > If *Key* is found, it returns the corresponding value. If *key* is not found, it returns the passed *defaultValue*. > > This example looks up the passed color in the Dictionary. > > ``` xojo > Var d As New Dictionary > d.Value(Color.Red) = "This is pure red." > d.Value(Color.Blue) = "This is pure blue." > > Var a As Variant > a = d.Lookup(Color.Red, "Default color") > ```

forsearch

Dictionary.Remove **Remove**(key As `Variant`) > Removes the *key* _th *value-key* pair from the Dictionary. > > If *key* is not in the Dictionary, it raises a `KeyNotFoundException` error. > > The following code removes the passed entry from the \`Dictionary\`: > > ``` xojo > Try > d.Remove(Color.Red) > Catch err As KeyNotFoundException > MessageBox("You tried to access a nonexistent item!") > End Try > ```

forsearch

Dictionary.RemoveAll **RemoveAll** > Removes all entries from the Dictionary. This invalidates all iterators that were created from the Dictionary. > > Remove all entries from a \`Dictionary\`: > > ``` xojo > d1.RemoveAll > ```

forsearch

Dictionary.Value **Value** value As `Variant` > Retrieves a value to the *key* item in the Dictionary. **Value**(value As `Variant`, `Assigns` value As `Variant`) > Assigns a value to the *key* item in the Dictionary. > > The Value function is encoding-sensitive. The Dictionary works of hash functions and the hash of a UTF-16 string is vastly different than the hash of a UTF-8 string. > > If you attempt to read a value for a key that is not in the Dictionary, a `KeyNotFoundException` error is raised. To avoid the exception, use the `Lookup` method to provide a default value if the key is not found or use the `HasKey` method to check if the key exists. > > The Dictionary example in the Examples folder allows you to enter and display Dictionary entries. It uses only strings for the key and value, but you can actually use any type that can be stored as a `Variant`. The fields *KeyField* and *ValueField* contain the new *key:value* pair. > > To use the example, enter a key and value pair and then press the “Set Value for Key” button. Its code is: > > ``` xojo > ' add a value the same way you would set the value > ' the key is a variant, which means it can be > ' any data type. > // > ' the value is also a variant > ' however, this example only uses strings for keys and values > > myDictionary.Value(KeyField.Text) = ValueField.Text > > UpdateListbox > ``` > > *UpdateListbox* is a window method and it repopulates the ListBox. > > ``` xojo > ListBox1.RemoveAllRows > > For Each entry As DictionaryEntry In MyDictionary > ListBox1.AddRow(entry.Key) > Next > ```

forsearch

Dictionary.Values **Values** As `Variant()` > Returns all the values in the Dictionary as an array of `Variants`. > > The order is stable and matches the order returned by Keys at least until the Dictionary is modified. Use this method with `For Each` to loop through all the values. > > The following code retrieves the entries in the Dictionary and populates an array of `Variants`: > > ``` xojo > Var d As New Dictionary > d.Value(1) = "123" > d.Value(2) = "234" > d.Value(3) = "123" > > Var v() As Variant > v = d.Values ' after this line v will be an array of variants that are all the values in the dictionary > ``` ## Delegate descriptions

forsearch

Dictionary.KeyComparisonDelegate **KeyComparisonDelegate**(leftKey As `Variant`, rightKey As `Variant`) As `Integer` > Implement this delegate if you would like the Dictionary to support case-sensitive keys. Return integer with value like String.Compare function. > >

> >

> > Important > >

> > This delegate is not supported for Android. > >

## Interfaces This class implements the `Iterable` class interface. ## Notes The Dictionary class provides the functionality of the `Collection` class and offers several advantages: With the `Collection` class, the time taken to locate an item is a function of the number of items in the `Collection` because the search is sequential. A 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 is a `Variant`, but is a `String` in the `Collection` class, giving you greater flexibility. On the other hand, the Collection can store multiple values per key. When you assign a value to a key that is already in the Dictionary, the new value replaces the old one The `Pair` class also stores key-value items. The `Pair` class stores the key-value items in its Left and Right properties and an array of pairs can be set up as a linked list. The `Pair` class has only the two properties that contain the values of the pair. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Iterating through a Dictionary To iterate through the contents of a Dictionary, use the `DictionaryEntry` class. ### String key differences Dictionaries use hashes for their lookup functions. Because of this, string keys need to match exactly; otherwise the Dictionary will not consider them equal. The only exception to this rule is with regard to string case. The characters "a" and "A" are treated as identical in Dictionary keys because of a case-insensitive hashing function. However, non-ASCII characters such as "é" and "É" are not treated as identical in Dictionary keys, even though they are equal in a direct string comparison. While a UTF-16 string can be compared to a UTF-8 function in your code, they will provide different hashes when working with dictionaries. Although the keys are case-insensitive, the case of the key is remembered. And the case of the key is not changed if a subsequent assignment uses a different case for the key. For example: ``` xojo Var d As New Dictionary d.Value("a") = "lower" d.Value("A") = "UPPER" MessageBox(d.Value("a")) ' Displays "UPPER" MessageBox(d.Value("A")) ' Displays "UPPER" ' The actual key value is "a" as you can test using the Key method: MessageBox(d.Key(0)) ' Displays "a" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Integer key differences Due to a particularity of Variant comparison, it is possible that Integer keys of different types may not evaluate as equivalent. For example, ``` xojo Var v1 As Int32 = -1 Var v2 As Int64 = -1 Var d As New Dictionary d.Value(v1) = "something" If d.HasKey(v2) Then ' Won't get here, because the two keys are not considered equivalent End If ``` ### Case-Sensitive keys While Dictionary keys are case-insensitive, you can create case-sensitive keys if you need them: This function provides a case-sensitive comparison: ``` xojo Public Function CaseSensitiveKeyComparisonDelegate(leftKey As Variant, rightKey As Variant) As Integer Return leftKey.StringValue.Compare(rightKey.StringValue, ComparisonOptions.CaseSensitive) End Function ``` You then call the function above when creating a \`Dictionary\`: ``` xojo Var d As New Dictionary(AddressOf CaseSensitiveKeyComparisonDelegate) d.Value("Hello") = 123 d.Value("hello") = 234 Break ' The dictionary has now 2 entries in the dictionary ``` ## Sample code The following code takes advantage of the fact that the key is a `Variant`, and not necessarily a number. In this example, the keys are colors and the values are descriptions. ``` xojo Try Var d As New Dictionary d.Value(Color.Red) = "This is pure red." d.Value(Color.Blue) = "This is pure blue." MessageBox(d.Value(d.Key(1))) ' displays "This is pure blue." Catch err As KeyNotFoundException MessageBox("Key not in the dictionary") Catch err As OutOfBoundsException MessageBox("The index of the key is out of bounds!") End Try ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If the index passed to the Key method in the line: ``` xojo MessageBox(d.Value(d.Key(1))) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- is not an element in the Dictionary, an `OutOfBoundsException` occurs and the `Exception block` at the end of the method will trap it. You could also retrieve this value in the Dictionary by passing the Value method the key rather than the key's index ``` xojo MessageBox(d.Value(Color.Blue)) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In this case, if you pass a key that is not in the Dictionary, a `KeyNotFoundException` will occur and the `Exception block` will also trap it and display the appropriate error message. This code returns the value of `KeyCount` for the above code: ``` xojo Var d As New Dictionary d.Value(Color.Red) = "This is pure red." d.Value(Color.Blue) = "This is pure blue." MessageBox(d.KeyCount.ToString) ' displays "2" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Instead of the `Exception` block, you could first use the HasKey method before trying to access the value: ``` xojo If d.HasKey(Color.Red) Then MessageBox(d.Value(Color.Red)) Else MessageBox("Key not in the dictionary!") End If ``` ## Compatibility | | | |-----------------------|-----| | **Project Types** | All | | **Operating Systems** | All |

`Object` parent class; `DictionaryEntry`, `KeyNotFoundException` error; `Collection`, `Pair`, and `Variant` classes