System.Generics.Collections.TDictionary

From RAD Studio API Documentation
Jump to: navigation, search

System.Generics.Collections.TEnumerableSystem.TObjectTDictionary

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

Code Examples