TOPIC
    about_Hash_Tables

SHORT DESCRIPTION
    Describes how to create, use, and sort hash tables in Windows PowerShell.


LONG DESCRIPTION
    A hash table, also known as a dictionary or associative array, is a
    compact data structure that stores one or more name/value pairs. For
    example, a hash table might contain a series of names and employee IDs,
    computer names and IP addresses, or message IDs and message text.
 

    Hash tables are frequently used because they are very efficient for finding
    and retrieving data. You can use hash tables to store lists and to create
    calculated properties in Windows PowerShell. And, Windows PowerShell has a
    cmdlet, ConvertFrom-StringData, that converts strings to a hash table.


  Creating Hash Tables
      The items in a hash table are arranged in name/value pairs, such as:


          Msg1="Please enter your password."
          Msg2="The path parameter is required."
          Msg3="The alias of Get-Command is gcm."


      The values are mapped to or associated with the names so that when you 
      submit the name, Windows PowerShell returns the value.


      In Windows PowerShell, the syntax of a hash table is as follows:

 
          @{ <name> = <value>; [<name> = <value> ] ...}


      When you create a hash table, follow these guidelines:


          - Begin the hash table with an at sign (@).

          - Enclose the hash table in braces ({}).

          - Enter one or more name-value pairs for the content of the hash 
            table.

          - Use an equal sign (=) to separate each name from its value.

          - Use a semicolon (;) to separate the name/value pairs.

          - If a name or value contains spaces, enclose it in quotation marks.


      For example, a hash table of the previous user messages looks like this:


          @{
          Msg1="Please enter your password.";
          Msg2="The path parameter is required.";
          Msg3="The alias of Get-Command is gcm.";
          }


      To use a hash table in scripts and commands, save it in a variable. The
      value of the variable is a hash table object 
      (System.Collections.Hashtable), and each name in the name/value pairs
      is a property of the hash table object.


      The following commands save the user-message hash table in the $a 
      variable and use the dot method to display the values. 


          C:\PS> $a = @{
          >> Msg1="Please enter your password.";
          >> Msg2="The path parameter is required.";
          >> Msg3="The alias of Get-Command is gcm.";
          >> }



          C:\PS> $a
          Name                           Value
          ----                           -----
          Msg1                    Please enter your password.
          Msg3                    The alias of Get-Command is gcm.
          Msg2                    The path parameter is required.

          C:\PS> $a.Msg1
          Please enter your password.


      Hash tables are not limited to one type of data. You can enter any data 
      type in a hash table, and you can combine data types in a single hash 
      table. For example, you can build a hash table that contains an integer,
      a call to a cmdlet, and a string.


  Sorting Hash Tables
      To sort the hash table alphabetically by keys or values, use the 
      GetEnumerator method of hash tables to get the keys and values in the 
      hash table, and then use the Sort-Object cmdlet to sort them.


      For example, the following command sorts the hash table in $a 
      alphabetically by keys.


          C:\PS> $a.getenumerator() | sort-object -property key

          Name                           Value
          ----                           -----
          Msg1                           Please enter your password.
          Msg2                           The path parameter is required.
          Msg3                           The alias of Get-Command is gcm.


      The following command uses the same method to sort the hash values in 
      descending order.


          C:\PS> $a.getenumerator() | sort-object -property value -descending

          Name                           Value
          ----                           -----
          Msg2                           The path parameter is required.
          Msg3                           The alias of Get-Command is gcm.
          Msg1                           Please enter your password.



  ConvertFrom-StringData
      The ConvertFrom-StringData cmdlet converts a string or a here-string of 
      name/value pairs into a hash table. You can use the 
      ConvertFrom-StringData cmdlet safely in the Data section of a script, 
      and you can use it with the Import-LocalizedData cmdlet to display user
      messages in the user-interface (UI) culture of the current user.


      Here-strings are especially useful when the values in the hash table 
      include quotation marks. (For more information about here-strings, see
      about_Quoting_Rules.)


      The following example shows how to create a here-string of the user 
      messages in the previous example and how to use ConvertFrom-StringData
      to convert them from a string into a hash table.


      The following command creates a here-string of the name/value pairs and
      then saves it in the $string variable.


          C:\PS> $string = @"
          Msg1="Please enter your password."
          Msg2="The path parameter is required."
          Msg3="The alias of Get-Command is gcm."
          "@

   
    This command uses the ConvertFrom-StringData cmdlet to convert the 
    here-string into a hash table.


        C:\PS> convertfrom-stringdata $string

        Name                           Value
        ----                           -----
        Msg3                           "The alias of Get-Command is gcm."
        Msg2                           "The path parameter is required."
        Msg1                           "Please enter your password."


SEE ALSO
    about_Arrays
    about_Quoting_Rules
    about_Script_Internationalization 
    ConvertFrom-StringData
    Import-LocalizedData
    
