Dictionary ジェネリック クラス

.NET Framework クラス ライブラリ リファレンス

Dictionary ジェネリック クラス

メモ : このクラスは、.NET Framework version 2.0 で新しく追加されたものです。

キーと値のコレクションを表します。

名前空間: System.Collections.Generic
アセンブリ: mscorlib (mscorlib.dll 内)
構文

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

ディクショナリ内の値の型。

解説

Dictionary ジェネリック クラスにより、キーのセットを値のセットに対応付けることができます。ディクショナリに追加される各エントリは、値とその値に関連付けられたキーで構成されます。Dictionary クラスはハッシュ テーブルとして実装されているため、キーを使用した値の取得は非常に高速で、O(1) に近くなります。

メモ
取得速度は、TKey に指定されている型のハッシュ アルゴリズムの品質によって異なります。

オブジェクトが Dictionary のキーとして使用されている場合、そのオブジェクトに対してハッシュ値に影響するような変更を行わないでください。Dictionary 内のすべてのキーは、ディクショナリの等値比較演算子に従って、一意である必要があります。キーを null 参照 (Visual Basic では Nothing) にすることはできませんが、値の型 TValue が参照型である場合、値を null にすることはできます。

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 ステートメントは、列挙子のラッパーです。これは、コレクションからの読み取りだけを許可し、コレクションへの書き込みはできません。

使用例

文字列キーを含む文字列の空の 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.
 */

継承階層

System.Object
  System.Collections.Generic.Dictionary

スレッド セーフ

この型の public static (Visual Basic では Shared) メンバは、スレッド セーフです。すべてのインスタンス メンバがスレッド セーフになるかどうかは保証されていません。

コレクションが変更されない限り、Dictionary では、複数の読み込み操作が同時に発生しても問題ありません。ただし、コレクションの列挙処理は、本質的にはスレッド セーフな処理ではありません。まれに書き込みアクセスによって列挙処理で競合が発生する場合、列挙処理が完了するまでコレクションをロックする必要があります。コレクションに対し複数のスレッドがアクセスして読み取りや書き込みを行うことができるようにするには、独自に同期化を実装する必要があります。

プラットフォーム

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 によってサポートされていないバージョンがあります。サポートされているバージョンについては、「システム要件」を参照してください。

バージョン情報

.NET Framework
サポート対象 : 2.0
.NET Compact Framework
サポート対象 : 2.0

参照

関連項目
Dictionary メンバ
System.Collections.Generic 名前空間
IDictionary
SortedList
KeyValuePair
IEqualityComparer