Dictionary 泛型類

.NET Framework 類庫 

Dictionary 泛型類 

注意：此類在 .NET Framework 2.0 版中是新增的。

表示鍵和值的集合。

命名空間:System.Collections.Generic
程序集:mscorlib（在 mscorlib.dll 中）

<script type="text/Javascript"> var ExpCollDivStr = ExpCollDivStr; ExpCollDivStr = ExpCollDivStr + "ctl00_LibFrame_ctl0275baefc,"; var ExpCollImgStr = ExpCollImgStr; ExpCollImgStr = ExpCollImgStr + "ctl00_LibFrame_ctl02img,"; </script> 語法

Visual Basic（聲明）

<SerializableAttribute> _
<ComVisibleAttribute(False)> _
Public Class Dictionary(Of TKey, TValue)
    Implements IDictionary(Of TKey, TValue), ICollection(Of KeyValuePair(Of TKey, TValue)), _
    IEnumerable(Of KeyValuePair(Of TKey, TValue)), IDictionary, ICollection, _
    IEnumerable, ISerializable, IDeserializationCallback

Visual Basic（用法）

Dim instance As Dictionary(Of TKey, TValue)

C#

[SerializableAttribute] 
[ComVisibleAttribute(false)] 
public class Dictionary<TKey,TValue> : IDictionary<TKey,TValue>, ICollection<KeyValuePair<TKey,TValue>>, 
    IEnumerable<KeyValuePair<TKey,TValue>>, IDictionary, ICollection, IEnumerable, 
    ISerializable, IDeserializationCallback

C++

[SerializableAttribute] 
[ComVisibleAttribute(false)] 
generic<typename TKey, typename TValue>
public ref class Dictionary : IDictionary<TKey, TValue>, ICollection<KeyValuePair<TKey, TValue>>, 
    IEnumerable<KeyValuePair<TKey, TValue>>, IDictionary, ICollection, IEnumerable, 
    ISerializable, IDeserializationCallback

J#

J# 支持使用泛型類型和方法，但不支持進行新的聲明。

JScript

JScript 支持泛型類型和方法。

 

類型參數

 

TKey

字典中的鍵的類型。

 

TValue

字典中的值的類型。

<script type="text/Javascript"> var ExpCollDivStr = ExpCollDivStr; ExpCollDivStr = ExpCollDivStr + "ctl00_LibFrame_ctl09fc049e3,"; var ExpCollImgStr = ExpCollImgStr; ExpCollImgStr = ExpCollImgStr + "ctl00_LibFrame_ctl09img,"; </script> 備註

Dictionary 泛型類提供了從一組鍵到一組值的映射。字典中的每個添加項都由一個值及其相關聯的鍵組成。通過鍵來檢索值的速度是非常快的，接近於 O(1)，這是因爲 Dictionary 類是作爲一個哈希表來實現的。

注意

檢索速度取決於爲 TKey 指定的類型的哈希算法的質量。

只要對象用作 Dictionary 中的鍵，它就不能以任何影響其哈希值的方式更改。使用字典的相等比較器比較時，Dictionary 中的任何鍵都必須是唯一的。鍵不能爲 空引用（在 Visual Basic 中爲 Nothing），但是如果值類型 TValue 爲引用類型，該值則可以爲空。

Dictionary 需要一個相等實現來確定鍵是否相等。可以使用一個接受 comparer 參數的構造函數來指定 IEqualityComparer 泛型接口的實現；如果不指定實現，則使用默認的泛型相等比較器 EqualityComparer.Default。如果類型 TKey 實現 System.IEquatable 泛型接口，則默認相等比較器會使用該實現。

注意

例如，您可以使用 StringComparer 類提供的不區分大小寫的字符串比較器來創建帶不區分大小寫的字符串鍵的字典。

Dictionary 的容量是 Dictionary 可以包含的元素數。在此實現中，Dictionary 的默認初始容量爲 3；但該默認值可能在 .NET Framework 的未來版本中更改。當向 Dictionary 中添加元素時，將通過重新分配內部數組來根據需要自動增大容量。

對於枚舉而言，字典中的每一項都被視爲一個表示值及其鍵的 KeyValuePair 結構進行處理。項返回的順序未定義。

C# 語言的 foreach 語句（在 C++ 中爲 for each，在 Visual Basic 中爲 For Each）需要集合中每個元素的類型。由於 Dictionary 是鍵和值的集合，因此元素類型並非鍵類型或值類型。相反，元素類型是鍵類型和值類型的 KeyValuePair。例如：

