A Dictionary is a special type of array. The important points about a Dictionary are:
- Each item in the Dictionary is referenced by a string index
- It is dynamic (doesn’t have a fixed size)
- Dictionaries can contain normal datatypes (such as int, string, double, bool) or other Classes
- Dictionaries don’t have a history, so you can’t refer to a Dictionary meaning one bar ago. This is an important difference from arrays
A Dictionary is an array-like collection object for storing string-indexed values of non-specific type.
|sKey (Index)||oValue (normal datatypes: bool, string, int, double, etc.), or Object|
|“shirley”||“stop calling me shirley”|
It may help to think of a Dictionary as an unsorted list.
Important programming notes:
- See the Initialization section, below
- See the Usage Examples section, below
- See the Limitations section, below
Dictionary is a variable type, which must be declared, as in:
variables: Dictionary myDict( null ) ;
Properly declared, it can be created in the code body with:
myDict = New Dictionary ;
myDict = Dictionary.Create() ;
Elements are added to the Dictionary using the .Add( sKey, oValue ) method, or the .Items[ sKey ] property, where sKey is a string containing the key name and oValue is the value to be stored. Elements (key and value) are removed from the Dictionary using the .Remove(sKey) method.
The .Contains( sKey ) method is used to determine if a key exists in the Dictionary.
For more information about manipulating a Dictionary object, see the Methods section, below.
For Dictionary usage examples, see the Usage Examples section, below.
Dictionary is a collection class in the ‘elsystem.collections’ namespace.
The fully-qualified class name is ‘elsystem.collections.Dictionary’.
Other members of the elsystem.collections class include:
Important Programming Notes:
- The fully-qualified class name is ‘elsystem.collections.Dictionary’
- If you omit the ‘using elsystem.collections ;’ statement from the top of your code, any reference you make in code to the Dictionary class ( and related event handler method arguments ) must be fully qualified
The following table illustrates this
|‘Using elsystem.collections ;’ statement included||‘Using elsystem.collections ;’ statement omitted|
|myDict = New Dictionary ;||myDict = New elsystem.collections.Dictionary ;|
- Best Practice: ALWAYS include the appropriate ‘using’ statement whenever your code uses EasyLanguage classes
using elsystem.collections; variables: Dictionary myDict( NULL ); once myDict = new Dictionary;
Like all Class declarations, myDict is automatically declared as IntrabarPersist
|myDict.Count||<int>||Gets the number of elements contained in the Dictionary||get: myInteger = myDict.Count() ;|
|myDict.Items||<string>||Gets or sets the value of the element with the specified key||get: myValue = myDict.Items[ “myItem” ] astype …;|
set: myDict.Items[ “myItem” ] = myValue ;
|myDict.Keys||<vector>||Gets the vector collection of sorted keys from the Dictionary||get: myVector = myDict.Keys ;|
|myDict.Values||<vector>||Gets the vector collection of sorted values from the Dictionary||get: myVector = myDict.Values ;|
|.Add(sKey,oValue)||Adds an element with the provided key and value to the Dictionary||myDict.Add( “sKey”, oValue ) ;|
|.Clear||Removes all elements from the Dictionary||myDict.Clear() ;|
|.Contains(sKey)||True if the Dictionary contains an element with the specified key||myDict.Contains( “sKey” ) ;|
|.Create()||Initializes a new instance of the Dictionary class||myDict = Dictionary.Create() ;|
myDict = New Dictionary ;
|.Remove(sKey)||Removes the element with the specified key from the Dictionary||myDict.Remove( “sKey” ) ;|
Note: the .Items set property quietly calls the .Add method if the key does not already exist, which makes .Items more flexible, while using less code ( less manual exception handling ). However, if you wish an exception to be thrown when re-adding an existing key, use the .Add method.
Common Questions & Issues:
- How can I loop through all the elements in a Dictionary if the index keys are all strings ?
To loop through the elements in a Dictionary, use any of the following techniques:
* use integers as indexes ( these will be treated by the Dictionary as a string representation of that integer )
* maintain a list of strings in an integer-indexed collection, such as Vector, Stack, Queue, TokenList
* use the Dictionary.Keys property to return a vector of index sKeys
- If I want to use integer strings as index keys, shouldn’t I use a vector instead ?
Definitely. If you use integers as your index keys, they will be treated as string representations of those integers. String processing is fundamentally more CPU-intensive than numeric processing, so vector processing is faster for this reason alone.
For additional considerations regarding the use of a Dictionary vs. a Vector, see the Limitations section, below
Known limitations as of March 2011 ( Build 8585 )
- The Dictionary class exhibits the following performance issues:
- As the number of elements increases, processing time for Dictionary increases dramatically
- These performance issues make it preferable to use, if at all possible, an integer-index class instead, especially when the number of elements is large
- The following table illustrates the performance difference between Dictionary and Vector. Note that each value below is expressed in terms relative to some minimum. For example, “1x” is the smallest unit of measure required to perform any operation, regardless of the operation being performed. A value of “2x” would therefore mean that the operation took twice as many units as the one that required “1x”.