diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md index 54a67a8828d2..36d11d3d7f12 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -126,8 +128,35 @@ True > Wrapping a command in parentheses causes the automatic variable `$?` to be > set to `$true`, even when the enclosed command itself set `$?` to `$false`. > For example, `(Get-Item /Nosuch); $?` unexpectedly yields **True**. For -> more information about `$?`, see -> [about_Automatic_Variables][06]. +> more information about `$?`, see [about_Automatic_Variables][06]. + +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +For example, the outputs for these statements are different: + +```powershell +PS> ConvertFrom-Json '["a", "b"]' | ForEach-Object { "The value is '$_'" } + +The value is 'a b' + +PS> (ConvertFrom-Json '["a", "b"]') | ForEach-Object { "The value is '$_'" } + +The value is 'a' +The value is 'b' +``` + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + +For example, piping the output from `Get-ChildItem` to `Rename-Item` can have +unexpected effects where an item is renamed, then discovered again and renamed +a second time. #### Grouping assignment statements @@ -184,34 +213,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -For example, the outputs for these statements are different: - -```powershell -PS> ConvertFrom-Json '["a", "b"]' | ForEach-Object { "The value is '$_'" } - -The value is 'a b' - -PS> (ConvertFrom-Json '["a", "b"]') | ForEach-Object { "The value is '$_'" } - -The value is 'a' -The value is 'b' -``` - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - -For example, piping the output from `Get-ChildItem` to `Rename-Item` can have -unexpected effects where an item is renamed, then discovered again and renamed -a second time. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md index bc7882034d34..e556905a584e 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -122,6 +124,17 @@ PS> (Get-Item *.txt).Count -gt 10 True ``` +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + #### Grouping assignment statements Ungrouped assignment statements don't output values. When grouping an @@ -177,17 +190,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md index 131d9671c8e6..ba9967388fd0 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -122,6 +124,17 @@ PS> (Get-Item *.txt).Count -gt 10 True ``` +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + #### Grouping assignment statements Ungrouped assignment statements don't output values. When grouping an @@ -177,17 +190,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md index 52d92324609c..17769f3cc4f5 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -122,6 +124,17 @@ PS> (Get-Item *.txt).Count -gt 10 True ``` +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + #### Grouping assignment statements Ungrouped assignment statements don't output values. When grouping an @@ -177,17 +190,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a