PowerShell Logo Small

about_Switch



This is the built-in help made by Microsoft for the document 'about_Switch', in PowerShell version 2 - as retrieved from Windows version 'Microsoft® Windows Vista™ Ultimate ' PowerShell help files on 2016-06-24.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

Search powershellhelp.space

TOPIC
about_Switch

SHORT DESCRIPTION
Explains how to use a switch to handle multiple If statements.

LONG DESCRIPTION
You use an If statement to make a decision in a script or program.
Essentially, it says; “If this condition exists, perform this action.
Otherwise do that action.” You can perform that operation as many
times as you want, but if you have a long list of conditions, an If
statement becomes unwieldy. You can combine a long list of conditions
in a switch statement. As in all branching statements, braces ({})
must enclose script blocks.

A Switch statement is, in effect, a series of If statements. It matches
the expression with each of the conditions case by case. If a match
is found, the action associated with that condition is performed. A
basic switch statement takes the following form:

PS> $a = 3
PS> switch ($a) {
1 {"It is one."}
2 {"It is two."}
3 {"It is three."}
4 {"It is four."}
}

It is three.


This simple example takes a value and compares it with each condition
in the list. The action echoes a string from the match. But, you
could have a problem if you check all of the conditions.
For example:

PS> $day = "day5"
PS> switch ($day){
day1 {"Monday"; break}
day2 {"Tuesday"; break}
day3 {"Wednesday"; break}
day4 {"Thursday"; break}
day5 {"Friday"; break}
day6 {"Saturday"; break}
day7 {"Sunday"; break}
day5 {"Too many days"; break}
}

Friday


There are two day5 conditions in the list. But, the break at the end of
each condition tells the switch to stop looking further and to perform
the action it finds. If the break statements were not there, both
day5 actions would be performed.

If the value to switch against is an array, then each element in the
array will be evaluated in order, starting at element 0 (zero). At least
one element must be present that meets at least one condition; otherwise,
an error will result. If there is more than one default clause, an
error will result.

The complete switch syntax is as follows:

switch [-regex|-wildcard|-exact][-casesensitive] ( pipeline )

or

switch [-regex|-wildcard|-exact][-casesensitive] -file filename

followed by

{
"string"|number|variable|{ expression } { statementlist }
default { statementlist }
}


By default, if no parameters are used, Switch behaves as if a case-
insensitive exact match is in effect. If "pipeline" results in an
array, each element of the array will be evaluated in ascending offset
order (starting at 0 [zero]).

At least one conditional element must be present in the Switch
codeblock, and only one default clause can be present. If more than
one default clause is present, a ParseException will be thrown.

Switch has the following parameters:

Regex Indicates that the match clause, if it is a string, is
treated as a regex string. Use of this parameter
disables Wildcard and Exact. If the match clause is not
a string, this parameter is ignored.

Wildcard Indicates that the match clause, if it is a string, is
treated as a wildcard string. Use of this
parameter disables Regex and Exact. If the match clause
is not a string, this parameter is ignored.

Exact Indicates that the match clause, if it is a string, must
match exactly. Use of this parameter disables
Wildcard and Regex. If the match clause is not a
string, this parameter is ignored.

CaseSensitive Modifies the match clause, if it is a string, to be
case-sensitive. If the match clause is not a string,
this parameter is ignored.

File Takes input from a file (or representative) rather
than a statement. If multiple File parameters are
used, the last one is used. Each line of the
file is read and passed through the switch block.

Multiple uses of Regex, Wildcard, or Exact are allowed. However, only
the last parameter used governs the behavior.

The Break keyword indicates that no more processing will occur and
that the Switch statement will exit.

The Continue keyword indicates that no processing will continue


against the current token and that the next token in the conditional will
be evaluated. If no tokens are available, the Switch statement will
exit.

The "{ expression }" block may be a code block that will be evaluated
at the time of the comparison. The current object is bound to
the $_ automatic variable and is available during the evaluation of
the expression. A comparison is considered a match if the expression
evaluates to "True". This expression is evaluated in a new scope.

The "Default" keyword within the switch statement indicates that if
no matches are found, the code block that follows the keyword will
be evaluated. Program flow will not be allowed from block to
block because the closing brace ( } ) in the compound list is an explicit
break.

If multiple matches are found, each match results in the
expression being executed. To avoid this, the Break or Continue
keywords can be used to halt further comparisons.


SEE ALSO
about_Break
about_Continue
about_If
about_Script_Blocks