C#

複製代碼

foreach (KeyValuePair<int, string> kvp in myDictionary) {...}

C++

複製代碼

for each (KeyValuePair<int, String^> kvp in myDictionary) {...}

Visual Basic

複製代碼

For Each kvp As KeyValuePair(Of Integer, String) In myDictionary
    ...
Next kvp

foreach 語句是對枚舉數的包裝，只允許該枚舉數讀取集合，而不允許寫入集合。

<script type="text/Javascript"> var ExpCollDivStr = ExpCollDivStr; ExpCollDivStr = ExpCollDivStr + "ctl00_LibFrame_ctl1920c0237,"; var ExpCollImgStr = ExpCollImgStr; ExpCollImgStr = ExpCollImgStr + "ctl00_LibFrame_ctl19img,"; </script> 示例

下面的代碼示例創建一個空的帶有字符串鍵的字符串 Dictionary，並使用 Add 方法添加一些元素。該示例演示在嘗試添加重複的鍵時 Add 方法引發 ArgumentException。

該示例使用 Item 屬性（在 C# 中爲 索引器）來檢索值，演示當請求的鍵不存在時將引發 KeyNotFoundException，並演示與鍵相關聯的值可被替換。

該示例演示當程序必須經常嘗試字典中不存在的鍵值時，如何使用 TryGetValue 方法作爲一種更有效的方法來檢索值，它還演示如何使用 ContainsKey 方法在調用 Add 方法之前測試某個鍵是否存在。

該示例演示如何枚舉字典中的鍵和值，以及如何分別使用 Keys 屬性和 Values 屬性來單獨枚舉鍵和值。

最後，該示例演示 Remove 方法。

Visual Basic

複製代碼

Imports System
Imports System.Collections.Generic

Public Class Example
    
    Public Shared Sub Main() 

        ' Create a new dictionary of strings, with string keys.
        '
        Dim openWith As New Dictionary(Of String, String)
        
        ' Add some elements to the dictionary. There are no 
        ' duplicate keys, but some of the values are duplicates.
        openWith.Add("txt", "notepad.exe")
        openWith.Add("bmp", "paint.exe")
        openWith.Add("dib", "paint.exe")
        openWith.Add("rtf", "wordpad.exe")
        
        ' The Add method throws an exception if the new key is 
        ' already in the dictionary.
        Try
            openWith.Add("txt", "winword.exe")
        Catch 
            Console.WriteLine("An element with Key = ""txt"" already exists.")
        End Try

        ' The Item property is the default property, so you 
        ' can omit its name when accessing elements. 
        Console.WriteLine("For key = ""rtf"", value = {0}.", _
            openWith("rtf"))
        
        ' The default Item property can be used to change the value
        ' associated with a key.
        openWith("rtf") = "winword.exe"
        Console.WriteLine("For key = ""rtf"", value = {0}.", _
            openWith("rtf"))
        
        ' If a key does not exist, setting the default Item property
        ' for that key adds a new key/value pair.
        openWith("doc") = "winword.exe"

        ' The default Item property throws an exception if the requested
        ' key is not in the dictionary.
        Try
            Console.WriteLine("For key = ""tif"", value = {0}.", _
                openWith("tif"))
        Catch 
            Console.WriteLine("Key = ""tif"" is not found.")
        End Try

        ' When a program often has to try keys that turn out not to
        ' be in the dictionary, TryGetValue can be a more efficient 
        ' way to retrieve values.
        Dim value As String = ""
        If openWith.TryGetValue("tif", value) Then
            Console.WriteLine("For key = ""tif"", value = {0}.", value)
        Else
            Console.WriteLine("Key = ""tif"" is not found.")
        End If

        ' ContainsKey can be used to test keys before inserting 
        ' them.
        If Not openWith.ContainsKey("ht") Then
            openWith.Add("ht", "hypertrm.exe")
            Console.WriteLine("Value added for key = ""ht"": {0}", _
                openWith("ht"))
        End If

        ' When you use foreach to enumerate dictionary elements,
        ' the elements are retrieved as KeyValuePair objects.
        Console.WriteLine()
        For Each kvp As KeyValuePair(Of String, String) In openWith
            Console.WriteLine("Key = {0}, Value = {1}", _
                kvp.Key, kvp.Value)
        Next kvp

        ' To get the values alone, use the Values property.
        Dim valueColl As _
            Dictionary(Of String, String).ValueCollection = _
            openWith.Values
        
        ' The elements of the ValueCollection are strongly typed
        ' with the type that was specified for dictionary values.
        Console.WriteLine()
        For Each s As String In  valueColl
            Console.WriteLine("Value = {0}", s)
        Next s

        ' To get the keys alone, use the Keys property.
        Dim keyColl As _
            Dictionary(Of String, String).KeyCollection = _
            openWith.Keys
        
        ' The elements of the KeyCollection are strongly typed
        ' with the type that was specified for dictionary keys.
        Console.WriteLine()
        For Each s As String In  keyColl
            Console.WriteLine("Key = {0}", s)
        Next s

        ' Use the Remove method to remove a key/value pair.
        Console.WriteLine(vbLf + "Remove(""doc"")")
        openWith.Remove("doc")
        
        If Not openWith.ContainsKey("doc") Then
            Console.WriteLine("Key ""doc"" is not found.")
        End If

    End Sub

