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 4c76dd96dd27..9a8bf5b134fa 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/28/2024 +ms.date: 02/19/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 @@ -19,20 +19,19 @@ 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 is simpler. The `switch` +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. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression 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 is not recognized as a number is treated as a string. +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. -It is important to understand that the `` value is on the +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](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[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 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 3b2ae06239d7..353b823c9068 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/28/2024 +ms.date: 02/19/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 @@ -19,20 +19,19 @@ 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 is simpler. The `switch` +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. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression 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 is not recognized as a number is treated as a string. +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. -It is important to understand that the `` value is on the +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](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[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 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 e34c39f84a76..e2fee3aed9c3 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/28/2024 +ms.date: 02/19/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 @@ -19,20 +19,19 @@ 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 is simpler. The `switch` +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. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression 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 is not recognized as a number is treated as a string. +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. -It is important to understand that the `` value is on the +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](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[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 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 a0d2e38624e8..e26a256d9337 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/28/2024 +ms.date: 02/19/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 @@ -19,20 +19,19 @@ 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 is simpler. The `switch` +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. The `switch` statement can use the `$_` and `$switch` automatic variables. For -more information, see -[about_Automatic_Variables](about_Automatic_Variables.md). +more information, see [about_Automatic_Variables][02]. ## Syntax A basic `switch` statement has the following format: ```Syntax -Switch () +switch () { {} {} @@ -46,23 +45,23 @@ if ( -eq ()) {} if ( -eq ()) {} ``` -The `` is single expression that is evaluated in expression +The `` is single expression that's evaluated in expression 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 is not recognized as a number is treated as a string. +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. -It is important to understand that the `` value is on the +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](about_Comparison_Operators.md) +[about_Comparison_Operators][04] The value `default` is reserved for the action used when there are no other matches. @@ -74,9 +73,9 @@ the `` statements. The complete `switch` statement syntax is as follows: ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] () -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] () { + string | number | variable | { } + { } default { } # optional } ``` @@ -84,39 +83,40 @@ switch [-regex | -wildcard | -exact] [-casesensitive] () or ```Syntax -switch [-regex | -wildcard | -exact] [-casesensitive] -file filename -{ - "string" | number | variable | { } { } +switch [-Regex | -Wildcard | -Exact] [-CaseSensitive] -File filename { + string | number | variable | { } + { } default { } # optional } ``` -If no parameters are used, `switch` behaves the same as using the **Exact** +If you don't use parameters, `switch` behaves the same as using the **Exact** parameter. It performs a case-insensitive match for the value. If the value is a collection, each element is evaluated in the order in which it appears. The `switch` statement must include at least one condition statement. -The `default` clause is triggered when the value does not match any of the -conditions. It is equivalent to an `else` clause in an `if` statement. Only one +The `default` clause is triggered when the value doesn't match any of the +conditions. It's equivalent to an `else` clause in an `if` statement. Only one `default` clause is permitted in each `switch` statement. `switch` has the following parameters: - **Wildcard** - Indicates that the condition is a wildcard string. If the - match clause is not a string, the parameter is ignored. The comparison is + match clause isn't a string, the parameter is ignored. The comparison is case-insensitive. -- **Exact** - Indicates that the match clause, if it is a string, must match - exactly. If the match clause is not a string, this parameter is ignored. The +- **Exact** - Indicates that the match clause, if it's a string, must match + exactly. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. - **CaseSensitive** - Performs a case-sensitive match. If the match clause is not a string, this parameter is ignored. -- **File**- Takes input from a file rather than a ``. If - multiple **File** parameters are included, only the last one is used. Each - line of the file is read and evaluated by the `switch` statement. The - comparison is case-insensitive. +- **File**- Takes input from a file rather than a ``. The file + is read a line at a time and evaluated by the `switch` statement. By default, + the comparison is case-insensitive. The **File** parameter only supports one + file. If multiple **File** parameters are included, only the last one is + used.For more information see [File parameter examples][01]. - **Regex** - Performs regular expression matching of the value to the - condition. If the match clause is not a string, this parameter is ignored. + condition. If the match clause isn't a string, this parameter is ignored. The comparison is case-insensitive. The `$matches` automatic variable is available for use within the matching statement block. @@ -126,44 +126,41 @@ conditions. It is equivalent to an `else` clause in an `if` statement. Only one > ignored. Multiple instances of parameters are also permitted. However, only > the last parameter listed is used. -## Examples +## Simple match examples -In the following example, the `switch` statement compares the test value, 3, to +In the following example, the `switch` statement compares the test value `3` to each of the conditions. When the test value matches the condition, the action is performed. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } } ``` ```Output -It is three. +It's three. ``` -In this simple example, the value is compared to each condition in the list, -even though there is a match for the value 3. The following `switch` statement -has two conditions for a value of 3. It demonstrates that, by default, all -conditions are tested. +In this example, the value is compared to each condition in the list. The +following `switch` statement has two conditions for a value of 3, which +demonstrates that all conditions are tested. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. Three again. ``` @@ -171,18 +168,17 @@ To direct the `switch` to stop comparing after a match, use the `break` statement. The `break` statement terminates the `switch` statement. ```powershell -switch (3) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."; Break} - 4 {"It is four."} - 3 {"Three again."} +switch (3) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three."; break } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is three. +It's three. ``` If the test value is a collection, such as an array, each item in the @@ -190,19 +186,18 @@ collection is evaluated in the order in which it appears. The following examples evaluates 4 and then 2. ```powershell -switch (4, 2) -{ - 1 {"It is one."} - 2 {"It is two."} - 3 {"It is three."} - 4 {"It is four."} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one." } + 2 { "It's two." } + 3 { "It's three." } + 4 { "It's four." } + 3 { "Three again." } } ``` ```Output -It is four. -It is two. +It's four. +It's two. ``` Any `break` statements apply to the collection, not to each value, as shown @@ -210,20 +205,21 @@ in the following example. The `switch` statement is terminated by the `break` statement in the condition of value 4. ```powershell -switch (4, 2) -{ - 1 {"It is one."; Break} - 2 {"It is two." ; Break} - 3 {"It is three." ; Break} - 4 {"It is four." ; Break} - 3 {"Three again."} +switch (4, 2) { + 1 { "It's one."; break } + 2 { "It's two." ; break } + 3 { "It's three." ; break } + 4 { "It's four." ; break } + 3 { "Three again." } } ``` ```Output -It is four. +It's four. ``` +## More complex match examples + In this example, the `switch` statement is testing for the type of the value in the hashtable. You must use and expression that returns a boolean value to select the scriptblock to execute. @@ -256,16 +252,9 @@ $test = @{ $test.ToString() -switch -Exact ($test) -{ - 'System.Collections.Hashtable' - { - 'Hashtable string coercion' - } - 'test' - { - 'Hashtable value' - } +switch -Exact ($test) { + 'System.Collections.Hashtable' { 'Hashtable string coercion' } + 'test' { 'Hashtable value' } } ``` @@ -277,13 +266,12 @@ Hashtable string coercion In this example, there is no matching case so there is no output. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } } ``` @@ -291,16 +279,13 @@ By adding the `default` clause, you can perform an action when no other conditions succeed. ```powershell -switch ("fourteen") -{ - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - Default { - "No matches" - } +switch ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } + default { "No matches" } } ``` @@ -308,19 +293,18 @@ switch ("fourteen") No matches ``` -For the word "fourteen" to match a case you must use the `-Wildcard` or +For the word `fourteen` to match a case you must use the `-Wildcard` or `-Regex` parameter. ```powershell - PS> switch -Wildcard ("fourteen") - { - 1 {"It is one."; Break} - 2 {"It is two."; Break} - 3 {"It is three."; Break} - 4 {"It is four."; Break} - "fo*" {"That's too many."} - } - ``` +switch -Wildcard ("fourteen") { + 1 { "It's one."; break } + 2 { "It's two."; break } + 3 { "It's three."; break } + 4 { "It's four."; break } + "fo*" { "That's too many." } +} +``` ```Output That's too many. @@ -330,11 +314,22 @@ The following example uses the `-Regex` parameter. ```powershell $target = 'https://bing.com' -switch -Regex ($target) -{ - '^ftp\://.*$' { "$_ is an ftp address"; Break } - '^\w+@\w+\.com|edu|org$' { "$_ is an email address"; Break } - '^(http[s]?)\://.*$' { "$_ is a web address that uses $($matches[1])"; Break } +switch -Regex ($target) { + '^ftp\://.*$' + { + "$_ is an ftp address" + break + } + '^\w+@\w+\.com|edu|org$' + { + "$_ is an email address" + break + } + '^(http[s]?)\://.*$' + { + "$_ is a web address that uses $($matches[1])" + break + } } ``` @@ -346,14 +341,9 @@ The following example demonstrates the use of script blocks as `switch` statement conditions. ```powershell -switch ("Test") -{ - {$_ -is [String]} { - "Found a string" - } - "Test" { - "This $_ executes as well" - } +switch ("Test") { + { $_ -is [String] } { "Found a string" } + "Test" { "This $_ executes as well" } } ``` @@ -369,10 +359,11 @@ the beginning of the year 2022. ```powershell switch ((Get-Date 1-Jan-2022), (Get-Date 25-Dec-2021)) { - { $_.Year -eq 2021 } { - $days = ((Get-Date 1/1/2022) - $_).Days - "There are $days days until 2022." - } + { $_.Year -eq 2021 } + { + $days = ((Get-Date 1/1/2022) - $_).Days + "There are $days days until 2022." + } { $_.Year -eq 2022 } { 'Welcome to 2022!' } } ``` @@ -385,21 +376,16 @@ The `break` keyword stops processing and exits the `switch` statement. The `continue` keyword stops processing the current value, but continues processing any subsequent values. -The following example processes an array of numbers and displays if they are +The following example processes an array of numbers and displays if they're odd or even. Negative numbers are skipped with the `continue` keyword. If a non-number is encountered, execution is terminated with the `break` keyword. ```powershell -switch (1,4,-1,3,"Hello",2,1) -{ - {$_ -lt 0} { continue } - {$_ -isnot [Int32]} { break } - {$_ % 2} { - "$_ is Odd" - } - {-not ($_ % 2)} { - "$_ is Even" - } +switch (1,4,-1,3,"Hello",2,1) { + {$_ -lt 0} { continue } + {$_ -isnot [Int32]} { break } + {$_ % 2} { "$_ is Odd" } + {-not ($_ % 2)} { "$_ is Even" } } ``` @@ -409,9 +395,66 @@ switch (1,4,-1,3,"Hello",2,1) 3 is Odd ``` +## File parameter examples + +Using the `switch` statement with the **File** parameter is an efficient way to +process large files line by line. PowerShell streams the lines of the file to +the `switch` statement. Each line is processed individually. + +You can terminate +the processing before reaching the end of the file by using the `break` keyword +in the action statement. The `switch` statement is more efficient than using +`Get-Content` to process large files line by line. + +You can combine `switch -File` with `-Wildcard` or `-Regex` for flexible and efficient line-by-line pattern matching. + +The following example reads the `README.md` in the PowerShell-Docs repository. +It outputs each line until it reaches the line that starts with `##`. + +```powershell +switch -Regex -File .\README.md { + '^##\s' { break } + default { $_; continue } +} +``` + +The `` argument is interpreted as a wildcard expression, but it must +match only one file. The following example is the same as the previous one +except it uses a wildcard in the `` argument. This example works +because the wildcard pattern matches only one file. + +```powershell +switch -Regex -File .\README.* { + '^##\s' { break } + default { $_; continue } +} +``` + +You must escape characters that can be interpreted as wildcards if you want +them to be treated as literals. + +```powershell +$file = (New-Item -Path 'Temp:\Foo[0]' -Value Foo -Force).FullName +switch -File $file { Foo { 'Foo' } } +# No files matching '...\Temp\Foo[0]' were found. + +$fileEscaped = [WildcardPattern]::Escape($file) +switch -File $fileEscaped { foo { 'Foo' } } +# Foo +``` + ## See also -- [about_Break](about_Break.md) -- [about_Continue](about_Continue.md) -- [about_If](about_If.md) -- [about_Script_Blocks](about_Script_Blocks.md) +- [about_break][03] +- [about_Continue][05] +- [about_If][06] +- [about_Script_Blocks][07] + + +[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