diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 909c83aa0118..8830a0564507 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,7 +1,7 @@ --- description: Describes how to create, use, and sort hashtables in PowerShell. Locale: en-US -ms.date: 11/15/2023 +ms.date: 09/04/2024 no-loc: [iDictionary, Hashtable, OrderedDictionary, System.Collections.IDictionary, System.Collections.Hashtable] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_hash_tables?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -19,16 +19,16 @@ structure that stores one or more key-value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In PowerShell, each hashtable is a **Hashtable** -`[System.Collections.Hashtable]` object. You can use the properties and methods -of **Hashtable** objects in PowerShell. +In PowerShell, each hashtable is a `[System.Collections.Hashtable]` object. You +can use the properties and methods of **Hashtable** objects in PowerShell. -Beginning in PowerShell 3.0, you can use the `[ordered]` attribute to create an -`[System.Collections.Specialized.OrderedDictionary]` object in PowerShell. +Beginning in PowerShell 3.0, you can use the `[ordered]` type accelerator to +create an `[System.Collections.Specialized.OrderedDictionary]` object in +PowerShell. Ordered dictionaries differ from hashtables in that the keys always appear in the order in which you list them. The order of keys in a hashtable isn't -determined. +deterministic. The keys and value in hashtables are also .NET objects. They're most often strings or integers, but they can have any object type. You can also create @@ -36,8 +36,8 @@ nested hashtables, in which the value of a key is another hashtable. Hashtables are frequently used because they're efficient for finding and retrieving data. You can use hashtables to store lists and to create calculated -properties in PowerShell. And, PowerShell has a cmdlet, -`ConvertFrom-StringData`, that converts strings to a hashtable. +properties in PowerShell. And, the `ConvertFrom-StringData` cmdlet converts +structured string data to a hashtable. ## Syntax @@ -55,8 +55,6 @@ The syntax of an ordered dictionary is as follows: The `[ordered]` type accelerator was introduced in PowerShell 3.0. -## Creating hashtables - To create a hashtable, follow these guidelines: - Begin the hashtable with an at sign (`@`). @@ -72,65 +70,87 @@ To create a hashtable, follow these guidelines: before the `@` symbol. If you place it before the variable name, the command fails. -To create an empty hashtable in the value of $hash, type: +You can use ordered dictionaries in the same way that you use hashtables. +Either type can be used as the value of parameters that take a hashtable or +dictionary (**iDictionary**) type objects. -```powershell -$hash = @{} -``` +## Creating hashtables and ordered dictionaries -You can also add keys and values to a hashtable when you create it. For -example, the following statement creates a hashtable with three keys. +Consider the following hashtable and ordered dictionary examples: ```powershell -$hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} +$hash = @{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$hash ``` -## Creating ordered dictionaries - -You can create an ordered dictionary by adding an object of the -**OrderedDictionary** type, but the easiest way to create an ordered dictionary -is use the `[ordered]` attribute. +```Output +Name Value +---- ----- +three 3 +2 two +1 one +``` -The `[ordered]` attribute is introduced in PowerShell 3.0. +As you can see, the key-value pairs in a hashtable aren't presented in the +order that they were defined. -Place the attribute immediately before the "@" symbol. +The easiest way to create an ordered dictionary is to use the `[ordered]` +attribute. Place the attribute immediately before the `@` symbol. ```powershell -$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} +$dictionary = [ordered]@{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$dictionary ``` -You can use ordered dictionaries in the same way that you use hashtables. -Either type can be used as the value of parameters that take a hashtable or -dictionary (**iDictionary**). +```Output +Name Value +---- ----- +1 one +2 two +three 3 +``` + +Unlike hashtables, ordered dictionaries maintain the order of the key-value. + +### Converting hashtables and ordered dictionaries -You can't use the `[ordered]` attribute to convert or cast a hashtable. If you -place the ordered attribute before the variable name, the command fails with -the following error message. +You can't use the `[ordered]` type accelerator to convert or cast a hashtable. +If you place the ordered attribute before the variable name, the command fails +with the following error message. ```powershell -[ordered]$hash = @{} -At line:1 char:1 -+ [ordered]$hash = @{} -+ ~~~~~~~~~~~~~~ -The ordered attribute can be specified only on a hash literal node. - + CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException - + FullyQualifiedErrorId : OrderedAttributeOnlyOnHashLiteralNode +[ordered]$orderedhash = @{} +ParserError: +Line | + 1 | [ordered]$orderedhash = @{} + | ~~~~~~~~~~~~~~ + | The ordered attribute can be specified only on a hash literal node. ``` To correct the expression, move the [ordered] attribute. ```powershell -$hash = [ordered]@{} +$orderedhash = [ordered]@{} ``` -You can cast an ordered dictionary to a hashtable, but you can't recover the -ordered attribute, even if you clear the variable and enter new values. To -re-establish the order, you must remove and recreate the variable. +You can cast an ordered dictionary to a hashtable, but you can't guarantee the +order of the members. ```powershell -[hashtable]$hash = [ordered]@{ - Number = 1; Shape = "Square"; Color = "Blue"} -$hash +[hashtable]$newhash = [ordered]@{ + Number = 1 + Shape = "Square" + Color = "Blue" +} +$newhash ``` ```Output @@ -141,84 +161,155 @@ Shape Square Number 1 ``` -## Displaying hashtables +## Hashtable and dictionary properties -To display a hashtable that's saved in a variable, type the variable name. By -default, a hashtables is displayed as a table with one column for keys and one -for values. +Hashtables and ordered dictionaries share several properties. Consider the +`$hash` and `$dictionary` variables defined in the previous examples. ```powershell -$hash +$hash | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -Name Value ----- ----- -Shape Square -Color Blue -Number 1 -``` - -hashtables have **Keys** and **Values** properties. Use dot notation to display -all the keys or all the values. - -```powershell -$hash.keys -``` + TypeName: System.Collections.Hashtable -```Output -Number -Shape -Color +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} ``` ```powershell -$hash.values +$dictionary | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -1 -Square -Blue -``` - -Each key name is also a property of the hashtable, and its value is the value -of the key name property. Use the following format to display the property -values. - -```Syntax -$hashtable. - -``` - -For example: - -```powershell -$hash.Number -1 - -$hash.Color -Blue -``` - -hashtables have a **Count** property that indicates the number of key-value -pairs in the hashtable. - -```powershell -$hash.count -3 -``` - -hashtable tables aren't arrays, so you can't use an integer as an index -into the hashtable, but you can use a key name to index into the hashtable. -If the key is a string value, enclose the key name in quotation marks. - -For example: - -```powershell -$hash["Number"] -1 -``` + TypeName: System.Collections.Specialized.OrderedDictionary + +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(int index) {get;set;}, + System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} +``` + +The most-used properties are **Count**, **Keys**, **Values**, and **Item**. + +- The **Count** property that indicates the number of key-value pairs in the + object. + +- The **Keys** property is a collection of the key names in the hashtable or + dictionary. + + ```powershell + PS> $hash.Keys + three + 2 + 1 + + PS> $dictionary.Keys + 1 + 2 + three + ``` + +- The **Values** property is a collection of the values in the hashtable or + dictionary. + + ```powershell + PS> $hash.Values + 3 + two + one + + PS> $dictionary.Values + one + two + 3 + ``` + +- The **Item** property is a parameterized property that returns the value of + the item that you specify. Hashtables use the key as the parameter to the + parameterized property, while dictionaries use the index by default. This + difference affects how you access the values for each type. + +## Accessing values + +There are two common ways to access the values in a hashtable or dictionary: +member notation or array index notation. + +- **Member notation** - Values can be accessed by using the key name as a + member property of the object. For example: + + ```powershell + PS> $hash.1 + one + + PS> $dictionary.2 + two + ``` + +- **Array index notation** - Values can be accessed by using index notation. + PowerShell converts that notation into a call to **Item** parameterized + property of the object. + + When you use index notation with hashtables, the value inside of the brackets + is the key name. If the key is a string value, enclose the key name in + quotes. For example: + + ```powershell + PS> $hash['three'] + 3 + + PS> $hash[2] + 2 + ``` + + In this example, the key value `2` isn't an index into the collection of + values. It's the value of the key in the key-value pair. You can prove this + by indexing into the collection of values. + + ```powershell + PS> ([array]$hash.Values)[2] + one + ``` + + When you use index notation with dictionaries, the value inside of the + brackets is interpreted based on its type. If the value is an integer, it's + treated as an index into the collection of values. If the value isn't an + integer, it's treated as the key name. For example: + + ```powershell + PS> $dictionary[1] + two + PS> ([array]$dictionary.Values)[1] + two + PS> $dictionary[[object]1] + one + PS> $dictionary['three'] + 3 + ``` + + In this example, the array value `[1]` is an index into the collection of + values using the `Item(int index)` parameterized property overload. The array + value `[[object]1]` isn't an index but a key value using the + `Item(System.Object key)` overload. + + > [!NOTE] + > This behavior can be confusing when the key value is an integer. When + > possible, you should avoid using integer key values in dictionaries. ### Handling property name collisions @@ -231,7 +322,7 @@ to return the collection of the **HashTable** keys, use this syntax: $hashtable.psbase.Keys ``` -This applies for other types which implement the +This requirement applies for other types that implement the **System.Collections.IDictionary** interface, like **OrderedDictionary**. ## Iterating over keys and values @@ -245,10 +336,9 @@ $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` > [!NOTE] -> In these examples, `$hash` is defined as an -> [ordered dictionary](#creating-ordered-dictionaries) to ensure the output is -> always in the same order. These examples work the same for normal hashtables, -> but the order of the output isn't predictable. +> In these examples, `$hash` is defined as an ordered dictionary to ensure the +> output is always in the same order. These examples work the same for standard +> hashtables, but the order of the output isn't predictable. Each example returns a message for every key and its value: @@ -258,7 +348,7 @@ The value of 'Shape' is: Square The value of 'Color' is: Blue ``` -This example uses a **foreach** block to iterate over the keys. +This example uses a `foreach` block to iterate over the keys. ```powershell foreach ($Key in $hash.Keys) { @@ -274,7 +364,7 @@ $hash.Keys | ForEach-Object { } ``` -This example uses the **GetEnumerator** method to send each key-value pair +This example uses the `GetEnumerator()` method to send each key-value pair through the pipeline to `ForEach-Object`. ```powershell @@ -283,7 +373,7 @@ $hash.GetEnumerator() | ForEach-Object { } ``` -This example uses the **GetEnumerator** and **ForEach** methods to iterate over +This example uses the `GetEnumerator()` and `ForEach()` methods to iterate over each key-value pair. ```powershell @@ -292,21 +382,23 @@ $hash.GetEnumerator().ForEach({"The value of '$($_.Key)' is: $($_.Value)"}) ## Adding and Removing Keys and Values -To add keys and values to a hashtable, use the following command format. +Typically, when you create a hashtable you include the key-value pairs in the +definition. However, you can add and remove key-value pairs from a hashtable at +any time. The following example creates an empty hashtable. ```powershell -$hash[""] = "" +$hash = @{} ``` -For example, to add a "Time" key with a value of "Now" to the hashtable, use -the following statement format. +You can add key-value pairs using array notation. For example, the following +example adds a `Time` key with a value of `Now` to the hashtable. ```powershell $hash["Time"] = "Now" ``` -You can also add keys and values to a hashtable using the `Add` method of the -**System.Collections.Hashtable** object. The `Add` method has the following +You can also add keys and values to a hashtable using the `Add()` method of the +**System.Collections.Hashtable** object. The `Add()` method has the following syntax: ```powershell @@ -339,27 +431,19 @@ $hash.Add($t, $now) ``` You can't use a subtraction operator to remove a key-value pair from a hash -table, but you can use the Remove method of the Hashtable object. The Remove -method takes the key as its value. - -The `Remove` method has the following syntax: +table, but you can use the `Remove()` method of the hashtable object. The +`Remove` method has the following syntax: ``` -Remove(Key) +$object.Remove() ``` -For example, to remove the `Time=Now` key-value pair from the hashtable in the -value of the `$hash` variable, type: +The following example removes the `Time` key-value pair from `$hash`. ```powershell $hash.Remove("Time") ``` -You can use all of the properties and methods of Hashtable objects in -PowerShell, including `Contains`, `Clear`, `Clone`, and `CopyTo`. For more -information about Hashtable objects, see -[System.Collections.Hashtable](/dotnet/api/system.collections.hashtable). - ## Object Types in HashTables The keys and values in a hashtable can have any .NET object type, and a single @@ -472,8 +556,8 @@ PS> $p.Hash2.b The items in a hashtable are intrinsically unordered. The key-value pairs might appear in a different order each time that you display them. -Although you can't sort a hashtable, you can use the GetEnumerator method of -hashtables to enumerate the keys and values, and then use the `Sort-Object` +Although you can't sort a hashtable, you can use the `GetEnumerator()` method +of hashtables to enumerate the keys and values, and then use the `Sort-Object` cmdlet to sort the enumerated values for display. For example, the following commands enumerate the keys and values in the hash diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 91449c0bcaf4..951e1613bb53 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 03/20/2024 +ms.date: 09/04/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Quoting_Rules @@ -13,6 +13,13 @@ Describes rules for using single and double quotation marks in PowerShell. ## Long description +When parsing, PowerShell first looks to interpret input as an expression. But +when a command invocation is encountered, parsing continues in argument mode. +Non-numeric arguments without quotes are treated as strings. If you have +arguments that contain spaces, such as paths, then you must enclose those +argument values in quotes. For more information about argument parsing, see the +**Argument mode** section of [about_Parsing][01]. + Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (`'`) or double quotation marks (`"`). @@ -427,12 +434,11 @@ For more information about this behavior, see the [about_Parsing][02] article. ## See also -- [about_Parsing][01] - [about_Special_Characters][04] - [ConvertFrom-StringData][05] -[01]: about_Parsing.md +[01]: about_Parsing.md#argument-mode [02]: about_Parsing.md#passing-arguments-that-contain-quote-characters [03]: about_preference_variables.md#ofs [04]: about_Special_Characters.md diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index b71bc13b77d7..482f17f54ab9 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,7 +1,7 @@ --- description: Describes how to create, use, and sort hashtables in PowerShell. Locale: en-US -ms.date: 11/15/2023 +ms.date: 09/04/2024 no-loc: [iDictionary, Hashtable, OrderedDictionary, System.Collections.IDictionary, System.Collections.Hashtable] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_hash_tables?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -19,16 +19,16 @@ structure that stores one or more key-value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In PowerShell, each hashtable is a **Hashtable** -`[System.Collections.Hashtable]` object. You can use the properties and methods -of **Hashtable** objects in PowerShell. +In PowerShell, each hashtable is a `[System.Collections.Hashtable]` object. You +can use the properties and methods of **Hashtable** objects in PowerShell. -Beginning in PowerShell 3.0, you can use the `[ordered]` attribute to create an -`[System.Collections.Specialized.OrderedDictionary]` object in PowerShell. +Beginning in PowerShell 3.0, you can use the `[ordered]` type accelerator to +create an `[System.Collections.Specialized.OrderedDictionary]` object in +PowerShell. Ordered dictionaries differ from hashtables in that the keys always appear in the order in which you list them. The order of keys in a hashtable isn't -determined. +deterministic. The keys and value in hashtables are also .NET objects. They're most often strings or integers, but they can have any object type. You can also create @@ -36,8 +36,8 @@ nested hashtables, in which the value of a key is another hashtable. Hashtables are frequently used because they're efficient for finding and retrieving data. You can use hashtables to store lists and to create calculated -properties in PowerShell. And, PowerShell has a cmdlet, -`ConvertFrom-StringData`, that converts strings to a hashtable. +properties in PowerShell. And, the `ConvertFrom-StringData` cmdlet converts +structured string data to a hashtable. ## Syntax @@ -55,8 +55,6 @@ The syntax of an ordered dictionary is as follows: The `[ordered]` type accelerator was introduced in PowerShell 3.0. -## Creating hashtables - To create a hashtable, follow these guidelines: - Begin the hashtable with an at sign (`@`). @@ -72,46 +70,67 @@ To create a hashtable, follow these guidelines: before the `@` symbol. If you place it before the variable name, the command fails. -To create an empty hashtable in the value of $hash, type: +You can use ordered dictionaries in the same way that you use hashtables. +Either type can be used as the value of parameters that take a hashtable or +dictionary (**iDictionary**) type objects. -```powershell -$hash = @{} -``` +## Creating hashtables and ordered dictionaries -You can also add keys and values to a hashtable when you create it. For -example, the following statement creates a hashtable with three keys. +Consider the following hashtable and ordered dictionary examples: ```powershell -$hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} +$hash = @{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$hash ``` -## Creating ordered dictionaries - -You can create an ordered dictionary by adding an object of the -**OrderedDictionary** type, but the easiest way to create an ordered dictionary -is use the `[ordered]` attribute. +```Output +Name Value +---- ----- +three 3 +2 two +1 one +``` -The `[ordered]` attribute is introduced in PowerShell 3.0. +As you can see, the key-value pairs in a hashtable aren't presented in the +order that they were defined. -Place the attribute immediately before the "@" symbol. +The easiest way to create an ordered dictionary is to use the `[ordered]` +attribute. Place the attribute immediately before the `@` symbol. ```powershell -$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} +$dictionary = [ordered]@{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$dictionary ``` -You can use ordered dictionaries in the same way that you use hashtables. -Either type can be used as the value of parameters that take a hashtable or -dictionary (**iDictionary**). +```Output +Name Value +---- ----- +1 one +2 two +three 3 +``` + +Unlike hashtables, ordered dictionaries maintain the order of the key-value. + +### Converting hashtables and ordered dictionaries -You can't use the `[ordered]` attribute to convert or cast a hashtable. If you -place the ordered attribute before the variable name, the command fails with -the following error message. +You can't use the `[ordered]` type accelerator to convert or cast a hashtable. +If you place the ordered attribute before the variable name, the command fails +with the following error message. ```powershell -[ordered]$hash = @{} +[ordered]$orderedhash = @{} ParserError: Line | - 1 | [ordered]$hash = @{} + 1 | [ordered]$orderedhash = @{} | ~~~~~~~~~~~~~~ | The ordered attribute can be specified only on a hash literal node. ``` @@ -119,17 +138,19 @@ Line | To correct the expression, move the [ordered] attribute. ```powershell -$hash = [ordered]@{} +$orderedhash = [ordered]@{} ``` -You can cast an ordered dictionary to a hashtable, but you can't recover the -ordered attribute, even if you clear the variable and enter new values. To -re-establish the order, you must remove and recreate the variable. +You can cast an ordered dictionary to a hashtable, but you can't guarantee the +order of the members. ```powershell -[hashtable]$hash = [ordered]@{ - Number = 1; Shape = "Square"; Color = "Blue"} -$hash +[hashtable]$newhash = [ordered]@{ + Number = 1 + Shape = "Square" + Color = "Blue" +} +$newhash ``` ```Output @@ -140,84 +161,155 @@ Shape Square Number 1 ``` -## Displaying hashtables +## Hashtable and dictionary properties -To display a hashtable that's saved in a variable, type the variable name. By -default, a hashtables is displayed as a table with one column for keys and one -for values. +Hashtables and ordered dictionaries share several properties. Consider the +`$hash` and `$dictionary` variables defined in the previous examples. ```powershell -$hash +$hash | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -Name Value ----- ----- -Shape Square -Color Blue -Number 1 -``` - -hashtables have **Keys** and **Values** properties. Use dot notation to display -all the keys or all the values. - -```powershell -$hash.keys -``` + TypeName: System.Collections.Hashtable -```Output -Number -Shape -Color +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} ``` ```powershell -$hash.values +$dictionary | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -1 -Square -Blue -``` - -Each key name is also a property of the hashtable, and its value is the value -of the key name property. Use the following format to display the property -values. - -```Syntax -$hashtable. - -``` - -For example: - -```powershell -$hash.Number -1 - -$hash.Color -Blue -``` - -hashtables have a **Count** property that indicates the number of key-value -pairs in the hashtable. - -```powershell -$hash.count -3 -``` - -hashtable tables aren't arrays, so you can't use an integer as an index -into the hashtable, but you can use a key name to index into the hashtable. -If the key is a string value, enclose the key name in quotation marks. - -For example: - -```powershell -$hash["Number"] -1 -``` + TypeName: System.Collections.Specialized.OrderedDictionary + +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(int index) {get;set;}, + System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} +``` + +The most-used properties are **Count**, **Keys**, **Values**, and **Item**. + +- The **Count** property that indicates the number of key-value pairs in the + object. + +- The **Keys** property is a collection of the key names in the hashtable or + dictionary. + + ```powershell + PS> $hash.Keys + three + 2 + 1 + + PS> $dictionary.Keys + 1 + 2 + three + ``` + +- The **Values** property is a collection of the values in the hashtable or + dictionary. + + ```powershell + PS> $hash.Values + 3 + two + one + + PS> $dictionary.Values + one + two + 3 + ``` + +- The **Item** property is a parameterized property that returns the value of + the item that you specify. Hashtables use the key as the parameter to the + parameterized property, while dictionaries use the index by default. This + difference affects how you access the values for each type. + +## Accessing values + +There are two common ways to access the values in a hashtable or dictionary: +member notation or array index notation. + +- **Member notation** - Values can be accessed by using the key name as a + member property of the object. For example: + + ```powershell + PS> $hash.1 + one + + PS> $dictionary.2 + two + ``` + +- **Array index notation** - Values can be accessed by using index notation. + PowerShell converts that notation into a call to **Item** parameterized + property of the object. + + When you use index notation with hashtables, the value inside of the brackets + is the key name. If the key is a string value, enclose the key name in + quotes. For example: + + ```powershell + PS> $hash['three'] + 3 + + PS> $hash[2] + 2 + ``` + + In this example, the key value `2` isn't an index into the collection of + values. It's the value of the key in the key-value pair. You can prove this + by indexing into the collection of values. + + ```powershell + PS> ([array]$hash.Values)[2] + one + ``` + + When you use index notation with dictionaries, the value inside of the + brackets is interpreted based on its type. If the value is an integer, it's + treated as an index into the collection of values. If the value isn't an + integer, it's treated as the key name. For example: + + ```powershell + PS> $dictionary[1] + two + PS> ([array]$dictionary.Values)[1] + two + PS> $dictionary[[object]1] + one + PS> $dictionary['three'] + 3 + ``` + + In this example, the array value `[1]` is an index into the collection of + values using the `Item(int index)` parameterized property overload. The array + value `[[object]1]` isn't an index but a key value using the + `Item(System.Object key)` overload. + + > [!NOTE] + > This behavior can be confusing when the key value is an integer. When + > possible, you should avoid using integer key values in dictionaries. ### Handling property name collisions @@ -230,7 +322,7 @@ to return the collection of the **HashTable** keys, use this syntax: $hashtable.psbase.Keys ``` -This applies for other types which implement the +This requirement applies for other types that implement the **System.Collections.IDictionary** interface, like **OrderedDictionary**. ## Iterating over keys and values @@ -244,10 +336,9 @@ $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` > [!NOTE] -> In these examples, `$hash` is defined as an -> [ordered dictionary](#creating-ordered-dictionaries) to ensure the output is -> always in the same order. These examples work the same for normal hashtables, -> but the order of the output isn't predictable. +> In these examples, `$hash` is defined as an ordered dictionary to ensure the +> output is always in the same order. These examples work the same for standard +> hashtables, but the order of the output isn't predictable. Each example returns a message for every key and its value: @@ -257,7 +348,7 @@ The value of 'Shape' is: Square The value of 'Color' is: Blue ``` -This example uses a **foreach** block to iterate over the keys. +This example uses a `foreach` block to iterate over the keys. ```powershell foreach ($Key in $hash.Keys) { @@ -273,7 +364,7 @@ $hash.Keys | ForEach-Object { } ``` -This example uses the **GetEnumerator** method to send each key-value pair +This example uses the `GetEnumerator()` method to send each key-value pair through the pipeline to `ForEach-Object`. ```powershell @@ -282,7 +373,7 @@ $hash.GetEnumerator() | ForEach-Object { } ``` -This example uses the **GetEnumerator** and **ForEach** methods to iterate over +This example uses the `GetEnumerator()` and `ForEach()` methods to iterate over each key-value pair. ```powershell @@ -291,21 +382,23 @@ $hash.GetEnumerator().ForEach({"The value of '$($_.Key)' is: $($_.Value)"}) ## Adding and Removing Keys and Values -To add keys and values to a hashtable, use the following command format. +Typically, when you create a hashtable you include the key-value pairs in the +definition. However, you can add and remove key-value pairs from a hashtable at +any time. The following example creates an empty hashtable. ```powershell -$hash[""] = "" +$hash = @{} ``` -For example, to add a "Time" key with a value of "Now" to the hashtable, use -the following statement format. +You can add key-value pairs using array notation. For example, the following +example adds a `Time` key with a value of `Now` to the hashtable. ```powershell $hash["Time"] = "Now" ``` -You can also add keys and values to a hashtable using the `Add` method of the -**System.Collections.Hashtable** object. The `Add` method has the following +You can also add keys and values to a hashtable using the `Add()` method of the +**System.Collections.Hashtable** object. The `Add()` method has the following syntax: ```powershell @@ -338,27 +431,19 @@ $hash.Add($t, $now) ``` You can't use a subtraction operator to remove a key-value pair from a hash -table, but you can use the Remove method of the Hashtable object. The Remove -method takes the key as its value. - -The `Remove` method has the following syntax: +table, but you can use the `Remove()` method of the hashtable object. The +`Remove` method has the following syntax: ``` -Remove(Key) +$object.Remove() ``` -For example, to remove the `Time=Now` key-value pair from the hashtable in the -value of the `$hash` variable, type: +The following example removes the `Time` key-value pair from `$hash`. ```powershell $hash.Remove("Time") ``` -You can use all of the properties and methods of Hashtable objects in -PowerShell, including `Contains`, `Clear`, `Clone`, and `CopyTo`. For more -information about Hashtable objects, see -[System.Collections.Hashtable](/dotnet/api/system.collections.hashtable). - ## Object Types in HashTables The keys and values in a hashtable can have any .NET object type, and a single @@ -468,8 +553,8 @@ PS> $p.Hash2.b The items in a hashtable are intrinsically unordered. The key-value pairs might appear in a different order each time that you display them. -Although you can't sort a hashtable, you can use the GetEnumerator method of -hashtables to enumerate the keys and values, and then use the `Sort-Object` +Although you can't sort a hashtable, you can use the `GetEnumerator()` method +of hashtables to enumerate the keys and values, and then use the `Sort-Object` cmdlet to sort the enumerated values for display. For example, the following commands enumerate the keys and values in the hash diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index d557050cd04f..c4a93263182a 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 03/20/2024 +ms.date: 09/04/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Quoting_Rules @@ -13,6 +13,13 @@ Describes rules for using single and double quotation marks in PowerShell. ## Long description +When parsing, PowerShell first looks to interpret input as an expression. But +when a command invocation is encountered, parsing continues in argument mode. +Non-numeric arguments without quotes are treated as strings. If you have +arguments that contain spaces, such as paths, then you must enclose those +argument values in quotes. For more information about argument parsing, see the +**Argument mode** section of [about_Parsing][01]. + Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (`'`) or double quotation marks (`"`). @@ -427,12 +434,11 @@ For more information about this behavior, see the [about_Parsing][02] article. ## See also -- [about_Parsing][01] - [about_Special_Characters][04] - [ConvertFrom-StringData][05] -[01]: about_Parsing.md +[01]: about_Parsing.md#argument-mode [02]: about_Parsing.md#passing-arguments-that-contain-quote-characters [03]: about_preference_variables.md#ofs [04]: about_Special_Characters.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index 51dd014975de..b6723a19cae1 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,7 +1,7 @@ --- description: Describes how to create, use, and sort hashtables in PowerShell. Locale: en-US -ms.date: 11/15/2023 +ms.date: 09/04/2024 no-loc: [iDictionary, Hashtable, OrderedDictionary, System.Collections.IDictionary, System.Collections.Hashtable] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_hash_tables?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -19,16 +19,16 @@ structure that stores one or more key-value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In PowerShell, each hashtable is a **Hashtable** -`[System.Collections.Hashtable]` object. You can use the properties and methods -of **Hashtable** objects in PowerShell. +In PowerShell, each hashtable is a `[System.Collections.Hashtable]` object. You +can use the properties and methods of **Hashtable** objects in PowerShell. -Beginning in PowerShell 3.0, you can use the `[ordered]` attribute to create an -`[System.Collections.Specialized.OrderedDictionary]` object in PowerShell. +Beginning in PowerShell 3.0, you can use the `[ordered]` type accelerator to +create an `[System.Collections.Specialized.OrderedDictionary]` object in +PowerShell. Ordered dictionaries differ from hashtables in that the keys always appear in the order in which you list them. The order of keys in a hashtable isn't -determined. +deterministic. The keys and value in hashtables are also .NET objects. They're most often strings or integers, but they can have any object type. You can also create @@ -36,8 +36,8 @@ nested hashtables, in which the value of a key is another hashtable. Hashtables are frequently used because they're efficient for finding and retrieving data. You can use hashtables to store lists and to create calculated -properties in PowerShell. And, PowerShell has a cmdlet, -`ConvertFrom-StringData`, that converts strings to a hashtable. +properties in PowerShell. And, the `ConvertFrom-StringData` cmdlet converts +structured string data to a hashtable. ## Syntax @@ -55,8 +55,6 @@ The syntax of an ordered dictionary is as follows: The `[ordered]` type accelerator was introduced in PowerShell 3.0. -## Creating hashtables - To create a hashtable, follow these guidelines: - Begin the hashtable with an at sign (`@`). @@ -72,46 +70,67 @@ To create a hashtable, follow these guidelines: before the `@` symbol. If you place it before the variable name, the command fails. -To create an empty hashtable in the value of $hash, type: +You can use ordered dictionaries in the same way that you use hashtables. +Either type can be used as the value of parameters that take a hashtable or +dictionary (**iDictionary**) type objects. -```powershell -$hash = @{} -``` +## Creating hashtables and ordered dictionaries -You can also add keys and values to a hashtable when you create it. For -example, the following statement creates a hashtable with three keys. +Consider the following hashtable and ordered dictionary examples: ```powershell -$hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} +$hash = @{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$hash ``` -## Creating ordered dictionaries - -You can create an ordered dictionary by adding an object of the -**OrderedDictionary** type, but the easiest way to create an ordered dictionary -is use the `[ordered]` attribute. +```Output +Name Value +---- ----- +three 3 +2 two +1 one +``` -The `[ordered]` attribute is introduced in PowerShell 3.0. +As you can see, the key-value pairs in a hashtable aren't presented in the +order that they were defined. -Place the attribute immediately before the "@" symbol. +The easiest way to create an ordered dictionary is to use the `[ordered]` +attribute. Place the attribute immediately before the `@` symbol. ```powershell -$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} +$dictionary = [ordered]@{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$dictionary ``` -You can use ordered dictionaries in the same way that you use hashtables. -Either type can be used as the value of parameters that take a hashtable or -dictionary (**iDictionary**). +```Output +Name Value +---- ----- +1 one +2 two +three 3 +``` + +Unlike hashtables, ordered dictionaries maintain the order of the key-value. + +### Converting hashtables and ordered dictionaries -You can't use the `[ordered]` attribute to convert or cast a hashtable. If you -place the ordered attribute before the variable name, the command fails with -the following error message. +You can't use the `[ordered]` type accelerator to convert or cast a hashtable. +If you place the ordered attribute before the variable name, the command fails +with the following error message. ```powershell -[ordered]$hash = @{} +[ordered]$orderedhash = @{} ParserError: Line | - 1 | [ordered]$hash = @{} + 1 | [ordered]$orderedhash = @{} | ~~~~~~~~~~~~~~ | The ordered attribute can be specified only on a hash literal node. ``` @@ -119,17 +138,19 @@ Line | To correct the expression, move the [ordered] attribute. ```powershell -$hash = [ordered]@{} +$orderedhash = [ordered]@{} ``` -You can cast an ordered dictionary to a hashtable, but you can't recover the -ordered attribute, even if you clear the variable and enter new values. To -re-establish the order, you must remove and recreate the variable. +You can cast an ordered dictionary to a hashtable, but you can't guarantee the +order of the members. ```powershell -[hashtable]$hash = [ordered]@{ - Number = 1; Shape = "Square"; Color = "Blue"} -$hash +[hashtable]$newhash = [ordered]@{ + Number = 1 + Shape = "Square" + Color = "Blue" +} +$newhash ``` ```Output @@ -140,84 +161,155 @@ Shape Square Number 1 ``` -## Displaying hashtables +## Hashtable and dictionary properties -To display a hashtable that's saved in a variable, type the variable name. By -default, a hashtables is displayed as a table with one column for keys and one -for values. +Hashtables and ordered dictionaries share several properties. Consider the +`$hash` and `$dictionary` variables defined in the previous examples. ```powershell -$hash +$hash | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -Name Value ----- ----- -Shape Square -Color Blue -Number 1 -``` - -hashtables have **Keys** and **Values** properties. Use dot notation to display -all the keys or all the values. - -```powershell -$hash.keys -``` + TypeName: System.Collections.Hashtable -```Output -Number -Shape -Color +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} ``` ```powershell -$hash.values +$dictionary | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -1 -Square -Blue -``` - -Each key name is also a property of the hashtable, and its value is the value -of the key name property. Use the following format to display the property -values. - -```Syntax -$hashtable. - -``` - -For example: - -```powershell -$hash.Number -1 - -$hash.Color -Blue -``` - -hashtables have a **Count** property that indicates the number of key-value -pairs in the hashtable. - -```powershell -$hash.count -3 -``` - -hashtable tables aren't arrays, so you can't use an integer as an index -into the hashtable, but you can use a key name to index into the hashtable. -If the key is a string value, enclose the key name in quotation marks. - -For example: - -```powershell -$hash["Number"] -1 -``` + TypeName: System.Collections.Specialized.OrderedDictionary + +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(int index) {get;set;}, + System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} +``` + +The most-used properties are **Count**, **Keys**, **Values**, and **Item**. + +- The **Count** property that indicates the number of key-value pairs in the + object. + +- The **Keys** property is a collection of the key names in the hashtable or + dictionary. + + ```powershell + PS> $hash.Keys + three + 2 + 1 + + PS> $dictionary.Keys + 1 + 2 + three + ``` + +- The **Values** property is a collection of the values in the hashtable or + dictionary. + + ```powershell + PS> $hash.Values + 3 + two + one + + PS> $dictionary.Values + one + two + 3 + ``` + +- The **Item** property is a parameterized property that returns the value of + the item that you specify. Hashtables use the key as the parameter to the + parameterized property, while dictionaries use the index by default. This + difference affects how you access the values for each type. + +## Accessing values + +There are two common ways to access the values in a hashtable or dictionary: +member notation or array index notation. + +- **Member notation** - Values can be accessed by using the key name as a + member property of the object. For example: + + ```powershell + PS> $hash.1 + one + + PS> $dictionary.2 + two + ``` + +- **Array index notation** - Values can be accessed by using index notation. + PowerShell converts that notation into a call to **Item** parameterized + property of the object. + + When you use index notation with hashtables, the value inside of the brackets + is the key name. If the key is a string value, enclose the key name in + quotes. For example: + + ```powershell + PS> $hash['three'] + 3 + + PS> $hash[2] + 2 + ``` + + In this example, the key value `2` isn't an index into the collection of + values. It's the value of the key in the key-value pair. You can prove this + by indexing into the collection of values. + + ```powershell + PS> ([array]$hash.Values)[2] + one + ``` + + When you use index notation with dictionaries, the value inside of the + brackets is interpreted based on its type. If the value is an integer, it's + treated as an index into the collection of values. If the value isn't an + integer, it's treated as the key name. For example: + + ```powershell + PS> $dictionary[1] + two + PS> ([array]$dictionary.Values)[1] + two + PS> $dictionary[[object]1] + one + PS> $dictionary['three'] + 3 + ``` + + In this example, the array value `[1]` is an index into the collection of + values using the `Item(int index)` parameterized property overload. The array + value `[[object]1]` isn't an index but a key value using the + `Item(System.Object key)` overload. + + > [!NOTE] + > This behavior can be confusing when the key value is an integer. When + > possible, you should avoid using integer key values in dictionaries. ### Handling property name collisions @@ -230,7 +322,7 @@ to return the collection of the **HashTable** keys, use this syntax: $hashtable.psbase.Keys ``` -This applies for other types which implement the +This requirement applies for other types that implement the **System.Collections.IDictionary** interface, like **OrderedDictionary**. ## Iterating over keys and values @@ -244,10 +336,9 @@ $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` > [!NOTE] -> In these examples, `$hash` is defined as an -> [ordered dictionary](#creating-ordered-dictionaries) to ensure the output is -> always in the same order. These examples work the same for normal hashtables, -> but the order of the output isn't predictable. +> In these examples, `$hash` is defined as an ordered dictionary to ensure the +> output is always in the same order. These examples work the same for standard +> hashtables, but the order of the output isn't predictable. Each example returns a message for every key and its value: @@ -257,7 +348,7 @@ The value of 'Shape' is: Square The value of 'Color' is: Blue ``` -This example uses a **foreach** block to iterate over the keys. +This example uses a `foreach` block to iterate over the keys. ```powershell foreach ($Key in $hash.Keys) { @@ -273,7 +364,7 @@ $hash.Keys | ForEach-Object { } ``` -This example uses the **GetEnumerator** method to send each key-value pair +This example uses the `GetEnumerator()` method to send each key-value pair through the pipeline to `ForEach-Object`. ```powershell @@ -282,7 +373,7 @@ $hash.GetEnumerator() | ForEach-Object { } ``` -This example uses the **GetEnumerator** and **ForEach** methods to iterate over +This example uses the `GetEnumerator()` and `ForEach()` methods to iterate over each key-value pair. ```powershell @@ -291,21 +382,23 @@ $hash.GetEnumerator().ForEach({"The value of '$($_.Key)' is: $($_.Value)"}) ## Adding and Removing Keys and Values -To add keys and values to a hashtable, use the following command format. +Typically, when you create a hashtable you include the key-value pairs in the +definition. However, you can add and remove key-value pairs from a hashtable at +any time. The following example creates an empty hashtable. ```powershell -$hash[""] = "" +$hash = @{} ``` -For example, to add a "Time" key with a value of "Now" to the hashtable, use -the following statement format. +You can add key-value pairs using array notation. For example, the following +example adds a `Time` key with a value of `Now` to the hashtable. ```powershell $hash["Time"] = "Now" ``` -You can also add keys and values to a hashtable using the `Add` method of the -**System.Collections.Hashtable** object. The `Add` method has the following +You can also add keys and values to a hashtable using the `Add()` method of the +**System.Collections.Hashtable** object. The `Add()` method has the following syntax: ```powershell @@ -338,27 +431,19 @@ $hash.Add($t, $now) ``` You can't use a subtraction operator to remove a key-value pair from a hash -table, but you can use the Remove method of the Hashtable object. The Remove -method takes the key as its value. - -The `Remove` method has the following syntax: +table, but you can use the `Remove()` method of the hashtable object. The +`Remove` method has the following syntax: ``` -Remove(Key) +$object.Remove() ``` -For example, to remove the `Time=Now` key-value pair from the hashtable in the -value of the `$hash` variable, type: +The following example removes the `Time` key-value pair from `$hash`. ```powershell $hash.Remove("Time") ``` -You can use all of the properties and methods of Hashtable objects in -PowerShell, including `Contains`, `Clear`, `Clone`, and `CopyTo`. For more -information about Hashtable objects, see -[System.Collections.Hashtable](/dotnet/api/system.collections.hashtable). - ## Object Types in HashTables The keys and values in a hashtable can have any .NET object type, and a single @@ -471,8 +556,8 @@ PS> $p.Hash2.b The items in a hashtable are intrinsically unordered. The key-value pairs might appear in a different order each time that you display them. -Although you can't sort a hashtable, you can use the GetEnumerator method of -hashtables to enumerate the keys and values, and then use the `Sort-Object` +Although you can't sort a hashtable, you can use the `GetEnumerator()` method +of hashtables to enumerate the keys and values, and then use the `Sort-Object` cmdlet to sort the enumerated values for display. For example, the following commands enumerate the keys and values in the hash diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 2e55e21378a2..507d82c437ee 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 03/20/2024 +ms.date: 09/04/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Quoting_Rules @@ -13,6 +13,13 @@ Describes rules for using single and double quotation marks in PowerShell. ## Long description +When parsing, PowerShell first looks to interpret input as an expression. But +when a command invocation is encountered, parsing continues in argument mode. +Non-numeric arguments without quotes are treated as strings. If you have +arguments that contain spaces, such as paths, then you must enclose those +argument values in quotes. For more information about argument parsing, see the +**Argument mode** section of [about_Parsing][01]. + Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (`'`) or double quotation marks (`"`). @@ -427,12 +434,11 @@ For more information about this behavior, see the [about_Parsing][02] article. ## See also -- [about_Parsing][01] - [about_Special_Characters][04] - [ConvertFrom-StringData][05] -[01]: about_Parsing.md +[01]: about_Parsing.md#argument-mode [02]: about_Parsing.md#passing-arguments-that-contain-quote-characters [03]: about_preference_variables.md#ofs [04]: about_Special_Characters.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Hash_Tables.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Hash_Tables.md index ef6fa58ba7ce..736d6e3a0483 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Hash_Tables.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Hash_Tables.md @@ -1,7 +1,7 @@ --- description: Describes how to create, use, and sort hashtables in PowerShell. Locale: en-US -ms.date: 11/15/2023 +ms.date: 09/04/2024 no-loc: [iDictionary, Hashtable, OrderedDictionary, System.Collections.IDictionary, System.Collections.Hashtable] online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_hash_tables?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -19,16 +19,16 @@ structure that stores one or more key-value pairs. For example, a hash table might contain a series of IP addresses and computer names, where the IP addresses are the keys and the computer names are the values, or vice versa. -In PowerShell, each hashtable is a **Hashtable** -`[System.Collections.Hashtable]` object. You can use the properties and methods -of **Hashtable** objects in PowerShell. +In PowerShell, each hashtable is a `[System.Collections.Hashtable]` object. You +can use the properties and methods of **Hashtable** objects in PowerShell. -Beginning in PowerShell 3.0, you can use the `[ordered]` attribute to create an -`[System.Collections.Specialized.OrderedDictionary]` object in PowerShell. +Beginning in PowerShell 3.0, you can use the `[ordered]` type accelerator to +create an `[System.Collections.Specialized.OrderedDictionary]` object in +PowerShell. Ordered dictionaries differ from hashtables in that the keys always appear in the order in which you list them. The order of keys in a hashtable isn't -determined. +deterministic. The keys and value in hashtables are also .NET objects. They're most often strings or integers, but they can have any object type. You can also create @@ -36,8 +36,8 @@ nested hashtables, in which the value of a key is another hashtable. Hashtables are frequently used because they're efficient for finding and retrieving data. You can use hashtables to store lists and to create calculated -properties in PowerShell. And, PowerShell has a cmdlet, -`ConvertFrom-StringData`, that converts strings to a hashtable. +properties in PowerShell. And, the `ConvertFrom-StringData` cmdlet converts +structured string data to a hashtable. ## Syntax @@ -55,8 +55,6 @@ The syntax of an ordered dictionary is as follows: The `[ordered]` type accelerator was introduced in PowerShell 3.0. -## Creating hashtables - To create a hashtable, follow these guidelines: - Begin the hashtable with an at sign (`@`). @@ -72,46 +70,67 @@ To create a hashtable, follow these guidelines: before the `@` symbol. If you place it before the variable name, the command fails. -To create an empty hashtable in the value of $hash, type: +You can use ordered dictionaries in the same way that you use hashtables. +Either type can be used as the value of parameters that take a hashtable or +dictionary (**iDictionary**) type objects. -```powershell -$hash = @{} -``` +## Creating hashtables and ordered dictionaries -You can also add keys and values to a hashtable when you create it. For -example, the following statement creates a hashtable with three keys. +Consider the following hashtable and ordered dictionary examples: ```powershell -$hash = @{ Number = 1; Shape = "Square"; Color = "Blue"} +$hash = @{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$hash ``` -## Creating ordered dictionaries - -You can create an ordered dictionary by adding an object of the -**OrderedDictionary** type, but the easiest way to create an ordered dictionary -is use the `[ordered]` attribute. +```Output +Name Value +---- ----- +three 3 +2 two +1 one +``` -The `[ordered]` attribute is introduced in PowerShell 3.0. +As you can see, the key-value pairs in a hashtable aren't presented in the +order that they were defined. -Place the attribute immediately before the "@" symbol. +The easiest way to create an ordered dictionary is to use the `[ordered]` +attribute. Place the attribute immediately before the `@` symbol. ```powershell -$hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} +$dictionary = [ordered]@{ + 1 = 'one' + 2 = 'two' + 'three' = 3 +} +$dictionary ``` -You can use ordered dictionaries in the same way that you use hashtables. -Either type can be used as the value of parameters that take a hashtable or -dictionary (**iDictionary**). +```Output +Name Value +---- ----- +1 one +2 two +three 3 +``` + +Unlike hashtables, ordered dictionaries maintain the order of the key-value. + +### Converting hashtables and ordered dictionaries -You can't use the `[ordered]` attribute to convert or cast a hashtable. If you -place the ordered attribute before the variable name, the command fails with -the following error message. +You can't use the `[ordered]` type accelerator to convert or cast a hashtable. +If you place the ordered attribute before the variable name, the command fails +with the following error message. ```powershell -[ordered]$hash = @{} +[ordered]$orderedhash = @{} ParserError: Line | - 1 | [ordered]$hash = @{} + 1 | [ordered]$orderedhash = @{} | ~~~~~~~~~~~~~~ | The ordered attribute can be specified only on a hash literal node. ``` @@ -119,17 +138,19 @@ Line | To correct the expression, move the [ordered] attribute. ```powershell -$hash = [ordered]@{} +$orderedhash = [ordered]@{} ``` -You can cast an ordered dictionary to a hashtable, but you can't recover the -ordered attribute, even if you clear the variable and enter new values. To -re-establish the order, you must remove and recreate the variable. +You can cast an ordered dictionary to a hashtable, but you can't guarantee the +order of the members. ```powershell -[hashtable]$hash = [ordered]@{ - Number = 1; Shape = "Square"; Color = "Blue"} -$hash +[hashtable]$newhash = [ordered]@{ + Number = 1 + Shape = "Square" + Color = "Blue" +} +$newhash ``` ```Output @@ -140,84 +161,155 @@ Shape Square Number 1 ``` -## Displaying hashtables +## Hashtable and dictionary properties -To display a hashtable that's saved in a variable, type the variable name. By -default, a hashtables is displayed as a table with one column for keys and one -for values. +Hashtables and ordered dictionaries share several properties. Consider the +`$hash` and `$dictionary` variables defined in the previous examples. ```powershell -$hash +$hash | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -Name Value ----- ----- -Shape Square -Color Blue -Number 1 -``` - -hashtables have **Keys** and **Values** properties. Use dot notation to display -all the keys or all the values. - -```powershell -$hash.keys -``` + TypeName: System.Collections.Hashtable -```Output -Number -Shape -Color +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} ``` ```powershell -$hash.values +$dictionary | Get-Member -MemberType Properties, ParameterizedProperty ``` ```Output -1 -Square -Blue -``` - -Each key name is also a property of the hashtable, and its value is the value -of the key name property. Use the following format to display the property -values. - -```Syntax -$hashtable. - -``` - -For example: - -```powershell -$hash.Number -1 - -$hash.Color -Blue -``` - -hashtables have a **Count** property that indicates the number of key-value -pairs in the hashtable. - -```powershell -$hash.count -3 -``` - -hashtable tables aren't arrays, so you can't use an integer as an index -into the hashtable, but you can use a key name to index into the hashtable. -If the key is a string value, enclose the key name in quotation marks. - -For example: - -```powershell -$hash["Number"] -1 -``` + TypeName: System.Collections.Specialized.OrderedDictionary + +Name MemberType Definition +---- ---------- ---------- +Item ParameterizedProperty System.Object Item(int index) {get;set;}, + System.Object Item(System.Object key) {get;set;} +Count Property int Count {get;} +IsFixedSize Property bool IsFixedSize {get;} +IsReadOnly Property bool IsReadOnly {get;} +IsSynchronized Property bool IsSynchronized {get;} +Keys Property System.Collections.ICollection Keys {get;} +SyncRoot Property System.Object SyncRoot {get;} +Values Property System.Collections.ICollection Values {get;} +``` + +The most-used properties are **Count**, **Keys**, **Values**, and **Item**. + +- The **Count** property that indicates the number of key-value pairs in the + object. + +- The **Keys** property is a collection of the key names in the hashtable or + dictionary. + + ```powershell + PS> $hash.Keys + three + 2 + 1 + + PS> $dictionary.Keys + 1 + 2 + three + ``` + +- The **Values** property is a collection of the values in the hashtable or + dictionary. + + ```powershell + PS> $hash.Values + 3 + two + one + + PS> $dictionary.Values + one + two + 3 + ``` + +- The **Item** property is a parameterized property that returns the value of + the item that you specify. Hashtables use the key as the parameter to the + parameterized property, while dictionaries use the index by default. This + difference affects how you access the values for each type. + +## Accessing values + +There are two common ways to access the values in a hashtable or dictionary: +member notation or array index notation. + +- **Member notation** - Values can be accessed by using the key name as a + member property of the object. For example: + + ```powershell + PS> $hash.1 + one + + PS> $dictionary.2 + two + ``` + +- **Array index notation** - Values can be accessed by using index notation. + PowerShell converts that notation into a call to **Item** parameterized + property of the object. + + When you use index notation with hashtables, the value inside of the brackets + is the key name. If the key is a string value, enclose the key name in + quotes. For example: + + ```powershell + PS> $hash['three'] + 3 + + PS> $hash[2] + 2 + ``` + + In this example, the key value `2` isn't an index into the collection of + values. It's the value of the key in the key-value pair. You can prove this + by indexing into the collection of values. + + ```powershell + PS> ([array]$hash.Values)[2] + one + ``` + + When you use index notation with dictionaries, the value inside of the + brackets is interpreted based on its type. If the value is an integer, it's + treated as an index into the collection of values. If the value isn't an + integer, it's treated as the key name. For example: + + ```powershell + PS> $dictionary[1] + two + PS> ([array]$dictionary.Values)[1] + two + PS> $dictionary[[object]1] + one + PS> $dictionary['three'] + 3 + ``` + + In this example, the array value `[1]` is an index into the collection of + values using the `Item(int index)` parameterized property overload. The array + value `[[object]1]` isn't an index but a key value using the + `Item(System.Object key)` overload. + + > [!NOTE] + > This behavior can be confusing when the key value is an integer. When + > possible, you should avoid using integer key values in dictionaries. ### Handling property name collisions @@ -230,7 +322,7 @@ to return the collection of the **HashTable** keys, use this syntax: $hashtable.psbase.Keys ``` -This applies for other types which implement the +This requirement applies for other types that implement the **System.Collections.IDictionary** interface, like **OrderedDictionary**. ## Iterating over keys and values @@ -244,10 +336,9 @@ $hash = [ordered]@{ Number = 1; Shape = "Square"; Color = "Blue"} ``` > [!NOTE] -> In these examples, `$hash` is defined as an -> [ordered dictionary](#creating-ordered-dictionaries) to ensure the output is -> always in the same order. These examples work the same for normal hashtables, -> but the order of the output isn't predictable. +> In these examples, `$hash` is defined as an ordered dictionary to ensure the +> output is always in the same order. These examples work the same for standard +> hashtables, but the order of the output isn't predictable. Each example returns a message for every key and its value: @@ -257,7 +348,7 @@ The value of 'Shape' is: Square The value of 'Color' is: Blue ``` -This example uses a **foreach** block to iterate over the keys. +This example uses a `foreach` block to iterate over the keys. ```powershell foreach ($Key in $hash.Keys) { @@ -273,7 +364,7 @@ $hash.Keys | ForEach-Object { } ``` -This example uses the **GetEnumerator** method to send each key-value pair +This example uses the `GetEnumerator()` method to send each key-value pair through the pipeline to `ForEach-Object`. ```powershell @@ -282,7 +373,7 @@ $hash.GetEnumerator() | ForEach-Object { } ``` -This example uses the **GetEnumerator** and **ForEach** methods to iterate over +This example uses the `GetEnumerator()` and `ForEach()` methods to iterate over each key-value pair. ```powershell @@ -291,21 +382,23 @@ $hash.GetEnumerator().ForEach({"The value of '$($_.Key)' is: $($_.Value)"}) ## Adding and Removing Keys and Values -To add keys and values to a hashtable, use the following command format. +Typically, when you create a hashtable you include the key-value pairs in the +definition. However, you can add and remove key-value pairs from a hashtable at +any time. The following example creates an empty hashtable. ```powershell -$hash[""] = "" +$hash = @{} ``` -For example, to add a "Time" key with a value of "Now" to the hashtable, use -the following statement format. +You can add key-value pairs using array notation. For example, the following +example adds a `Time` key with a value of `Now` to the hashtable. ```powershell $hash["Time"] = "Now" ``` -You can also add keys and values to a hashtable using the `Add` method of the -**System.Collections.Hashtable** object. The `Add` method has the following +You can also add keys and values to a hashtable using the `Add()` method of the +**System.Collections.Hashtable** object. The `Add()` method has the following syntax: ```powershell @@ -338,27 +431,19 @@ $hash.Add($t, $now) ``` You can't use a subtraction operator to remove a key-value pair from a hash -table, but you can use the Remove method of the Hashtable object. The Remove -method takes the key as its value. - -The `Remove` method has the following syntax: +table, but you can use the `Remove()` method of the hashtable object. The +`Remove` method has the following syntax: ``` -Remove(Key) +$object.Remove() ``` -For example, to remove the `Time=Now` key-value pair from the hashtable in the -value of the `$hash` variable, type: +The following example removes the `Time` key-value pair from `$hash`. ```powershell $hash.Remove("Time") ``` -You can use all of the properties and methods of Hashtable objects in -PowerShell, including `Contains`, `Clear`, `Clone`, and `CopyTo`. For more -information about Hashtable objects, see -[System.Collections.Hashtable](/dotnet/api/system.collections.hashtable). - ## Object Types in HashTables The keys and values in a hashtable can have any .NET object type, and a single @@ -471,8 +556,8 @@ PS> $p.Hash2.b The items in a hashtable are intrinsically unordered. The key-value pairs might appear in a different order each time that you display them. -Although you can't sort a hashtable, you can use the GetEnumerator method of -hashtables to enumerate the keys and values, and then use the `Sort-Object` +Although you can't sort a hashtable, you can use the `GetEnumerator()` method +of hashtables to enumerate the keys and values, and then use the `Sort-Object` cmdlet to sort the enumerated values for display. For example, the following commands enumerate the keys and values in the hash diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 96b2807c6ec8..5ff5c0440b61 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 03/20/2024 +ms.date: 09/04/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Quoting_Rules @@ -13,6 +13,13 @@ Describes rules for using single and double quotation marks in PowerShell. ## Long description +When parsing, PowerShell first looks to interpret input as an expression. But +when a command invocation is encountered, parsing continues in argument mode. +Non-numeric arguments without quotes are treated as strings. If you have +arguments that contain spaces, such as paths, then you must enclose those +argument values in quotes. For more information about argument parsing, see the +**Argument mode** section of [about_Parsing][01]. + Quotation marks are used to specify a literal string. You can enclose a string in single quotation marks (`'`) or double quotation marks (`"`). @@ -427,12 +434,11 @@ For more information about this behavior, see the [about_Parsing][02] article. ## See also -- [about_Parsing][01] - [about_Special_Characters][04] - [ConvertFrom-StringData][05] -[01]: about_Parsing.md +[01]: about_Parsing.md#argument-mode [02]: about_Parsing.md#passing-arguments-that-contain-quote-characters [03]: about_preference_variables.md#ofs [04]: about_Special_Characters.md diff --git a/reference/docs-conceptual/learn/shell/creating-profiles.md b/reference/docs-conceptual/learn/shell/creating-profiles.md index 29272da9204f..bae3fc5b9d5e 100644 --- a/reference/docs-conceptual/learn/shell/creating-profiles.md +++ b/reference/docs-conceptual/learn/shell/creating-profiles.md @@ -2,7 +2,7 @@ description: > This article explains how to use your profile to save preferred PowerShell settings and optimize your shell experience. -ms.date: 12/01/2022 +ms.date: 09/04/2024 title: Customizing your shell environment --- # Customizing your shell environment @@ -109,12 +109,13 @@ function prompt { $principal = [Security.Principal.WindowsPrincipal] $identity $adminRole = [Security.Principal.WindowsBuiltInRole]::Administrator - $prefix = $(if (Test-Path variable:/PSDebugContext) { '[DBG]: ' } - elseif ($principal.IsInRole($adminRole)) { "[ADMIN]: " } - else { '' }) - $body = 'PS ' + $(Get-Location) + $prefix = if (Test-Path variable:/PSDebugContext) { '[DBG]: ' } else { '' } + if ($principal.IsInRole($adminRole)) { + $prefix = "[ADMIN]:$prefix" + } + $body = 'PS ' + $PWD.path $suffix = $(if ($NestedPromptLevel -ge 1) { '>>' }) + '> ' - $prefix + $body + $suffix + "${prefix}${body}${suffix}" } ## Create $PSStyle if running on a version older than 7.2