Help:Switch parser function

Help:Switch

The switch parser function, coded as "#switch", selects the first matching branch in a list of choices, acting as a case statement. Each branch can be a value, an expression, or a template call, to match the value of the switch. Although many #switch structures are used to branch among a set of values, the branches can also include boolean expressions to act as a set of pre-conditions to be tested until one tests true, acting as an if-elseif-elseif-elseif-else structure.

A #switch can contain over 1,000 branches, but should be split to have less than 100 branches, in each of multiple or nested parts. The upper branches execute faster, and the bottom branches must wait for processing of all higher branches. Because it is a parser function, a #switch can be used inside any page, even in article text, but in most cases, a #switch is typically used inside a wp:template, to branch depending on a parameter value passed to the template.

General format

The #switch function can be a one-line form:

{{#switch: {{{x}}} |1=one |2=two |3|4|5=range 3-5 |other}}

That one-line #switch would show "range 3-5" for either value 3, 4 or 5.

However, in many cases, the #switch function is a multi-line form, with each branch on a different line, as follows:

{{#switch: {{{x}}}
| 1 = one
| 2 = two
| 3|4|5 = range 3-5
| {{#expr: 2*3}} = six
| {{#expr: 2*3+1}} = {{lc:SEVEN}} <!--lowercase-->
| other

}}

For each branch of a #switch, either side of an equals-sign "=" can be a simple value, or expression, or a template call.

Using switches as if-elseif-elseif

A #switch function can be structured as a set of pre-conditions which are tested until one is true (equal to "1"). For example to pre-screen numbers to avoid division by zero:

{{#switch: 1
| {{#expr: {{{x2}}} = 0}} = Parameter x2 is 0 - cannot divide.
| {{#expr: {{{y2}}} = 0}} = Parameter y2 is 0 - cannot divide.
| {{#expr: {{{z2}}} = 0}} = Parameter z2 is 0 - cannot divide.
| 1 = {{#expr: {{{x}}}/{{{x2}}} + {{{y}}}/{{{y2}}} + {{{z}}}/{{{z2}}} }}
}}

When testing x2, y2 and z2, if any of them is zero, then the #switch ends with a warning message, rather than calculating the weighted average of the three amounts x, y, and z. Each branch acts as a pre-condition, so the whole #switch structure performs as equivalent to if-elseif-elseif-elseif-else, even though an #if-function structure cannot have an "elseif" clause.

Another example, to test an amount "n" to determine the number of decimal digits:

{{#switch: 1
| {{#expr: floor({{{n}}}*100) <> {{{n}}}*100}} = 3
| {{#expr: floor({{{n}}}*10) <> {{{n}}}*10}} = 2
| {{#expr: floor( {{{n}}} ) <> {{{n}}} }} = 1
| {{#expr: {{{n}}} mod 1000 = 0}} = -3
| {{#expr: {{{n}}} mod 100 = 0 }} = -2
| {{#expr: {{{n}}} mod 10 = 0 }} = -1
| 1 = 0

}}

That is another example, using "#switch: 1" to stack a set of pre-conditions which are tested, in sequence, until one is true (equal to "1").

Performance considerations

A #switch can contain over 1,000-2,000 branches, but should be split to have less than 100 branches, in multiple or nested parts. In some cases, it might be possible to split into multiple #switch structures, such as when many cases use the same first letter. Then, using {{padleft:|1|{{{value}}} }} can extract the first letter of {{{value}}} to be used in a higher #switch which branches by most-frequent letter, followed by all others at the bottom or "#default" branch. Another common split might separate numeric values into frequent ranges, followed by all other.

The upper branches of a #switch execute faster, and the bottom branches must wait for processing of all higher branches. Hence, the top branch should be the most-used case, unless pre-screening of data is done in the early branches.

General format

Using switches as if-elseif-elseif

Performance considerations

See also