This documentation is archived and is not being maintained.

StringDictionary Class

Implements a hashtable with the key strongly typed to be a string rather than an object.

For a list of all members of this type, see StringDictionary Members.

System.Object
   System.Collections.Specialized.StringDictionary

[Visual Basic]
Public Class StringDictionary
   Implements IEnumerable
[C#]
public class StringDictionary : IEnumerable
[C++]
public __gc class StringDictionary : public IEnumerable
[JScript]
public class StringDictionary implements IEnumerable

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

This implementation does not provide a synchronized (thread-safe) wrapper for a StringDictionary, but derived classes can create their own synchronized versions of the StringDictionary using the SyncRoot property.

Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.

Remarks

A key cannot be a null reference (Nothing in Visual Basic), but a value can.

The key is handled in a case-insensitive manner; it is translated to lower case before it is used with the string dictionary.

In .NET Framework version 1.0, this class uses culture-sensitive string comparisons. However, in .NET Framework version 1.1 and later, this class uses CultureInfo.InvariantCulture when comparing strings. For more information about how culture affects comparisons and sorting, see Comparing and Sorting Data for a Specific Culture and Performing Culture-Insensitive String Operations.

Example

[Visual Basic, C#, C++] The following code example demonstrates several of the properties and methods of StringDictionary.

[Visual Basic] 
Imports System
Imports System.Collections
Imports System.Collections.Specialized

Public Class SamplesStringDictionary   

   Public Shared Sub Main()

      ' Creates and initializes a new StringDictionary.
      Dim myCol As New StringDictionary()
      myCol.Add("red", "rojo")
      myCol.Add("green", "verde")
      myCol.Add("blue", "azul")

      ' Displays the values in the StringDictionary in two different ways.
      Console.WriteLine("Displays the elements using for each:")
      PrintKeysAndValues(myCol)
      Console.WriteLine("Displays the elements using the Keys, Values, Count, and indexer properties:")
      PrintKeysAndValues2(myCol)

      ' Copies the StringDictionary to an array with DictionaryEntry elements.
      Dim myArr(myCol.Count) As DictionaryEntry
      myCol.CopyTo(myArr, 0)

      ' Displays the values in the array.
      Console.WriteLine("Displays the elements in the array:")
      Console.WriteLine("   KEY        VALUE")
      Dim i As Integer
      For i = 0 To myArr.Length - 1
         Console.WriteLine("   {0,-10} {1}", myArr(i).Key, myArr(i).Value)
      Next i
      Console.WriteLine()

      ' Searches for a value.
      If myCol.ContainsValue("amarillo") Then
         Console.WriteLine("The collection contains the value ""amarillo"".")
      Else
         Console.WriteLine("The collection does not contain the value ""amarillo"".")
      End If
      Console.WriteLine()

      ' Searches for a key and deletes it.
      If myCol.ContainsKey("green") Then
         myCol.Remove("green")
      End If
      Console.WriteLine("The collection contains the following elements after removing ""green"":")
      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 StringDictionary)
      Dim de As DictionaryEntry

      Console.WriteLine("   KEY        VALUE")
      For Each de In  myCol
         Console.WriteLine("   {0,-10} {1}", de.Key, de.Value)
      Next de
      Console.WriteLine()

   End Sub 'PrintKeysAndValues

   Public Shared Sub PrintKeysAndValues2(myCol As StringDictionary)
      Dim myKeys(myCol.Count) As [String]
      myCol.Keys.CopyTo(myKeys, 0)

      Console.WriteLine("   [INDEX] KEY        VALUE")
      Dim i As Integer
      For i = 0 To myCol.Count - 1
         Console.WriteLine("   [{0}]     {1,-10} {2}", i, myKeys(i), myCol(myKeys(i)))
      Next i
      Console.WriteLine()

   End Sub 'PrintKeysAndValues2

End Class 'SamplesStringDictionary 


'This code produces the following output.
'
'Displays the elements using for each:
'   KEY        VALUE
'   green      verde
'   red        rojo
'   blue       azul
'
'Displays the elements using the Keys, Values, Count, and indexer properties:
'   [INDEX] KEY        VALUE
'   [0]     green      verde
'   [1]     red        rojo
'   [2]     blue       azul
'
'Displays the elements in the array:
'   KEY        VALUE
'   green      verde
'   red        rojo
'   blue       azul
'
'The collection does not contain the value "amarillo".
'
'The collection contains the following elements after removing "green":
'   KEY        VALUE
'   red        rojo
'   blue       azul
'
'The collection contains the following elements after it is cleared:
'   KEY        VALUE
'


[C#] 
using System;
using System.Collections;
using System.Collections.Specialized;

public class SamplesStringDictionary  {

   public static void Main()  {

      // Creates and initializes a new StringDictionary.
      StringDictionary myCol = new StringDictionary();
      myCol.Add( "red", "rojo" );
      myCol.Add( "green", "verde" );
      myCol.Add( "blue", "azul" );

      // Displays the values in the StringDictionary in two different ways.
      Console.WriteLine( "Displays the elements using foreach:" );
      PrintKeysAndValues( myCol );
      Console.WriteLine( "Displays the elements using the Keys, Values, Count, and indexer properties:" );
      PrintKeysAndValues2( myCol );

      // Copies the StringDictionary to an array with DictionaryEntry elements.
      DictionaryEntry[] myArr = new DictionaryEntry[myCol.Count];
      myCol.CopyTo( myArr, 0 );

      // Displays the values in the array.
      Console.WriteLine( "Displays the elements in the array:" );
      Console.WriteLine( "   KEY        VALUE" );
      for ( int i = 0; i < myArr.Length; i++ )
         Console.WriteLine( "   {0,-10} {1}", myArr[i].Key, myArr[i].Value );
      Console.WriteLine();

      // Searches for a value.
      if ( myCol.ContainsValue( "amarillo" ) )
         Console.WriteLine( "The collection contains the value \"amarillo\"." );
      else
         Console.WriteLine( "The collection does not contain the value \"amarillo\"." );
      Console.WriteLine();

      // Searches for a key and deletes it.
      if ( myCol.ContainsKey( "green" ) )
         myCol.Remove( "green" );
      Console.WriteLine( "The collection contains the following elements after removing \"green\":" );
      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( StringDictionary myCol )  {
      Console.WriteLine( "   KEY        VALUE" );
      foreach ( DictionaryEntry de in myCol )
         Console.WriteLine( "   {0,-10} {1}", de.Key, de.Value );
      Console.WriteLine();
   }

   public static void PrintKeysAndValues2( StringDictionary myCol )  {
      String[] myKeys = new String[myCol.Count];
      myCol.Keys.CopyTo( myKeys, 0 );

      Console.WriteLine( "   [INDEX] KEY        VALUE" );
      for ( int i = 0; i < myCol.Count; i++ )
         Console.WriteLine( "   [{0}]     {1,-10} {2}", i, myKeys[i], myCol[myKeys[i]] );
      Console.WriteLine();
   }


}

/*
This code produces the following output.

Displays the elements using foreach:
   KEY        VALUE
   green      verde
   red        rojo
   blue       azul

Displays the elements using the Keys, Values, Count, and indexer properties:
   [INDEX] KEY        VALUE
   [0]     green      verde
   [1]     red        rojo
   [2]     blue       azul

Displays the elements in the array:
   KEY        VALUE
   green      verde
   red        rojo
   blue       azul

The collection does not contain the value "amarillo".

The collection contains the following elements after removing "green":
   KEY        VALUE
   red        rojo
   blue       azul

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( StringDictionary* myCol );
void PrintKeysAndValues2( StringDictionary* myCol );

int main()  {

    // Creates and initializes a new StringDictionary.
    StringDictionary* myCol = new StringDictionary();
    myCol->Add( S"red", S"rojo" );
    myCol->Add( S"green", S"verde" );
    myCol->Add( S"blue", S"azul" );

    // Displays the values in the StringDictionary in two different ways.
    Console::WriteLine( S"Displays the elements using foreach:" );
    PrintKeysAndValues( myCol );
    Console::WriteLine( S"Displays the elements using the Keys, Values, Count, and indexer properties:" );
    PrintKeysAndValues2( myCol );

    // Copies the StringDictionary to an array with DictionaryEntry elements.
    DictionaryEntry myArr[] = new DictionaryEntry[myCol->Count];
    myCol->CopyTo( myArr, 0 );

    // Displays the values in the array.
    Console::WriteLine( S"Displays the elements in the array:" );
    Console::WriteLine( S"   KEY        VALUE" );
    for ( int i = 0; i < myArr->Length; i++ )
        Console::WriteLine( S"   {0,-10} {1}", myArr[i].Key, myArr[i].Value );
    Console::WriteLine();

    // Searches for a value.
    if ( myCol->ContainsValue( S"amarillo" ) )
        Console::WriteLine( S"The collection contains the value \"amarillo\"." );
    else
        Console::WriteLine( S"The collection does not contain the value \"amarillo\"." );
    Console::WriteLine();

    // Searches for a key and deletes it.
    if ( myCol->ContainsKey( S"green" ) )
        myCol->Remove( S"green" );
    Console::WriteLine( S"The collection contains the following elements after removing \"green\":" );
    PrintKeysAndValues( myCol );

    // Clears the entire collection.
    myCol->Clear();
    Console::WriteLine( S"The collection contains the following elements after it is cleared:" );
    PrintKeysAndValues( myCol );

}

void PrintKeysAndValues( StringDictionary* myCol )  {
    Console::WriteLine( S"   KEY        VALUE" );
    IEnumerator* myEnum = myCol->GetEnumerator();
    while (myEnum->MoveNext())
    {
        DictionaryEntry de = *__try_cast<DictionaryEntry*>(myEnum->Current);
        Console::WriteLine( S"   {0,-10} {1}", de.Key, de.Value );
    }
    Console::WriteLine();
}

void PrintKeysAndValues2( StringDictionary* myCol )  {
    String* myKeys[] = new String*[myCol->Count];
    myCol->Keys->CopyTo( myKeys, 0 );

    Console::WriteLine( S"   [INDEX] KEY        VALUE" );
    for ( int i = 0; i < myCol->Count; i++ )
        Console::WriteLine( S"   [{0}]     {1,-10} {2}", __box(i), myKeys->Item[i], myCol->Item[myKeys[i]] );
    Console::WriteLine();
}

/*
This code produces the following output.

Displays the elements using foreach:
   KEY        VALUE
   green      verde
   red        rojo
   blue       azul

Displays the elements using the Keys, Values, Count, and indexer properties:
   [INDEX] KEY        VALUE
   [0]     green      verde
   [1]     red        rojo
   [2]     blue       azul

Displays the elements in the array:
   KEY        VALUE
   green      verde
   red        rojo
   blue       azul

The collection does not contain the value "amarillo".

The collection contains the following elements after removing "green":
   KEY        VALUE
   red        rojo
   blue       azul

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 Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Collections.Specialized

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

Assembly: System (in System.dll)

See Also

StringDictionary Members | System.Collections.Specialized Namespace | Hashtable | Performing Culture-Insensitive String Operations

Show: