about_Hash_Tables

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