End Class

' This code example produces the following output:
'
'An element with Key = "txt" already exists.
'For key = "rtf", value = wordpad.exe.
'For key = "rtf", value = winword.exe.
'Key = "tif" is not found.
'Key = "tif" is not found.
'Value added for key = "ht": hypertrm.exe
'
'Key = txt, Value = notepad.exe
'Key = bmp, Value = paint.exe
'Key = dib, Value = paint.exe
'Key = rtf, Value = winword.exe
'Key = doc, Value = winword.exe
'Key = ht, Value = hypertrm.exe
'
'Value = notepad.exe
'Value = paint.exe
'Value = paint.exe
'Value = winword.exe
'Value = winword.exe
'Value = hypertrm.exe
'
'Key = txt
'Key = bmp
'Key = dib
'Key = rtf
'Key = doc
'Key = ht
'
'Remove("doc")
'Key "doc" is not found.
' 

C#

複製代碼

using System;
using System.Collections.Generic;

public class Example
{
    public static void Main()
    {
        // Create a new dictionary of strings, with string keys.
        //
        Dictionary<string, string> openWith = 
            new Dictionary<string, string>();

        // Add some elements to the dictionary. There are no 
        // duplicate keys, but some of the values are duplicates.
        openWith.Add("txt", "notepad.exe");
        openWith.Add("bmp", "paint.exe");
        openWith.Add("dib", "paint.exe");
        openWith.Add("rtf", "wordpad.exe");

        // The Add method throws an exception if the new key is 
        // already in the dictionary.
        try
        {
            openWith.Add("txt", "winword.exe");
        }
        catch (ArgumentException)
        {
            Console.WriteLine("An element with Key = /"txt/" already exists.");
        }

        // The Item property is another name for the indexer, so you 
        // can omit its name when accessing elements. 
        Console.WriteLine("For key = /"rtf/", value = {0}.", 
            openWith["rtf"]);

        // The indexer can be used to change the value associated
        // with a key.
        openWith["rtf"] = "winword.exe";
        Console.WriteLine("For key = /"rtf/", value = {0}.", 
            openWith["rtf"]);

        // If a key does not exist, setting the indexer for that key
        // adds a new key/value pair.
        openWith["doc"] = "winword.exe";

        // The indexer throws an exception if the requested key is
        // not in the dictionary.
        try
        {
            Console.WriteLine("For key = /"tif/", value = {0}.", 
                openWith["tif"]);
        }
        catch (KeyNotFoundException)
        {
            Console.WriteLine("Key = /"tif/" is not found.");
        }

        // When a program often has to try keys that turn out not to
        // be in the dictionary, TryGetValue can be a more efficient 
        // way to retrieve values.
        string value = "";
        if (openWith.TryGetValue("tif", out value))
        {
            Console.WriteLine("For key = /"tif/", value = {0}.", value);
        }
        else
        {
            Console.WriteLine("Key = /"tif/" is not found.");
        }

        // ContainsKey can be used to test keys before inserting 
        // them.
        if (!openWith.ContainsKey("ht"))
        {
            openWith.Add("ht", "hypertrm.exe");
            Console.WriteLine("Value added for key = /"ht/": {0}", 
                openWith["ht"]);
        }

        // When you use foreach to enumerate dictionary elements,
        // the elements are retrieved as KeyValuePair objects.
        Console.WriteLine();
        foreach( KeyValuePair<string, string> kvp in openWith )
        {
            Console.WriteLine("Key = {0}, Value = {1}", 
                kvp.Key, kvp.Value);
        }

        // To get the values alone, use the Values property.
        Dictionary<string, string>.ValueCollection valueColl =
            openWith.Values;

        // The elements of the ValueCollection are strongly typed
        // with the type that was specified for dictionary values.
        Console.WriteLine();
        foreach( string s in valueColl )
        {
            Console.WriteLine("Value = {0}", s);
        }

        // To get the keys alone, use the Keys property.
        Dictionary<string, string>.KeyCollection keyColl =
            openWith.Keys;

        // The elements of the KeyCollection are strongly typed
        // with the type that was specified for dictionary keys.
        Console.WriteLine();
        foreach( string s in keyColl )
        {
            Console.WriteLine("Key = {0}", s);
        }

        // Use the Remove method to remove a key/value pair.
        Console.WriteLine("/nRemove(/"doc/")");
        openWith.Remove("doc");

        if (!openWith.ContainsKey("doc"))
        {
            Console.WriteLine("Key /"doc/" is not found.");
        }
    }
}

