HybridDictionary.Add Method
Adds an entry with the specified key and value into the HybridDictionary.
[Visual Basic] Public Overridable Sub Add( _ ByVal key As Object, _ ByVal value As Object _ ) Implements IDictionary.Add [C#] public virtual void Add( object key, object value ); [C++] public: virtual void Add( Object* key, Object* value ); [JScript] public function Add( key : Object, value : Object );
Parameters
- key
- The key of the entry to add.
- value
- The value of the entry to add. The value can be a null reference (Nothing in Visual Basic).
Implements
Exceptions
| Exception Type | Condition |
|---|---|
| ArgumentNullException | key is a null reference (Nothing in Visual Basic). |
| ArgumentException | An entry with the same key already exists in the HybridDictionary. |
Remarks
An object that has no correlation between its state and its hash code value should typically not be used as the key. For example, String objects are better than StringBuilder objects for use as keys.
A key cannot be a null reference (Nothing in Visual Basic), but a value can.
The Item property can also be used to add new elements by setting the value of a key that does not exist in the HybridDictionary. For example: myCollection["myNonexistentKey"] = myValue. However, if the specified key already exists in the HybridDictionary, setting the Item property overwrites the old value. In contrast, the Add method does not modify existing elements.
When the number of elements becomes greater than the optimal size for a ListDictionary, the elements are copied from the ListDictionary to a Hashtable. However, this only happens once. If the collection is already stored in a Hashtable and the number of elements falls below the optimal size for a ListDictionary, the collection remains in the Hashtable.
Example
[Visual Basic, C#, C++] The following code example adds to and removes elements from a HybridDictionary.
[Visual Basic] Imports System Imports System.Collections Imports System.Collections.Specialized Public Class SamplesHybridDictionary Public Shared Sub Main() ' Creates and initializes a new HybridDictionary. Dim myCol As New HybridDictionary() myCol.Add("Braeburn Apples", "1.49") myCol.Add("Fuji Apples", "1.29") myCol.Add("Gala Apples", "1.49") myCol.Add("Golden Delicious Apples", "1.29") myCol.Add("Granny Smith Apples", "0.89") myCol.Add("Red Delicious Apples", "0.99") myCol.Add("Plantain Bananas", "1.49") myCol.Add("Yellow Bananas", "0.79") myCol.Add("Strawberries", "3.33") myCol.Add("Cranberries", "5.98") myCol.Add("Navel Oranges", "1.29") myCol.Add("Grapes", "1.99") myCol.Add("Honeydew Melon", "0.59") myCol.Add("Seedless Watermelon", "0.49") myCol.Add("Pineapple", "1.49") myCol.Add("Nectarine", "1.99") myCol.Add("Plums", "1.69") myCol.Add("Peaches", "1.99") ' Displays the values in the HybridDictionary in three different ways. Console.WriteLine("Initial contents of the HybridDictionary:") PrintKeysAndValues(myCol) ' Deletes a key. myCol.Remove("Plums") Console.WriteLine("The collection contains the following elements after removing ""Plums"":") PrintKeysAndValues(myCol) ' Clears the entire collection. myCol.Clear() Console.WriteLine("The collection contains the following elements after it is cleared:") PrintKeysAndValues(myCol) End Sub 'Main Public Shared Sub PrintKeysAndValues(myCol As IDictionary) Console.WriteLine(" KEY VALUE") Dim de As DictionaryEntry For Each de In myCol Console.WriteLine(" {0,-25} {1}", de.Key, de.Value) Next de Console.WriteLine() End Sub 'PrintKeysAndValues End Class 'SamplesHybridDictionary 'This code produces the following output. ' 'Initial contents of the HybridDictionary: ' KEY VALUE ' Seedless Watermelon 0.49 ' Nectarine 1.99 ' Cranberries 5.98 ' Plantain Bananas 1.49 ' Honeydew Melon 0.59 ' Pineapple 1.49 ' Strawberries 3.33 ' Grapes 1.99 ' Braeburn Apples 1.49 ' Peaches 1.99 ' Red Delicious Apples 0.99 ' Golden Delicious Apples 1.29 ' Yellow Bananas 0.79 ' Granny Smith Apples 0.89 ' Gala Apples 1.49 ' Plums 1.69 ' Navel Oranges 1.29 ' Fuji Apples 1.29 ' 'The collection contains the following elements after removing "Plums": ' KEY VALUE ' Seedless Watermelon 0.49 ' Nectarine 1.99 ' Cranberries 5.98 ' Plantain Bananas 1.49 ' Honeydew Melon 0.59 ' Pineapple 1.49 ' Strawberries 3.33 ' Grapes 1.99 ' Braeburn Apples 1.49 ' Peaches 1.99 ' Red Delicious Apples 0.99 ' Golden Delicious Apples 1.29 ' Yellow Bananas 0.79 ' Granny Smith Apples 0.89 ' Gala Apples 1.49 ' Navel Oranges 1.29 ' Fuji Apples 1.29 ' 'The collection contains the following elements after it is cleared: ' KEY VALUE ' [C#] using System; using System.Collections; using System.Collections.Specialized; public class SamplesHybridDictionary { public static void Main() { // Creates and initializes a new HybridDictionary. HybridDictionary myCol = new HybridDictionary(); myCol.Add( "Braeburn Apples", "1.49" ); myCol.Add( "Fuji Apples", "1.29" ); myCol.Add( "Gala Apples", "1.49" ); myCol.Add( "Golden Delicious Apples", "1.29" ); myCol.Add( "Granny Smith Apples", "0.89" ); myCol.Add( "Red Delicious Apples", "0.99" ); myCol.Add( "Plantain Bananas", "1.49" ); myCol.Add( "Yellow Bananas", "0.79" ); myCol.Add( "Strawberries", "3.33" ); myCol.Add( "Cranberries", "5.98" ); myCol.Add( "Navel Oranges", "1.29" ); myCol.Add( "Grapes", "1.99" ); myCol.Add( "Honeydew Melon", "0.59" ); myCol.Add( "Seedless Watermelon", "0.49" ); myCol.Add( "Pineapple", "1.49" ); myCol.Add( "Nectarine", "1.99" ); myCol.Add( "Plums", "1.69" ); myCol.Add( "Peaches", "1.99" ); // Displays the values in the HybridDictionary in three different ways. Console.WriteLine( "Initial contents of the HybridDictionary:" ); PrintKeysAndValues( myCol ); // Deletes a key. myCol.Remove( "Plums" ); Console.WriteLine( "The collection contains the following elements after removing \"Plums\":" ); PrintKeysAndValues( myCol ); // Clears the entire collection. myCol.Clear(); Console.WriteLine( "The collection contains the following elements after it is cleared:" ); PrintKeysAndValues( myCol ); } public static void PrintKeysAndValues( IDictionary myCol ) { Console.WriteLine( " KEY VALUE" ); foreach ( DictionaryEntry de in myCol ) Console.WriteLine( " {0,-25} {1}", de.Key, de.Value ); Console.WriteLine(); } } /* This code produces the following output. Initial contents of the HybridDictionary: KEY VALUE Seedless Watermelon 0.49 Nectarine 1.99 Cranberries 5.98 Plantain Bananas 1.49 Honeydew Melon 0.59 Pineapple 1.49 Strawberries 3.33 Grapes 1.99 Braeburn Apples 1.49 Peaches 1.99 Red Delicious Apples 0.99 Golden Delicious Apples 1.29 Yellow Bananas 0.79 Granny Smith Apples 0.89 Gala Apples 1.49 Plums 1.69 Navel Oranges 1.29 Fuji Apples 1.29 The collection contains the following elements after removing "Plums": KEY VALUE Seedless Watermelon 0.49 Nectarine 1.99 Cranberries 5.98 Plantain Bananas 1.49 Honeydew Melon 0.59 Pineapple 1.49 Strawberries 3.33 Grapes 1.99 Braeburn Apples 1.49 Peaches 1.99 Red Delicious Apples 0.99 Golden Delicious Apples 1.29 Yellow Bananas 0.79 Granny Smith Apples 0.89 Gala Apples 1.49 Navel Oranges 1.29 Fuji Apples 1.29 The collection contains the following elements after it is cleared: KEY VALUE */ [C++] #using <mscorlib.dll> #using <System.dll> using namespace System; using namespace System::Collections; using namespace System::Collections::Specialized; void PrintKeysAndValues( IDictionary* myCol ) { Console::WriteLine( S" KEY VALUE" ); IEnumerator* myEnum = myCol->GetEnumerator(); while (myEnum->MoveNext()) { DictionaryEntry de = *__try_cast<DictionaryEntry*>(myEnum->Current); Console::WriteLine( S" {0,-25} {1}", de.Key, de.Value ); } Console::WriteLine(); } int main() { // Creates and initializes a new HybridDictionary. HybridDictionary* myCol = new HybridDictionary(); myCol->Add( S"Braeburn Apples", S"1.49" ); myCol->Add( S"Fuji Apples", S"1.29" ); myCol->Add( S"Gala Apples", S"1.49" ); myCol->Add( S"Golden Delicious Apples", S"1.29" ); myCol->Add( S"Granny Smith Apples", S"0.89" ); myCol->Add( S"Red Delicious Apples", S"0.99" ); myCol->Add( S"Plantain Bananas", S"1.49" ); myCol->Add( S"Yellow Bananas", S"0.79" ); myCol->Add( S"Strawberries", S"3.33" ); myCol->Add( S"Cranberries", S"5.98" ); myCol->Add( S"Navel Oranges", S"1.29" ); myCol->Add( S"Grapes", S"1.99" ); myCol->Add( S"Honeydew Melon", S"0.59" ); myCol->Add( S"Seedless Watermelon", S"0.49" ); myCol->Add( S"Pineapple", S"1.49" ); myCol->Add( S"Nectarine", S"1.99" ); myCol->Add( S"Plums", S"1.69" ); myCol->Add( S"Peaches", S"1.99" ); // Displays the values in the HybridDictionary in three different ways. Console::WriteLine( S"Initial contents of the HybridDictionary:" ); PrintKeysAndValues( myCol ); // Deletes a key. myCol->Remove( S"Plums" ); Console::WriteLine( S"The collection contains the following elements after removing \"Plums\":" ); PrintKeysAndValues( myCol ); // Clears the entire collection. myCol->Clear(); Console::WriteLine( S"The collection contains the following elements after it is cleared:" ); PrintKeysAndValues( myCol ); } /* This code produces the following output. Initial contents of the HybridDictionary: KEY VALUE Seedless Watermelon 0.49 Nectarine 1.99 Cranberries 5.98 Plantain Bananas 1.49 Honeydew Melon 0.59 Pineapple 1.49 Strawberries 3.33 Grapes 1.99 Braeburn Apples 1.49 Peaches 1.99 Red Delicious Apples 0.99 Golden Delicious Apples 1.29 Yellow Bananas 0.79 Granny Smith Apples 0.89 Gala Apples 1.49 Plums 1.69 Navel Oranges 1.29 Fuji Apples 1.29 The collection contains the following elements after removing "Plums": KEY VALUE Seedless Watermelon 0.49 Nectarine 1.99 Cranberries 5.98 Plantain Bananas 1.49 Honeydew Melon 0.59 Pineapple 1.49 Strawberries 3.33 Grapes 1.99 Braeburn Apples 1.49 Peaches 1.99 Red Delicious Apples 0.99 Golden Delicious Apples 1.29 Yellow Bananas 0.79 Granny Smith Apples 0.89 Gala Apples 1.49 Navel Oranges 1.29 Fuji Apples 1.29 The collection contains the following elements after it is cleared: KEY VALUE */
[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button
in the upper-left corner of the page.
Requirements
Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework
See Also
HybridDictionary Class | HybridDictionary Members | System.Collections.Specialized Namespace | Remove | Item | IDictionary.Add