Delphi 2009 泛型字典 TDictionary<TKey,TValue> 完整實戰指南

TDictionary 核心特性

TDictionary<TKey, TValue> 是 Delphi 2009 引入的泛型雜湊表實作，提供 O(1) 平均時間複雜度的鍵值查找、新增、刪除操作。類似 .NET 的 Dictionary<TKey, TValue>，適用於高效率查找場景。

核心操作方法速查表

完整實作範例：互動式字典管理器

表單設計

• TMemo：左側顯示所有鍵值對
• TEdit x2：輸入 Key (Cardinal) 與 Value (String)
• TButton x4：新增、刪除、查詢、清空

核心程式碼

uses Generics.Collections;

var
  Dictionary: TDictionary<Cardinal, string>;

procedure TForm1.FormCreate(Sender: TObject);
begin
  Dictionary := TDictionary<Cardinal, string>.Create;
  Memo1.Clear;
  // 按鈕標題設定略...
  Edit1.NumbersOnly := True; // Key 僅限數字
end;

procedure TForm1.FormDestroy(Sender: TObject);
begin
  Dictionary.Free;
end;

// 新增/更新
procedure TForm1.Button1Click(Sender: TObject);
var
  key: Cardinal;
  value: string;
  k, v: Boolean;
  str: string;
begin
  key := StrToIntDef(Edit1.Text, 0);
  value := Edit2.Text;
  if value = '' then value := 'Null';

  k := Dictionary.ContainsKey(key);
  v := Dictionary.ContainsValue(value);

  if not k then
  begin
    Dictionary.Add(key, value);
    Memo1.Lines.Add(Format('%d=%s', [key, value]));
  end
  else if k and not v then
  begin
    str := Format('Key 已存在: %d=%s，是否更新？', [key, Dictionary[key]]);
    if MessageBox(0, PChar(str), '確認', MB_OKCANCEL or MB_ICONQUESTION) = IDOK then
    begin
      Dictionary.AddOrSetValue(key, value);
      Memo1.Lines.Values[IntToStr(key)] := value; // 同步更新顯示
    end;
  end
  else
    ShowMessage(Format('%d=%s 已存在，不可重複', [key, value]));

  Caption := IntToStr(Dictionary.Count); // 標題列顯示筆數
end;

// 刪除
procedure TForm1.Button2Click(Sender: TObject);
var
  key: Integer;
  i: Integer;
begin
  key := StrToIntDef(Edit1.Text, 0);
  if not Dictionary.ContainsKey(key) then
  begin
    ShowMessageFmt('Key %d 不存在', [key]);
    Exit;
  end;

  Dictionary.Remove(key);
  Caption := IntToStr(Dictionary.Count);

  i := Memo1.Lines.IndexOfName(IntToStr(key));
  if i > -1 then Memo1.Lines.Delete(i);
end;

// 查詢
procedure TForm1.Button3Click(Sender: TObject);
var
  key: Integer;
  value: string;
begin
  key := StrToIntDef(Edit1.Text, 0);
  if Dictionary.TryGetValue(key, value) then
    ShowMessageFmt('Key %d 存在，值為: %s', [key, value])
  else
    ShowMessageFmt('Key %d 不存在', [key]);
end;

// 清空
procedure TForm1.Button4Click(Sender: TObject);
begin
  Dictionary.Clear;
  Caption := IntToStr(Dictionary.Count);
  Memo1.Clear;
end;

進階應用技巧

1. 列舉器遍歷

for kvp in Dictionary do
  ShowMessageFmt('Key: %d, Value: %s', [kvp.Key, kvp.Value]);

2. 鍵值集合存取

var keys: TArray<Cardinal>;
var values: TArray<string>;
keys := Dictionary.Keys.ToArray;
values := Dictionary.Values.ToArray;

3. 自訂比較器 (建構子參數)

// 預設使用 EqualityComparer<TKey>.Default
// 可傳入自訂 IEqualityComparer<TKey> 實作大小寫不敏感等邏輯
Dictionary := TDictionary<string, Integer>.Create(TCaseInsensitiveComparer.Create);

效能與注意事項

• 容量預分配：大量資料時用 TDictionary<K,V>.Create(預估容量) 減少重新雜湊
• 避免頻繁 Clear/Add：重複使用容器優於反覆建立銷毀
• 執行緒安全：TDictionary 非執行緒安全，多執行緒需自行加鎖
• 記憶體管理：Value 為物件時，移除項目前須自行釋放，或改用 TObjectDictionary

總結

TDictionary<TKey, TValue> 以泛型強型別、高效能雜湊演算法、豐富 API 取代舊版 TStringList 或手動實作的查找表，是 Delphi 2009+ 處理鍵值資料的標準利器。