From RAD Studio API Documentation
Jump to: navigation, search



TDictionary<K,V> = class(TEnumerable<TPair<K,V>>)


template<typename K, typename V> class PASCALIMPLEMENTATION TDictionary__2 : public TEnumerable__1<TPair__2<K,V> >


Type Visibility Source Unit Parent
class public
System.Generics.Collections System.Generics.Collections


Collection of key-value pairs.

TDictionary represents a generic collection of key-value pairs.

This class provides a mapping from a collection of keys to a collection of values. When you create a TDictionary object, you can specify such parameters as initial capacity, equality operation, and initial content.

You can add a key that is associated with a corresponding value with the Add or AddOrSetValue methods. You can remove entries with Remove or Clear (removes all key-value pairs). Adding or removing a key-value pair and looking up a key are efficient, close to O(1), because keys are hashed. A key must not be nil (though a value may be nil) and there must be an equality comparison operation for keys.

You can test presence of keys and values with the TryGetValue, ContainsKey, and ContainsValue methods.

The Items property lists all dictionary entries. You can also set and get values by indexing the Items property. Setting the value this way overwrites any existing value.

The class TObjectDictionary inherits from TDictionary and provides an automatic mechanism for freeing objects removed from dictionary entries.

Access methods

This section summarizes methods for reading and writing TDictionary or TObjectDictionary, including the effect of duplicate keys when writing, or key not found when reading.


Method Index type   Value type   If duplicate key
Add TKey TValue Exception
AddOrSetValue TKey TValue Overwrite
Items TKey TValue Overwrite
TryAdd TKey TValue false


Method Index/input type   Result type If key not found Notes
ContainsKey TKey Boolean false True = found
ContainsValue TValue Boolean n/a True = found
ExtractPair TKey TPair Default pair Returns TPair, removes item from dictionary
Items TKey TValue Exception Use TryGetValue to avoid exception
operator [] TKey TValue Exception C++ only
Keys n/a TKeyCollection n/a
ToArray n/a TArray<TPair<TKey,TValue>> n/a
TryGetValue TKey TValue, Boolean default, false Returns TValue
Values n/a TValueCollection n/a


Below you can find some examples, where the code uses iteration through the contents of the dictionary.


uses System.Generics.Collections;
procedure TForm1.Button1Click(Sender: TObject);
  MyDict: TDictionary<string, TForm>;
  MyDict:= TDictionary<string, TForm>.Create;
    MyDict.Add('Form1', Self);
    for var Enum in MyDict do
Attention: When using TDictionary you must use System.Generics.Collections namespace.


#include <memory>
#include <system.Generics.Collections.hpp>
void __fastcall TForm2::Button1Click(TObject *Sender)
  std::unique_ptr<TDictionary__2<String, String>>
  strdict(new TDictionary__2<String, String>());
  strdict->Add("Form1", "A Value");
  for(const TPair__2<String,String> &pair: strdict.get()) {
Tip: Since C++ can only generates code for C++ templates, the code should use STL collections (std::map), not Delphi Generics collections (TDictionary).
Note: Since C++ is not able to instantiate Delphi Generics, C++ code must only use Delphi Generics with types for which Generic has been instantiated in Delphi code.

See Also

Code Examples