Difference between revisions of "Dictionary"

From Xojo Documentation

(See Also)
 
(16 intermediate revisions by 2 users not shown)
Line 9: Line 9:
 
<dynamicTable id="Properties" class="propertyTable" title="Properties" columns="3">
 
<dynamicTable id="Properties" class="propertyTable" title="Properties" columns="3">
 
{{Property | name=BinCount | type=Integer | platform=all | description=( Integer)&nbsp;&nbsp;The number of bins the hash table uses }}
 
{{Property | name=BinCount | type=Integer | platform=all | description=( Integer)&nbsp;&nbsp;The number of bins the hash table uses }}
{{Property | name=Count | type=Integer | readonly=yes | platform=all | description=( Integer)&nbsp;&nbsp;Number of key-value pairs in the Dictionary }}
+
{{Property | name=KeyCount | type=Integer | readonly=yes | platform=all | description=( Integer)&nbsp;&nbsp;Number of key-value pairs in the Dictionary. }}
 
</dynamicTable>
 
</dynamicTable>
  
 
<dynamicTable id="Methods" class="methodTable" title="Methods" columns="3">
 
<dynamicTable id="Methods" class="methodTable" title="Methods" columns="3">
{{Method | name=Clear | description=Clear()&#10;Clears all the key-value pairs in the Dictionary. }}
 
 
{{Method | name=HasKey | params=Key as [[Variant]] | returntype=[[Boolean]] | description=HasKey(Key as Variant) as Boolean&#10;Returns True if Key is in the Dictionary and False if it is not. }}
 
{{Method | name=HasKey | params=Key as [[Variant]] | returntype=[[Boolean]] | description=HasKey(Key as Variant) as Boolean&#10;Returns True if Key is in the Dictionary and False if it is not. }}
 
{{Method | name=Key | params=Index as [[Integer]] | returntype=[[Variant]] | description=Key(Index as Integer) as Variant&#10;Returns the value of key for the Indexth sequential item in the Dictionary }}
 
{{Method | name=Key | params=Index as [[Integer]] | returntype=[[Variant]] | description=Key(Index as Integer) as Variant&#10;Returns the value of key for the Indexth sequential item in the Dictionary }}
Line 19: Line 18:
 
{{Method | name=Lookup | params=Key as [[Variant]],defaultValue as [[Variant]] | returntype=[[Variant]] | newinversion=2005r1 | description=Lookup(Key as Variant,defaultValue as Variant) as Variant&#10;Looks up the passed value of Key. Returns a Variant.  }}
 
{{Method | name=Lookup | params=Key as [[Variant]],defaultValue as [[Variant]] | returntype=[[Variant]] | newinversion=2005r1 | description=Lookup(Key as Variant,defaultValue as Variant) as Variant&#10;Looks up the passed value of Key. Returns a Variant.  }}
 
{{Method | name=Remove | params=Key as [[Variant]] | description=Remove(Key as Variant)&#10;Removes the key value-key pair from the Dictionary.  }}
 
{{Method | name=Remove | params=Key as [[Variant]] | description=Remove(Key as Variant)&#10;Removes the key value-key pair from the Dictionary.  }}
 +
{{Method | name=RemoveAll | description=RemoveAll()&#10;Removes all entries from the Dictionary.  }}
 
{{Method | name=Value | returntype=Variant | platform=all| parameters=Key as [[Variant]] | description=( Variant)&nbsp;&nbsp;Assigns a value to the Key item in the Dictionary or retrieves the value associated with the Key item }}
 
{{Method | name=Value | returntype=Variant | platform=all| parameters=Key as [[Variant]] | description=( Variant)&nbsp;&nbsp;Assigns a value to the Key item in the Dictionary or retrieves the value associated with the Key item }}
 
{{Method | name=Values | returntype=[[Variant|Variant()]] | newinversion=2005r2 | description=Values() as Variant()&#10;Returns all the values in the Dictionary as an array of Variants. }}
 
{{Method | name=Values | returntype=[[Variant|Variant()]] | newinversion=2005r2 | description=Values() as Variant()&#10;Returns all the values in the Dictionary as an array of Variants. }}
Line 24: Line 24:
  
 
<dynamicTable id="Constructors" class="methodTable" title="Constructors" columns="1">
 
<dynamicTable id="Constructors" class="methodTable" title="Constructors" columns="1">
 +
{{Ctor |  params= keyComparison As KeyComparisonDelegate | description=Dictionary(keyComparison As KeyComparisonDelegate )&#10; Creates a Dictionary that gives you control over how key uniqueness is determined. }}
 
{{Ctor |  params=ParamArray entries as Pair | description=Dictionary(ParamArray entries as Pair )&#10; Creates a list of key-value pairs from the passed entries. }}
 
{{Ctor |  params=ParamArray entries as Pair | description=Dictionary(ParamArray entries as Pair )&#10; Creates a list of key-value pairs from the passed entries. }}
 +
 
</dynamicTable>
 
</dynamicTable>
 +
Constructor(keyComparison As KeyComparisonDelegate)
  
 +
<dynamicTable id="Delgates" class="methodTable" title="Delegates" columns="1">
 +
{{Method |  name=KeyComparisionDelegate | returntype=[[Integer]] | description=KeyComparisonDelegate(leftKey As Variant, rightKey As Variant)&#10; Provides the means to delegate the comparison of keys to one of your own methods. }}
 +
 +
</dynamicTable>
 
== Notes ==
 
== Notes ==
 
For iOS projects refer to the Dictionary-related classes in Xojo.Core:
 
For iOS projects refer to the Dictionary-related classes in Xojo.Core:
Line 44: Line 51:
  
 
<rbcode>
 
<rbcode>
Dim d As New Dictionary
+
Var d As New Dictionary
 
d.Value("a") = "lower"
 
d.Value("a") = "lower"
 
d.Value("A") = "UPPER"
 
d.Value("A") = "UPPER"
  
MsgBox(d.Value("a")) // Displays "UPPER"
+
MessageBox(d.Value("a")) // Displays "UPPER"
MsgBox(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:
 
// The actual key value is "a" as you can test using the Key method:
MsgBox(d.Key(0)) // Displays "a"
+
MessageBox(d.Key(0)) // Displays "a"
 
</rbcode>
 
</rbcode>
  
Line 59: Line 66:
  
 
<rbcode>
 
<rbcode>
Dim v1 As Int32 = -1
+
Var v1 As Int32 = -1
Dim v2 As Int64 = -1
+
Var v2 As Int64 = -1
  
Dim d As New Dictionary
+
Var d As New Dictionary
 
d.Value(v1) = "something"
 
d.Value(v1) = "something"
 
If d.HasKey(v2)  Then
 
If d.HasKey(v2)  Then
Line 73: Line 80:
 
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.
 
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.
 
<rbcode>
 
<rbcode>
Dim d As New Dictionary
+
Var d As New Dictionary
 
d.Value(RGB(255, 0, 0)) = "This is pure red."
 
d.Value(RGB(255, 0, 0)) = "This is pure red."
 
d.Value(RGB(0, 255, 255)) = "This is pure cyan."
 
d.Value(RGB(0, 255, 255)) = "This is pure cyan."
MsgBox(d.Value(d.Key(1))) // displays "This is pure cyan."
+
MessageBox(d.Value(d.Key(1))) // displays "This is pure cyan."
 
Exception err As RuntimeException
 
Exception err As RuntimeException
 
   If err IsA KeyNotFoundException Then
 
   If err IsA KeyNotFoundException Then
     MsgBox("Key not in the dictionary")
+
     MessageBox("Key not in the dictionary")
 
   End If
 
   End If
 
   If err IsA OutOfBoundsException Then
 
   If err IsA OutOfBoundsException Then
     MsgBox("The index of the key is out of bounds!")
+
     MessageBox("The index of the key is out of bounds!")
 
   End If
 
   End If
 
</rbcode>
 
</rbcode>
Line 88: Line 95:
 
If the index passed to the Key method in the line:
 
If the index passed to the Key method in the line:
 
<rbcode>
 
<rbcode>
MsgBox(d.Value(d.Key(1)))
+
MessageBox(d.Value(d.Key(1)))
 
</rbcode>
 
</rbcode>
  
 
is not an element in the dictionary, an [[OutOfBoundsException]] occurs and the [[Exception|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
 
is not an element in the dictionary, an [[OutOfBoundsException]] occurs and the [[Exception|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
 
<rbcode>
 
<rbcode>
MsgBox(d.Value(RGB(0, 255, 255)))
+
MessageBox(d.Value(RGB(0, 255, 255)))
 
</rbcode>
 
</rbcode>
  
 
In this case, if you pass a key that is not in the dictionary, a [[KeyNotFoundException]] will occur and the [[Exception|Exception block]] will also trap it and display the appropriate error message.
 
In this case, if you pass a key that is not in the dictionary, a [[KeyNotFoundException]] will occur and the [[Exception|Exception block]] will also trap it and display the appropriate error message.
  
This code returns the value of Count for the above code:
+
This code returns the value of [[Dictionary.KeyCount|KeyCount]] for the above code:
 
<rbcode>
 
<rbcode>
Dim d As New Dictionary
+
Var d As New Dictionary
 
d.Value(RGB(255, 0, 0)) = "This is pure red."
 
d.Value(RGB(255, 0, 0)) = "This is pure red."
 
d.Value(RGB(0, 255, 255)) = "This is pure cyan."
 
d.Value(RGB(0, 255, 255)) = "This is pure cyan."
MsgBox(Str(d.Count)) // displays "2"
+
MessageBox(Str(d.KeyCount)) // displays "2"
 
</rbcode>
 
</rbcode>
  
Line 109: Line 116:
 
<rbcode>
 
<rbcode>
 
If d.HasKey(RGB(0, 255, 255)) Then
 
If d.HasKey(RGB(0, 255, 255)) Then
   MsgBox(d.Value(RGB(0, 255, 255)))
+
   MessageBox(d.Value(RGB(0, 255, 255)))
 
Else
 
Else
   MsgBox("Key not in the dictionary!")
+
   MessageBox("Key not in the dictionary!")
 
End If
 
End If
 
</rbcode>
 
</rbcode>

Latest revision as of 22:50, 30 August 2019

Class (inherits from Object)

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
BinCount KeyCount fa-lock-32.png
Methods
HasKey Lookup Value
Key Remove Values
Keys RemoveAll
Constructors

Constructor(keyComparison As KeyComparisonDelegate)


Constructor(ParamArray entries as Pair)


Constructor(keyComparison As KeyComparisonDelegate)

Delegates
KeyComparisionDelegate

Notes

For iOS projects refer to the Dictionary-related classes in Xojo.Core:

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.

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:

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,

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

Xojo.Core.Dictionary does not have this limitation.

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.

Var d As New Dictionary
d.Value(RGB(255, 0, 0)) = "This is pure red."
d.Value(RGB(0, 255, 255)) = "This is pure cyan."
MessageBox(d.Value(d.Key(1))) // displays "This is pure cyan."
Exception err As RuntimeException
If err IsA KeyNotFoundException Then
MessageBox("Key not in the dictionary")
End If
If err IsA OutOfBoundsException Then
MessageBox("The index of the key is out of bounds!")
End If

If the index passed to the Key method in the line:

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

MessageBox(d.Value(RGB(0, 255, 255)))

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:

Var d As New Dictionary
d.Value(RGB(255, 0, 0)) = "This is pure red."
d.Value(RGB(0, 255, 255)) = "This is pure cyan."
MessageBox(Str(d.KeyCount)) // displays "2"

Instead of the Exception block, you could first use the HasKey method before trying to access the value:

If d.HasKey(RGB(0, 255, 255)) Then
MessageBox(d.Value(RGB(0, 255, 255)))
Else
MessageBox("Key not in the dictionary!")
End If

See Also

KeyNotFoundException error; Collection, Pair, Variant, Xojo.Core.Dictionary classes