diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md index 6345bdfdf2f3..38d8e8e48832 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/19/2025 +ms.date: 05/15/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -10,35 +10,34 @@ title: about_Switch ## Short description -Explains how to use a switch to handle multiple `if` statements. +Explains how to use a switch to handle multiple conditional statements. ## Long description -To check a condition in a script or function, use an `if` statement. The `if` -statement can check many types of conditions, including the value of variables -and the properties of objects. +To check a condition in a script or function, you can use an `if` statement. +The `if` statement can check many types of conditions, including the value of +variables and the properties of objects. -To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it's simpler. The `switch` -statement lists each condition and an optional action. If a condition obtains, -the action is performed. +To check multiple conditions, you can use a `switch` statement. The `switch` +statement is similar to a series of `if` statements, but it's simpler. The +`switch` statement lists each condition and an optional action. If a condition +matches, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see [about_Automatic_Variables][02]. +more information, see [about_Automatic_Variables][03]. ## Syntax A basic `switch` statement has the following format: ```Syntax -switch () -{ +switch () { {} {} } ``` -The equivalent `if` statements are: +This is similar to the following `if` statements: ```Syntax if ( -eq ()) {} @@ -50,18 +49,14 @@ mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), -variables, and scriptblocks that return a boolean value. - -Any unquoted value that's not recognized as a number is treated as a string. -To avoid confusion or unintended string conversion, you should always quote -string values. Enclose any expressions in parentheses `()`, creating -subexpressions, to ensure that the expression is evaluated correctly. +variables, and scriptblocks that return a boolean value. For an example, see +[Impact of string conversion][02] later in this article. It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators][04] +[about_Comparison_Operators][05] The value `default` is reserved for the action used when there are no other matches. @@ -218,6 +213,43 @@ switch (4, 2) { It's four. ``` +## Impact of string conversion + +Any unquoted value that's not recognized as a number is treated as a string. To +avoid unintended string conversion, use script blocks to evaluate the switch +value. + +```powershell +switch ( ([datetime]'1 Jan 1970').DayOfWeek ) { + 4 { 'The value matches a Thursday.' } + "4" { 'The numeric string matches a Thursday.' } + "Thursday" { 'The string value matches a Thursday.' } + { 4 -eq $_ } { 'The expression matches a Thursday.' } +} +``` + +The **DayOfWeek** property of the date object is an enumeration. While +enumerations can be compared to their numeric or string values, the `switch` +statement converts the value to a the string representation of the enumeration. + +```Output +The string value matches a Thursday. +The expression matches a Thursday. +``` + +This behavior is different from the behavior of the `-eq` comparison in an `if` +statement. + +```powershell +if (4 -eq ([datetime]'1 Jan 1970').DayOfWeek) { + 'The value matches a Thursday.' +} +``` + +```Output +The value matches a Thursday. +``` + ## More complex match examples In this example, the `switch` statement is testing for the type of the value in @@ -445,16 +477,17 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also -- [about_Break][03] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Break][04] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] [01]: #file-parameter-examples -[02]: about_Automatic_Variables.md -[03]: about_break.md -[04]: about_Comparison_Operators.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[02]: #impact-of-string-conversion +[03]: about_Automatic_Variables.md +[04]: about_break.md +[05]: about_Comparison_Operators.md +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md index ded64098be85..c96547076582 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/19/2025 +ms.date: 05/15/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -10,35 +10,34 @@ title: about_Switch ## Short description -Explains how to use a switch to handle multiple `if` statements. +Explains how to use a switch to handle multiple conditional statements. ## Long description -To check a condition in a script or function, use an `if` statement. The `if` -statement can check many types of conditions, including the value of variables -and the properties of objects. +To check a condition in a script or function, you can use an `if` statement. +The `if` statement can check many types of conditions, including the value of +variables and the properties of objects. -To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it's simpler. The `switch` -statement lists each condition and an optional action. If a condition obtains, -the action is performed. +To check multiple conditions, you can use a `switch` statement. The `switch` +statement is similar to a series of `if` statements, but it's simpler. The +`switch` statement lists each condition and an optional action. If a condition +matches, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see [about_Automatic_Variables][02]. +more information, see [about_Automatic_Variables][03]. ## Syntax A basic `switch` statement has the following format: ```Syntax -switch () -{ +switch () { {} {} } ``` -The equivalent `if` statements are: +This is similar to the following `if` statements: ```Syntax if ( -eq ()) {} @@ -50,18 +49,14 @@ mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), -variables, and scriptblocks that return a boolean value. - -Any unquoted value that's not recognized as a number is treated as a string. -To avoid confusion or unintended string conversion, you should always quote -string values. Enclose any expressions in parentheses `()`, creating -subexpressions, to ensure that the expression is evaluated correctly. +variables, and scriptblocks that return a boolean value. For an example, see +[Impact of string conversion][02] later in this article. It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators][04] +[about_Comparison_Operators][05] The value `default` is reserved for the action used when there are no other matches. @@ -218,6 +213,43 @@ switch (4, 2) { It's four. ``` +## Impact of string conversion + +Any unquoted value that's not recognized as a number is treated as a string. To +avoid unintended string conversion, use script blocks to evaluate the switch +value. + +```powershell +switch ( ([datetime]'1 Jan 1970').DayOfWeek ) { + 4 { 'The value matches a Thursday.' } + "4" { 'The numeric string matches a Thursday.' } + "Thursday" { 'The string value matches a Thursday.' } + { 4 -eq $_ } { 'The expression matches a Thursday.' } +} +``` + +The **DayOfWeek** property of the date object is an enumeration. While +enumerations can be compared to their numeric or string values, the `switch` +statement converts the value to a the string representation of the enumeration. + +```Output +The string value matches a Thursday. +The expression matches a Thursday. +``` + +This behavior is different from the behavior of the `-eq` comparison in an `if` +statement. + +```powershell +if (4 -eq ([datetime]'1 Jan 1970').DayOfWeek) { + 'The value matches a Thursday.' +} +``` + +```Output +The value matches a Thursday. +``` + ## More complex match examples In this example, the `switch` statement is testing for the type of the value in @@ -445,16 +477,17 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also -- [about_Break][03] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Break][04] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] [01]: #file-parameter-examples -[02]: about_Automatic_Variables.md -[03]: about_break.md -[04]: about_Comparison_Operators.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[02]: #impact-of-string-conversion +[03]: about_Automatic_Variables.md +[04]: about_break.md +[05]: about_Comparison_Operators.md +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md index 0c9b2b32d589..be911365e6ad 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/19/2025 +ms.date: 05/15/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -10,35 +10,34 @@ title: about_Switch ## Short description -Explains how to use a switch to handle multiple `if` statements. +Explains how to use a switch to handle multiple conditional statements. ## Long description -To check a condition in a script or function, use an `if` statement. The `if` -statement can check many types of conditions, including the value of variables -and the properties of objects. +To check a condition in a script or function, you can use an `if` statement. +The `if` statement can check many types of conditions, including the value of +variables and the properties of objects. -To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it's simpler. The `switch` -statement lists each condition and an optional action. If a condition obtains, -the action is performed. +To check multiple conditions, you can use a `switch` statement. The `switch` +statement is similar to a series of `if` statements, but it's simpler. The +`switch` statement lists each condition and an optional action. If a condition +matches, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see [about_Automatic_Variables][02]. +more information, see [about_Automatic_Variables][03]. ## Syntax A basic `switch` statement has the following format: ```Syntax -switch () -{ +switch () { {} {} } ``` -The equivalent `if` statements are: +This is similar to the following `if` statements: ```Syntax if ( -eq ()) {} @@ -50,18 +49,14 @@ mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), -variables, and scriptblocks that return a boolean value. - -Any unquoted value that's not recognized as a number is treated as a string. -To avoid confusion or unintended string conversion, you should always quote -string values. Enclose any expressions in parentheses `()`, creating -subexpressions, to ensure that the expression is evaluated correctly. +variables, and scriptblocks that return a boolean value. For an example, see +[Impact of string conversion][02] later in this article. It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators][04] +[about_Comparison_Operators][05] The value `default` is reserved for the action used when there are no other matches. @@ -218,6 +213,43 @@ switch (4, 2) { It's four. ``` +## Impact of string conversion + +Any unquoted value that's not recognized as a number is treated as a string. To +avoid unintended string conversion, use script blocks to evaluate the switch +value. + +```powershell +switch ( ([datetime]'1 Jan 1970').DayOfWeek ) { + 4 { 'The value matches a Thursday.' } + "4" { 'The numeric string matches a Thursday.' } + "Thursday" { 'The string value matches a Thursday.' } + { 4 -eq $_ } { 'The expression matches a Thursday.' } +} +``` + +The **DayOfWeek** property of the date object is an enumeration. While +enumerations can be compared to their numeric or string values, the `switch` +statement converts the value to a the string representation of the enumeration. + +```Output +The string value matches a Thursday. +The expression matches a Thursday. +``` + +This behavior is different from the behavior of the `-eq` comparison in an `if` +statement. + +```powershell +if (4 -eq ([datetime]'1 Jan 1970').DayOfWeek) { + 'The value matches a Thursday.' +} +``` + +```Output +The value matches a Thursday. +``` + ## More complex match examples In this example, the `switch` statement is testing for the type of the value in @@ -445,16 +477,17 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also -- [about_Break][03] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Break][04] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] [01]: #file-parameter-examples -[02]: about_Automatic_Variables.md -[03]: about_break.md -[04]: about_Comparison_Operators.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[02]: #impact-of-string-conversion +[03]: about_Automatic_Variables.md +[04]: about_break.md +[05]: about_Comparison_Operators.md +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md index 23be40d008df..04364df8762b 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Switch.md @@ -1,7 +1,7 @@ --- description: Explains how to use a switch to handle multiple `if` statements. Locale: en-US -ms.date: 02/19/2025 +ms.date: 05/15/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_switch?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Switch @@ -10,35 +10,34 @@ title: about_Switch ## Short description -Explains how to use a switch to handle multiple `if` statements. +Explains how to use a switch to handle multiple conditional statements. ## Long description -To check a condition in a script or function, use an `if` statement. The `if` -statement can check many types of conditions, including the value of variables -and the properties of objects. +To check a condition in a script or function, you can use an `if` statement. +The `if` statement can check many types of conditions, including the value of +variables and the properties of objects. -To check multiple conditions, use a `switch` statement. The `switch` statement -is equivalent to a series of `if` statements, but it's simpler. The `switch` -statement lists each condition and an optional action. If a condition obtains, -the action is performed. +To check multiple conditions, you can use a `switch` statement. The `switch` +statement is similar to a series of `if` statements, but it's simpler. The +`switch` statement lists each condition and an optional action. If a condition +matches, the action is performed. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see [about_Automatic_Variables][02]. +more information, see [about_Automatic_Variables][03]. ## Syntax A basic `switch` statement has the following format: ```Syntax -switch () -{ +switch () { {} {} } ``` -The equivalent `if` statements are: +This is similar to the following `if` statements: ```Syntax if ( -eq ()) {} @@ -50,18 +49,14 @@ mode to return a value. The `` is an expression whose value is compared to the input value. Expressions include literal values (strings or numbers), -variables, and scriptblocks that return a boolean value. - -Any unquoted value that's not recognized as a number is treated as a string. -To avoid confusion or unintended string conversion, you should always quote -string values. Enclose any expressions in parentheses `()`, creating -subexpressions, to ensure that the expression is evaluated correctly. +variables, and scriptblocks that return a boolean value. For an example, see +[Impact of string conversion][02] later in this article. It's important to understand that the `` value is on the left-hand side of the comparison expression. That means the result of the `` is on the right-hand side, which can be converted to the type of the left-hand side value for comparison. For more information, see -[about_Comparison_Operators][04] +[about_Comparison_Operators][05] The value `default` is reserved for the action used when there are no other matches. @@ -218,6 +213,43 @@ switch (4, 2) { It's four. ``` +## Impact of string conversion + +Any unquoted value that's not recognized as a number is treated as a string. To +avoid unintended string conversion, use script blocks to evaluate the switch +value. + +```powershell +switch ( ([datetime]'1 Jan 1970').DayOfWeek ) { + 4 { 'The value matches a Thursday.' } + "4" { 'The numeric string matches a Thursday.' } + "Thursday" { 'The string value matches a Thursday.' } + { 4 -eq $_ } { 'The expression matches a Thursday.' } +} +``` + +The **DayOfWeek** property of the date object is an enumeration. While +enumerations can be compared to their numeric or string values, the `switch` +statement converts the value to a the string representation of the enumeration. + +```Output +The string value matches a Thursday. +The expression matches a Thursday. +``` + +This behavior is different from the behavior of the `-eq` comparison in an `if` +statement. + +```powershell +if (4 -eq ([datetime]'1 Jan 1970').DayOfWeek) { + 'The value matches a Thursday.' +} +``` + +```Output +The value matches a Thursday. +``` + ## More complex match examples In this example, the `switch` statement is testing for the type of the value in @@ -445,16 +477,17 @@ switch -File $fileEscaped { foo { 'Foo' } } ## See also -- [about_Break][03] -- [about_Continue][05] -- [about_If][06] -- [about_Script_Blocks][07] +- [about_Break][04] +- [about_Continue][06] +- [about_If][07] +- [about_Script_Blocks][08] [01]: #file-parameter-examples -[02]: about_Automatic_Variables.md -[03]: about_break.md -[04]: about_Comparison_Operators.md -[05]: about_Continue.md -[06]: about_If.md -[07]: about_Script_Blocks.md +[02]: #impact-of-string-conversion +[03]: about_Automatic_Variables.md +[04]: about_break.md +[05]: about_Comparison_Operators.md +[06]: about_Continue.md +[07]: about_If.md +[08]: about_Script_Blocks.md