Dictionary<TKey,TValue> Constructors

Definition

Namespace:

System.Collections.Generic

Assemblies:

netstandard.dll, System.Collections.dll

Initializes a new instance of the Dictionary<TKey,TValue> class.

Overloads

Dictionary<TKey,TValue>()	Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the default initial capacity, and uses the default equality comparer for the key type.
Dictionary<TKey,TValue>(IDictionary<TKey,TValue>)	Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IDictionary<TKey,TValue> and uses the default equality comparer for the key type.
Dictionary<TKey,TValue>(IEnumerable<KeyValuePair<TKey,TValue>>)	Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IEnumerable<T>.
Dictionary<TKey,TValue>(IEqualityComparer<TKey>)	Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the default initial capacity, and uses the specified IEqualityComparer<T>.
Dictionary<TKey,TValue>(Int32)	Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the specified initial capacity, and uses the default equality comparer for the key type.
Dictionary<TKey,TValue>(IDictionary<TKey,TValue>, IEqualityComparer<TKey>)	Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IDictionary<TKey,TValue> and uses the specified IEqualityComparer<T>.
Dictionary<TKey,TValue>(IEnumerable<KeyValuePair<TKey,TValue>>, IEqualityComparer<TKey>)	Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IEnumerable<T> and uses the specified IEqualityComparer<T>.
Dictionary<TKey,TValue>(Int32, IEqualityComparer<TKey>)	Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the specified initial capacity, and uses the specified IEqualityComparer<T>.
Dictionary<TKey,TValue>(SerializationInfo, StreamingContext)	Obsolete. Initializes a new instance of the Dictionary<TKey,TValue> class with serialized data.

Dictionary<TKey,TValue>()

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the default initial capacity, and uses the default equality comparer for the key type.

C#

public Dictionary();

Examples

The following code example creates an empty Dictionary<TKey,TValue> of strings with string keys and uses the Add method to add some elements. The example demonstrates that the Add method throws an ArgumentException when attempting to add a duplicate key.

This code example is part of a larger example provided for the Dictionary<TKey,TValue> class.

C#

// 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.");
}

Remarks

Every key in a Dictionary<TKey,TValue> must be unique according to the default equality comparer.

Dictionary<TKey,TValue> requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, EqualityComparer<T>.Default. If type TKey implements the System.IEquatable<T> generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the IEqualityComparer<T> generic interface by using a constructor that accepts a comparer parameter.

Note

If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the Dictionary<TKey,TValue>.

This constructor is an O(1) operation.

See also

• IImmutableDictionary<TKey,TValue>
• Default
• IEquatable<T>

Dictionary<TKey,TValue>(IDictionary<TKey,TValue>)

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IDictionary<TKey,TValue> and uses the default equality comparer for the key type.

C#

public Dictionary(System.Collections.Generic.IDictionary<TKey,TValue> dictionary);

Parameters

dictionary

IDictionary<TKey,TValue>

The IDictionary<TKey,TValue> whose elements are copied to the new Dictionary<TKey,TValue>.

Exceptions

ArgumentNullException

dictionary is null.

ArgumentException

dictionary contains one or more duplicate keys.

Examples

The following code example shows how to use the Dictionary<TKey,TValue>(IEqualityComparer<TKey>) constructor to initialize a Dictionary<TKey,TValue> with sorted content from another dictionary. The code example creates a SortedDictionary<TKey,TValue> and populates it with data in random order, then passes the SortedDictionary<TKey,TValue> to the Dictionary<TKey,TValue>(IEqualityComparer<TKey>) constructor, creating a Dictionary<TKey,TValue> that is sorted. This is useful if you need to build a sorted dictionary that at some point becomes static; copying the data from a SortedDictionary<TKey,TValue> to a Dictionary<TKey,TValue> improves retrieval speed.

C#

using System;
using System.Collections.Generic;

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

        // Add some elements to the dictionary.
        openWith.Add("txt", "notepad.exe");
        openWith.Add("bmp", "paint.exe");
        openWith.Add("dib", "paint.exe");
        openWith.Add("rtf", "wordpad.exe");

        // Create a Dictionary of strings with string keys, and
        // initialize it with the contents of the sorted dictionary.
        Dictionary<string, string> copy =
            new Dictionary<string, string>(openWith);

        // List the contents of the copy.
        Console.WriteLine();
        foreach( KeyValuePair<string, string> kvp in copy )
        {
            Console.WriteLine("Key = {0}, Value = {1}",
               kvp.Key, kvp.Value);
        }
    }
}

/* This code example produces the following output:

Key = bmp, Value = paint.exe
Key = dib, Value = paint.exe
Key = rtf, Value = wordpad.exe
Key = txt, Value = notepad.exe
 */

Remarks

Every key in a Dictionary<TKey,TValue> must be unique according to the default equality comparer; likewise, every key in the source dictionary must also be unique according to the default equality comparer.

The initial capacity of the new Dictionary<TKey,TValue> is large enough to contain all the elements in dictionary.

Dictionary<TKey,TValue> requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, EqualityComparer<T>.Default. If type TKey implements the System.IEquatable<T> generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the IEqualityComparer<T> generic interface by using a constructor that accepts a comparer parameter.

This constructor is an O(n) operation, where n is the number of elements in dictionary.

See also

• IDictionary<TKey,TValue>
• Default
• IEquatable<T>

Dictionary<TKey,TValue>(IEnumerable<KeyValuePair<TKey,TValue>>)

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IEnumerable<T>.

C#

public Dictionary(System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey,TValue>> collection);

Parameters

collection

IEnumerable<KeyValuePair<TKey,TValue>>

The IEnumerable<T> whose elements are copied to the new Dictionary<TKey,TValue>.

Exceptions

ArgumentNullException

collection is null.

ArgumentException

collection contains one or more duplicated keys.

Dictionary<TKey,TValue>(IEqualityComparer<TKey>)

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the default initial capacity, and uses the specified IEqualityComparer<T>.

C#

public Dictionary(System.Collections.Generic.IEqualityComparer<TKey>? comparer);

Parameters

comparer

IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

Examples

The following code example creates a Dictionary<TKey,TValue> with a case-insensitive equality comparer for the current culture. The example adds four elements, some with lower-case keys and some with upper-case keys. The example then attempts to add an element with a key that differs from an existing key only by case, catches the resulting exception, and displays an error message. Finally, the example displays the elements in the dictionary.

C#

using System;
using System.Collections.Generic;

public class Example
{
    public static void Main()
    {
        // Create a new Dictionary of strings, with string keys
        // and a case-insensitive comparer for the current culture.
        Dictionary<string, string> openWith =
                      new Dictionary<string, string>(
                          StringComparer.CurrentCultureIgnoreCase);

        // Add some elements to the dictionary.
        openWith.Add("txt", "notepad.exe");
        openWith.Add("bmp", "paint.exe");
        openWith.Add("DIB", "paint.exe");
        openWith.Add("rtf", "wordpad.exe");

        // Try to add a fifth element with a key that is the same
        // except for case; this would be allowed with the default
        // comparer.
        try
        {
            openWith.Add("BMP", "paint.exe");
        }
        catch (ArgumentException)
        {
            Console.WriteLine("\nBMP is already in the dictionary.");
        }

        // List the contents of the sorted dictionary.
        Console.WriteLine();
        foreach( KeyValuePair<string, string> kvp in openWith )
        {
            Console.WriteLine("Key = {0}, Value = {1}", kvp.Key,
                kvp.Value);
        }
    }
}

/* This code example produces the following output:

BMP is already in the dictionary.

Key = txt, Value = notepad.exe
Key = bmp, Value = paint.exe
Key = DIB, Value = paint.exe
Key = rtf, Value = wordpad.exe
 */

Remarks

Use this constructor with the case-insensitive string comparers provided by the StringComparer class to create dictionaries with case-insensitive string keys.

