Class

Xojo.Core.Dictionary

Warning

This item was deprecated in version 2020r2. Please use Dictionary as a replacement.

Description

The Dictionary class is an unordered, mutable, key-value store that is loosely typed. It implements the Iterable interface, allowing efficient and easy iteration over all key-value pairs.

Properties

Name	Type	Read-Only	Shared
Count	Integer	✓

Methods

Name	Parameters	Returns
Clone		Dictionary
GetIterator		Iterator
HasKey	key As Variant	Boolean
Lookup	key As Variant, defaultValue As Variant	Variant
Remove	key As Variant
RemoveAll

Events

Name	Parameters	Returns
CompareKeys	lhs As Variant, rhs As Variant

Property descriptions

Xojo.Core.Dictionary.Count

Count As Integer

The number of entries in the Dictionary.

This property is read-only.

Method descriptions

Xojo.Core.Dictionary.Clone

Clone As Dictionary

Performs a shallow clone of the Dictionary, resulting in a new Dictionary that can be manipulated independently of the first. A shallow clone means that if a Dictionary Value or Key refers to a class instance, its contents are not also cloned.

Clone a dictionary and then change the original:

Var d1 As New Xojo.Core.Dictionary
d1.Value("Test") = "Hello, World!"

Var d2 As Xojo.Core.Dictionary
d2 = d1.Clone

d1.Value("Test") = "Changed!"

' d2.Value("Test") is still "Hello, World!"

Xojo.Core.Dictionary.GetIterator

GetIterator As Iterator

Creates a new iterator for the Dictionary which will yield DictionaryEntry objects for its values that you can iterate through using For Each...Next. Part of the xojo.core.iterable interface.

You will not access this method directly. Instead use the ability to iterate over the Dictionary using a For Each...Next loop.

Iterate over the Dictionary entries using For Each..Next:

Var d As New Xojo.Core.Dictionary
d.Value("One") = "Testing"
d.Value("Two") = "Iterator"

For Each entry As Xojo.Core.DictionaryEntry In d
  TextArea1.Text = TextArea1.Text + " " + entry.Key + " " + entry.Value
Next

Xojo.Core.Dictionary.HasKey

HasKey(key As Variant) As Boolean

Determines whether or not the Dictionary contains a value for the specified key.

Check if "Test" is used as a key value:

If Not d1.HasKey("Test") Then
  d1.Value("Test") = "Initial value"
End If

Xojo.Core.Dictionary.Lookup

Lookup(key As Variant, defaultValue As Variant) As Variant

Returns the value associated with the specified key. If there is no such entry, the defaultValue parameter is returned and no exception is raised.

If the User ID is not found in the Dictionary, return "UnknownUser":

Var userID As Integer = 123
Var user As Text
user = d1.Lookup(userID, "UnknownUser")

Xojo.Core.Dictionary.Remove

Remove(key As Variant)

Removes a single entry with the specified key from the Dictionary, invalidating all iterators that were created from the Dictionary. If there is no entry in the Dictionary for the key, a KeyNotFoundException is raised.

Remove the entry for the value "Test" in the Dictionary:

d1.Remove("Test")

Xojo.Core.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:

d1.RemoveAll

Event descriptions

Xojo.Core.Dictionary.CompareKeys

CompareKeys(lhs As Variant, rhs As Variant)

Implement this event handler if you would like the Dictionary to support case-sensitive keys.

This code does a case-sensitive comparison of the text value of the specified keys:

Var lhsText As Text = lhs
Var rhsText As Text = rhs
Return lhsText.Compare(rhsText, Text.CompareCaseSensitive)

Notes

As shown on GetIterator, if you change the Dictionary while iterating over it using For Each...Next, an exception will be raised. If you find you need to iterate and change the data, you can add a method to get all the keys into an array and then iterate through the array to access the Dictionary values. A method could be something like this:

Function EagerlyEvaluateIterable(obj As Xojo.Core.Iterable) As Auto()
  Var results() As Auto
  For Each item As Auto In obj
    results.Append(item)
  Next
  Return results
End Function

Now you can call the method to get an array where you can then modify the contents:

For Each entry As Xojo.Core.DictionaryEntry In EagerlyEvaluateIterable(d)
  ' Stuff that can mutate the dictionary
Next

Sample code

Add items to a Dictionary and loop through them:

Var months As New Xojo.Core.Dictionary
months.Value("January") = 31
months.Value("February") = 28
months.Value("March") = 31
months.Value("April") = 30
months.Value("May") = 31
months.Value("June") = 30
months.Value("July") = 31
months.Value("August") = 31
months.Value("September") = 30
months.Value("October") = 31
months.Value("November") = 30
months.Value("December") = 31

For Each days As Xojo.Core.DictionaryEntry In months
  Var numDays As Integer = days.Value
Next

Compatibility

All project types on all supported operating systems.