/* This code example produces the following output:

An element with Key = "txt" already exists.
For key = "rtf", value = wordpad.exe.
For key = "rtf", value = winword.exe.
Key = "tif" is not found.
Key = "tif" is not found.
Value added for key = "ht": hypertrm.exe

Key = txt, Value = notepad.exe
Key = bmp, Value = paint.exe
Key = dib, Value = paint.exe
Key = rtf, Value = winword.exe
Key = doc, Value = winword.exe
Key = ht, Value = hypertrm.exe

Value = notepad.exe
Value = paint.exe
Value = paint.exe
Value = winword.exe
Value = winword.exe
Value = hypertrm.exe

Key = txt
Key = bmp
Key = dib
Key = rtf
Key = doc
Key = ht

Remove("doc")
Key "doc" is not found.
 */

<script type="text/Javascript"> var ExpCollDivStr = ExpCollDivStr; ExpCollDivStr = ExpCollDivStr + "ctl00_LibFrame_ctl31705f927,"; var ExpCollImgStr = ExpCollImgStr; ExpCollImgStr = ExpCollImgStr + "ctl00_LibFrame_ctl31img,"; </script> 繼承層次結構

System.Object
  System.Collections.Generic.Dictionary

<script type="text/Javascript"> var ExpCollDivStr = ExpCollDivStr; ExpCollDivStr = ExpCollDivStr + "ctl00_LibFrame_ctl33e800f6d,"; var ExpCollImgStr = ExpCollImgStr; ExpCollImgStr = ExpCollImgStr + "ctl00_LibFrame_ctl33img,"; </script> 線程安全

此類型的公共靜態（在 Visual Basic 中爲 Shared）成員是線程安全的。但不能保證任何實例成員是線程安全的。

只要不修改該集合，Dictionary 就可以同時支持多個閱讀器。即便如此，從頭到尾對一個集合進行枚舉本質上並不是一個線程安全的過程。當出現枚舉與寫訪問互相爭用這種極少發生的情況時，必須在整個枚舉過程中鎖定集合。若要允許多個線程訪問集合以進行讀寫操作，則必須實現自己的同步。

<script type="text/Javascript"> var ExpCollDivStr = ExpCollDivStr; ExpCollDivStr = ExpCollDivStr + "ctl00_LibFrame_ctl34fc73e9e,"; var ExpCollImgStr = ExpCollImgStr; ExpCollImgStr = ExpCollImgStr + "ctl00_LibFrame_ctl34img,"; </script> 平臺

Windows 98、Windows 2000 SP4、Windows CE、Windows Millennium Edition、Windows Mobile for Pocket PC、Windows Mobile for Smartphone、Windows Server 2003、Windows XP Media Center Edition、Windows XP Professional x64 Edition、Windows XP SP2、Windows XP Starter Edition

.NET Framework 並不是對每個平臺的所有版本都提供支持。有關受支持版本的列表，請參見系統要求。

<script type="text/Javascript"> var ExpCollDivStr = ExpCollDivStr; ExpCollDivStr = ExpCollDivStr + "ctl00_LibFrame_ctl36a7008ee,"; var ExpCollImgStr = ExpCollImgStr; ExpCollImgStr = ExpCollImgStr + "ctl00_LibFrame_ctl36img,"; </script> 版本信息

.NET Framework

受以下版本支持：2.0

.NET Compact Framework

受以下版本支持：2.0