Every key in a Dictionary<TKey,TValue> must be unique according to the specified comparer.

Dictionary<TKey,TValue> requires an equality implementation to determine whether keys are equal. If comparer is null, this constructor uses the default generic equality comparer, EqualityComparer<T>.Default. If type TKey implements the System.IEquatable<T> generic interface, the default equality comparer uses that implementation.

Note

If you can estimate the size of the collection, using a constructor that specifies the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the Dictionary<TKey,TValue>.

This constructor is an O(1) operation.

See also

• IEqualityComparer<T>
• Default
• IEquatable<T>

Dictionary<TKey,TValue>(Int32)

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the specified initial capacity, and uses the default equality comparer for the key type.

C#

public Dictionary(int capacity);

Parameters

capacity

Int32

The initial number of elements that the Dictionary<TKey,TValue> can contain.

Exceptions

ArgumentOutOfRangeException

capacity is less than 0.

Examples

The following code example creates a dictionary with an initial capacity of 4 and populates it with 4 entries.

C#

using System;
using System.Collections.Generic;

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

        // Add 4 elements to the dictionary.
        openWith.Add("txt", "notepad.exe");
        openWith.Add("bmp", "paint.exe");
        openWith.Add("dib", "paint.exe");
        openWith.Add("rtf", "wordpad.exe");

        // List the contents of the dictionary.
        Console.WriteLine();
        foreach( KeyValuePair<string, string> kvp in openWith )
        {
            Console.WriteLine("Key = {0}, Value = {1}",
               kvp.Key, kvp.Value);
        }
    }
}

/* This code example produces the following output:

Key = txt, Value = notepad.exe
Key = bmp, Value = paint.exe
Key = dib, Value = paint.exe
Key = rtf, Value = wordpad.exe
 */

Remarks

Every key in a Dictionary<TKey,TValue> must be unique according to the default equality comparer.

The capacity of a Dictionary<TKey,TValue> is the number of elements that can be added to the Dictionary<TKey,TValue> before resizing is necessary. As elements are added to a Dictionary<TKey,TValue>, the capacity is automatically increased as required by reallocating the internal array.

If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the Dictionary<TKey,TValue>.

Dictionary<TKey,TValue> requires an equality implementation to determine whether keys are equal. This constructor uses the default generic equality comparer, EqualityComparer<T>.Default. If type TKey implements the System.IEquatable<T> generic interface, the default equality comparer uses that implementation. Alternatively, you can specify an implementation of the IEqualityComparer<T> generic interface by using a constructor that accepts a comparer parameter.

This constructor is an O(1) operation.

See also

• Default
• IEquatable<T>

Dictionary<TKey,TValue>(IDictionary<TKey,TValue>, IEqualityComparer<TKey>)

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IDictionary<TKey,TValue> and uses the specified IEqualityComparer<T>.

C#

public Dictionary(System.Collections.Generic.IDictionary<TKey,TValue> dictionary, System.Collections.Generic.IEqualityComparer<TKey>? comparer);

Parameters

dictionary

IDictionary<TKey,TValue>

The IDictionary<TKey,TValue> whose elements are copied to the new Dictionary<TKey,TValue>.

comparer

IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

Exceptions

ArgumentNullException

dictionary is null.

ArgumentException

dictionary contains one or more duplicate keys.

Examples

The following code example shows how to use the Dictionary<TKey,TValue>(IDictionary<TKey,TValue>, IEqualityComparer<TKey>) constructor to initialize a Dictionary<TKey,TValue> with case-insensitive sorted content from another dictionary. The code example creates a SortedDictionary<TKey,TValue> with a case-insensitive comparer and populates it with data in random order, then passes the SortedDictionary<TKey,TValue> to the Dictionary<TKey,TValue>(IDictionary<TKey,TValue>, IEqualityComparer<TKey>) constructor, along with a case-insensitive equality comparer, creating a Dictionary<TKey,TValue> that is sorted. This is useful if you need to build a sorted dictionary that at some point becomes static; copying the data from a SortedDictionary<TKey,TValue> to a Dictionary<TKey,TValue> improves retrieval speed.

