System.Generics.Collections.TDictionary

• Up to Parent: System.Generics.Collections
• Methods
• Properties
• Events
• Types

Delphi

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

C++

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

Properties

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

Description

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.

Write

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

Read

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

Iteration

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

Delphi

uses System.Generics.Collections;
procedure TForm1.Button1Click(Sender: TObject);
var
  MyDict: TDictionary<string, TForm>;
begin
  MyDict:= TDictionary<string, TForm>.Create;
  try
    MyDict.Add('Form1', Self);
    for var Enum in MyDict do
      ShowMessage(Enum.Key);
  finally
    MyDict.Free;
  end;
end;

Attention: When using TDictionary you must use System.Generics.Collections namespace.

C++

#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()) {
    ShowMessage(pair.Value);
  }
}

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

• Data.DBXCommon.TKey
• System.Rtti.TValue
• System.Generics.Collections.TDictionary.TKeyCollection
• System.Generics.Collections.TDictionary.TValueCollection
• System.Generics.Collections.TObjectDictionary

• System.Generics.Collections.TDictionary.Count
• System.Generics.Collections.TDictionary.Items
• System.Generics.Collections.TDictionary.Add
• System.Generics.Collections.TDictionary.AddOrSetValue
• System.Generics.Collections.TDictionary.Clear
• System.Generics.Collections.TDictionary.ContainsKey
• System.Generics.Collections.TDictionary.ContainsValue
• System.Generics.Collections.TDictionary.Remove
• System.Generics.Collections.TDictionary.TryGetValue
• System.Generics.Collections.TDictionary.TryAdd

Code Examples

• Generics Collections TDictionary (Delphi)
• Generics Collections TDictionary (C++)