The Dictionary External Object provides a way to store and retrieve key-value pairs. It allows you to manage a collection of data where each item is identified by a unique key.
You can find the Dictionary External Object in the KB Explorer within the Common module, which in turn is located within the GeneXus module.
The type of the keys used in the dictionary. You can set this type at design time. The default data type is VarChar(255), but it can be any of the following data types: Character, Date, Guid, Boolean, DateTime, Numeric, or GeneXus Domains based on these types.
The type of the values stored in the dictionary. You can set this type at design time. The default data type is VarChar(255), but it can be any data type.
Returns a collection of all values stored in the dictionary. This property is read-only at runtime and contains elements of the type specified by ValueType.
Returns a collection of all keys used in the dictionary. This property is read-only at runtime and contains elements of the type specified by KeyType.
Returns the number of items stored in the dictionary. This property is read-only at runtime.
Adds a new key-value pair to the dictionary or updates the value associated with an existing key.
| Return value |
None |
| Parameters |
Key: KeyType, Value: ValueType |
Adds or updates multiple key-value pairs from another dictionary.
| Return value |
None |
| Parameters |
Dictionary: Dictionary, GeneXus.Common |
Removes the item associated with the specified key from the dictionary.
| Return value |
Boolean |
| Parameters |
Key: KeyType |
Removes multiple items from the dictionary based on a collection of keys.
| Return value |
None |
| Parameters |
Keys: KeyType (Collection) |
Removes all items from the dictionary based on the keys of another dictionary.
| Return value |
None |
| Parameters |
Dictionary: Dictionary, GeneXus.Common |
Removes all items from the dictionary.
| Return value |
None |
| Parameters |
None |
Retrieves the value associated with the specified key.
| Return value |
ValueType |
| Parameters |
Key: KeyType |
Checks if the dictionary contains an item with the specified key.
| Return value |
Boolean |
| Parameters |
Key: KeyType |
Parses a JSON string and populates the dictionary with the key-value pairs from the JSON data.
| Return value |
None |
| Parameters |
Json: VarChar(255) |
Returns a JSON string representation of the dictionary.
| Return value |
VarChar(255) |
| Parameters |
None |
The Dictionary External Object does not have any events.
This sample shows you how to iterate through all dictionary elements using the For in command and the Keys property of the dictionary.
Step 1: Create the Procedure Object
You can define a variable of Dictionary type in any GeneXus object; however, a Procedure object is created for this example.
Step 2: Define the Dictionary type variable
Create a variable named &MyDictionary of Dictionary type. Set the Key Type property to Varchar and the Value Type property to Numeric.
Step 3: Initialize the Dictionary
Add some elements to the dictionary:
&MyDictionary.Set("Name", 1)
&MyDictionary.Set("Age", 30)
&MyDictionary.Set("City", 2)
Step 4: Iterate Through the Dictionary
Use the For in command to iterate over the Keys property of the dictionary:
for &Key in &MyDictionary.Keys
&Value = &MyDictionary.Get(&Key)
msg(&Key.ToString() + ": " + &Value.ToString())
endfor
Where &Key is of VarChar type and &Value is of Numeric type.
Step 5: Execute
Press F5 to run. The result is as follows:
Name: 1
Age: 30
City: 2
- Converting a Dictionary to or from XML, JSON, or String is only possible if the underlying types have the corresponding functions implemented. If these functions are not available, runtime exceptions will occur. For example, the File data type does not have a ToJson() method. Therefore, if you have a Dictionary with values of File type, you cannot serialize it to JSON.
- You cannot define variables that are collections of dictionaries.
- The Properties Data Type is a special case of a Dictionary where both KeyType and ValueType are of VarChar type. Unlike the Properties Data Type, a member of a Structured Data Type (SDT) can be a Dictionary. This means you can create an SDT that has a field that stores a Dictionary.
Example:
Suppose you're creating an SDT to represent a customer with the following structure:
Customer
Name: Varchar(40)
Address: Address, GeneXus
Preferences: Dictionary<Varchar, Varchar> // This is a Dictionary member
In this example, the Preferences member of the Customer SDT is a Dictionary. This allows you to store key-value pairs representing the customer's preferences, as shown below:
- Key: "FavoriteColor" Value: "Blue"
- Key: "NewsletterSubscription" Value: "Yes"
So, while you can't directly use the Properties data type within an SDT, you can use a Dictionary, which gives you more flexibility in storing data within your custom data structures.
Generators: .NET, .NET Framework, Java, Android, Apple
This External Object is available as of GeneXus 18 Upgrade 10.
Fundamentals of data structures: Dictionaries
External Object Types Node