Note

When you create a new dictionary with a case-insensitive comparer and populate it with entries from a dictionary that uses a case-sensitive comparer, as in this example, an exception occurs if the input dictionary has keys that differ only by case.

C#

using System;
using System.Collections.Generic;

public class Example
{
    public static void Main()
    {
        // Create a new sorted dictionary of strings, with string
        // keys and a case-insensitive comparer.
        SortedDictionary<string, string> openWith =
                new SortedDictionary<string, string>(
                    StringComparer.CurrentCultureIgnoreCase);

        // Add some elements to the dictionary.
        openWith.Add("txt", "notepad.exe");
        openWith.Add("Bmp", "paint.exe");
        openWith.Add("DIB", "paint.exe");
        openWith.Add("rtf", "wordpad.exe");

        // Create a Dictionary of strings with string keys and a
        // case-insensitive equality comparer, and initialize it
        // with the contents of the sorted dictionary.
        Dictionary<string, string> copy =
                new Dictionary<string, string>(openWith,
                    StringComparer.CurrentCultureIgnoreCase);

        // List the contents of the copy.
        Console.WriteLine();
        foreach( KeyValuePair<string, string> kvp in copy )
        {
            Console.WriteLine("Key = {0}, Value = {1}",
               kvp.Key, kvp.Value);
        }
    }
}

/* This code example produces the following output:

Key = Bmp, Value = paint.exe
Key = DIB, Value = paint.exe
Key = rtf, Value = wordpad.exe
Key = txt, Value = notepad.exe
 */

Remarks

Use this constructor with the case-insensitive string comparers provided by the StringComparer class to create dictionaries with case-insensitive string keys.

Every key in a Dictionary<TKey,TValue> must be unique according to the specified comparer; likewise, every key in the source dictionary must also be unique according to the specified comparer.

Note

For example, duplicate keys can occur if comparer is one of the case-insensitive string comparers provided by the StringComparer class and dictionary does not use a case-insensitive comparer key.

The initial capacity of the new Dictionary<TKey,TValue> is large enough to contain all the elements in dictionary.

Dictionary<TKey,TValue> requires an equality implementation to determine whether keys are equal. If comparer is null, this constructor uses the default generic equality comparer, EqualityComparer<T>.Default. If type TKey implements the System.IEquatable<T> generic interface, the default equality comparer uses that implementation.

This constructor is an O(n) operation, where n is the number of elements in dictionary.

See also

• IDictionary<TKey,TValue>
• IEqualityComparer<T>
• Default
• IEquatable<T>

Dictionary<TKey,TValue>(IEnumerable<KeyValuePair<TKey,TValue>>, IEqualityComparer<TKey>)

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that contains elements copied from the specified IEnumerable<T> and uses the specified IEqualityComparer<T>.

C#

public Dictionary(System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey,TValue>> collection, System.Collections.Generic.IEqualityComparer<TKey>? comparer);

Parameters

collection

IEnumerable<KeyValuePair<TKey,TValue>>

The IEnumerable<T> whose elements are copied to the new Dictionary<TKey,TValue>.

comparer

IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

Exceptions

ArgumentNullException

collection is null.

ArgumentException

collection contains one or more duplicated keys.

Dictionary<TKey,TValue>(Int32, IEqualityComparer<TKey>)

Source:

Dictionary.cs

Initializes a new instance of the Dictionary<TKey,TValue> class that is empty, has the specified initial capacity, and uses the specified IEqualityComparer<T>.

C#

public Dictionary(int capacity, System.Collections.Generic.IEqualityComparer<TKey>? comparer);

Parameters

capacity

Int32

The initial number of elements that the Dictionary<TKey,TValue> can contain.

comparer

IEqualityComparer<TKey>

The IEqualityComparer<T> implementation to use when comparing keys, or null to use the default EqualityComparer<T> for the type of the key.

Exceptions

ArgumentOutOfRangeException

capacity is less than 0.

Examples

The following code example creates a Dictionary<TKey,TValue> with an initial capacity of 5 and a case-insensitive equality comparer for the current culture. The example adds four elements, some with lower-case keys and some with upper-case keys. The example then attempts to add an element with a key that differs from an existing key only by case, catches the resulting exception, and displays an error message. Finally, the example displays the elements in the dictionary.

C#

using System;
using System.Collections.Generic;

public class Example
{
    public static void Main()
    {
        // Create a new dictionary of strings, with string keys, an
        // initial capacity of 5, and a case-insensitive equality
        // comparer.
        Dictionary<string, string> openWith =
                      new Dictionary<string, string>(5,
                          StringComparer.CurrentCultureIgnoreCase);

        // Add 4 elements to the dictionary.
        openWith.Add("txt", "notepad.exe");
        openWith.Add("bmp", "paint.exe");
        openWith.Add("DIB", "paint.exe");
        openWith.Add("rtf", "wordpad.exe");

        // Try to add a fifth element with a key that is the same
        // except for case; this would be allowed with the default
        // comparer.
        try
        {
            openWith.Add("BMP", "paint.exe");
        }
        catch (ArgumentException)
        {
            Console.WriteLine("\nBMP is already in the dictionary.");
        }

        // List the contents of the dictionary.
        Console.WriteLine();
        foreach( KeyValuePair<string, string> kvp in openWith )
        {
            Console.WriteLine("Key = {0}, Value = {1}", kvp.Key,
                kvp.Value);
        }
    }
}

/* This code example produces the following output:

BMP is already in the dictionary.

Key = txt, Value = notepad.exe
Key = bmp, Value = paint.exe
Key = DIB, Value = paint.exe
Key = rtf, Value = wordpad.exe
 */

Remarks

Use this constructor with the case-insensitive string comparers provided by the StringComparer class to create dictionaries with case-insensitive string keys.

Every key in a Dictionary<TKey,TValue> must be unique according to the specified comparer.

The capacity of a Dictionary<TKey,TValue> is the number of elements that can be added to the Dictionary<TKey,TValue> before resizing is necessary. As elements are added to a Dictionary<TKey,TValue>, the capacity is automatically increased as required by reallocating the internal array.

If the size of the collection can be estimated, specifying the initial capacity eliminates the need to perform a number of resizing operations while adding elements to the Dictionary<TKey,TValue>.

Dictionary<TKey,TValue> requires an equality implementation to determine whether keys are equal. If comparer is null, this constructor uses the default generic equality comparer, EqualityComparer<T>.Default. If type TKey implements the System.IEquatable<T> generic interface, the default equality comparer uses that implementation.

This constructor is an O(1) operation.

See also

• IEqualityComparer<T>
• Default
• IEquatable<T>

Dictionary<TKey,TValue>(SerializationInfo, StreamingContext)

Source:

Dictionary.cs

Caution

This API supports obsolete formatter-based serialization. It should not be called or extended by application code.

Initializes a new instance of the Dictionary<TKey,TValue> class with serialized data.

C#

[System.Obsolete("This API supports obsolete formatter-based serialization. It should not be called or extended by application code.", DiagnosticId="SYSLIB0051", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
protected Dictionary(System.Runtime.Serialization.SerializationInfo info, System.Runtime.Serialization.StreamingContext context);

Parameters

info

SerializationInfo

A SerializationInfo object containing the information required to serialize the Dictionary<TKey,TValue>.

context

StreamingContext

A StreamingContext structure containing the source and destination of the serialized stream associated with the Dictionary<TKey,TValue>.

Attributes

ObsoleteAttribute

Remarks

This constructor is called during deserialization to reconstitute an object transmitted over a stream. For more information, see XML and SOAP Serialization.

See also

• System.Runtime.Serialization