Help:Conditional expressions

Safer nicotine wiki Tobacco Harm Reduction
Jump to navigation Jump to search

This page, Help:Conditional expressions, describes ways to display different results based on checking conditions in a page or template. The parser functions used to evaluate conditional expressions include the function names: #ifexpr, #ifeq, #switch, #if, and #iferror or #ifexist. Each function name has been linked to the explanations below.

  • Using #ifeq can compare 2 strings or numbers.
  • But #ifexpr can check a math formula or multiple conditions.
  • The #switch function can branch to dozens or hundreds of different paths depending on a value, to act as a case statement to choose among alternatives.
  • Using #if can check to see if a parameter has been passed, or if an expression evaluates as true.
  • Using #iferror can check to see if an expression value triggers an error else shows the value.
  • While #ifexist can check to see if a page name or image/media file exists yet.

Note that all extra white space within the outer braces gets stripped out, so this permits formatting these constructs for better readability. For example:

{{#if: {{{xx|}}}
   | parameter xx passed
   | parameter xx omitted
}}

Only the spaces on either side of the xx appear in the text.

Summary of conditional expressions

The quick format of each function is as follows (you can see function examples bellow):

  • {{#if: test string | value if non-empty | value if empty }} (selects one of two values based on whether the test string is empty)
  • {{#ifeq: string 1 | string 2 | value if equal | value if unequal }} (selects one of two values based on whether the test strings are equal – numerically if applicable)
  • {{#iferror: test string | value if error | value if correct }} (selects value based on whether the test string generates a parser error)
  • {{#ifexpr: expression | value if true | value if false }} (selects value based on evaluation of expression)
  • {{#ifexist: page title | value if exists | value if doesn't exist }} (selects value depending on whether a page title exists)
  • {{#switch: test | case1 = value for case 1 | ... | default }} (provides alternatives based on the value of the test string; see test cases.)
  • {{#expr: expression }} (evaluates the given expression; see Help:Calculation)

The magic words can be used together, in nested combinations, to branch on complex conditions. Some combinations can use tricks based on the interactions between them.

Note that with #if expressions, using a positional parameter, this is, a parameter in the form "{{{1}}}" always requires a final vertical bar "|" in the parameter: {{{1|}}}. If the bar/pipe is omitted, then whenever the parameter 1 is absent, instead of leaving the field blank, the page will use the literal text "{{{1}}}" (as 3 sets of curly braces around a "1"), and the #if will be true unless parameter 1 is passed as an empty string, such as "1=".

Using #if

See also: {{if}}

Using #if can check whether a parameter has been passed.

This function evaluates a test string and determines whether or not it is empty. A test string containing only white space is considered to be empty.

:{{#if: test string | value if test string is not empty | value if test string is empty (or only white space) }}

Examples:

{{#if: {{{1|}}}
   | parameter 1 has data
   | parameter 1 is empty or omitted
}}

{{#if: {{{xx|}}}
   | parameter xx passed
   | parameter xx is empty or omitted
}}

{{#if: {{{xx|}}}{{{yy|}}}
   | xx and/or yy passed
   | both xx and yy are empty/omitted
}}

Using #ifeq

See also: {{ifeq}}

Using #ifeq can compare 2 strings or numbers (but not numeric expressions: 1+1). The parser function #ifeq compares two values and determines whether they are identical.

:{{#ifeq: string 1 | string 2 | value if identical | value if different }}

If both strings are valid numerical values, the strings are compared as numbers, rather than literal text:

{{#ifeq: 01 | 1 | equal | not equal}}equal
{{#ifeq: x01 | x1 | equal | not equal}}not equal
{{#ifeq: 2.000 | 002 | equal | not equal}}equal
{{#ifeq: 2.5 | 2+.5 | equal | not equal}}not equal (use #ifexpr for arithmetic)
{{#ifeq: {{#expr:10^3}} | 1000 | equal | not equal}}equal

The comparison is case-sensitive, checking to match capital letters:

{{#ifeq: King | king | equal | not equal}}not equal
{{#ifeq: {{lc:TopCat}} | topcat |equal|not equal}}equal
{{#ifeq: {{lc:{{{catname}}} }} | topcat |equal|not equal}}

So, when checking the value of a parameter named "{{{catname}}}" then the function {{lc:___}} can be used to instantly convert to lowercase text, during the comparison. The value of {{{catname}}} will not be changed for later use, instead it is only compared as lowercase letters.

{{#ifeq: {{{n}}} | 1 | singular | plural}}plural (For most languages, including English, {{Plural| lang=xx  |  {{{n}}}  |  singular  |plural }} is exactly equivalent ).

Using #ifexpr

Using #ifexpr can check a math formula or multiple conditions. The parser function #ifexpr evaluates a mathematical expression or boolean expression and branches depending on the boolean true/false value of the result (where zero means false):

:{{#ifexpr: expression | value if true | value if false }}
Examples:

{{#ifexpr: ( {{{1}}}+{{{2}}} ) * 2.63 > 45 |above 45 |not above 45}}
{{#ifexpr: {{{1}}} > 0 and {{{1}}} < 1.0 or {{#ifeq:{{{decimal}}}| yes}} |is decimal |not decimal}}

The expression result is evaluated exactly in the same manner as for function #expr, with the same operators being available. The output is then evaluated as a boolean expression.

An empty input expression evaluates to false:

{{#ifexpr: | yes | no}}no

As mentioned above, zero evaluates to false and any nonzero value (such as 6.7) evaluates to true.

Invalid data will display an error message. However, function #ifexpr is equivalent to using #ifeq with #expr inside, but flipping the true/false (then/else) clauses:

{{#ifeq: {{#expr: expression }} | 0 | value if false | value if true }}

An invalid or wrong input expression will trigger the true-value part (an error message is treated as an ordinary string; it is not equal to zero, so we get value if false).

{{#ifexpr: = | yes | no }}Expression error: Unexpected = operator
{{#ifeq: {{#expr: = }} |0 | yes | no }}no

Either or both of the return values may be omitted; no output is given when the appropriate branch is left empty:

{{#ifexpr: 1 > 0 | yes }}yes
{{#ifexpr: 0 = 0 | yes }} yes
{{#ifexpr: 1 > 0 | | no}}

Using #switch

The #switch function can branch to dozens or hundreds of different paths depending on a value, to act as a case statement which chooses among alternatives. A #switch expression is a quick way to handle multiple code values for a parameter, without using lots of #if functions; however, the performance slows when more than 100 branches, and common values should be listed higher among the choices, to run 3x-8x faster. In rare cases, a #switch could have over two thousand branches, but it takes time just to scan all the branches, even before comparing the values.

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 read the value of {{{x}}}. For a value of 1 it would return “one”. For a value of 2 it would return “two”. For the values 3, 4 or 5 it would return “range 3–5”. For any other value, or a null value, it would return “other”.

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
 | #default = other
 | 3|4|5 = any of 3–5
 | {{#expr: 2*3}} = six
 | {{#expr: 2*3+1}} = {{lc:SEVEN}} <!--lowercase-->
}}

This illustrates an alternative method of specifying the default case, which can appear first, last, or anywhere in between.

If no default is specified and no case matches the supplied value, a null value is returned.

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

See: Help:Switch parser function, for a full description and examples.

Using #iferror

Using #iferror can check to see if an expression value triggers an error, to then do something for that condition, else it shows the value which was being tested.

This function takes an input string and returns one of two results; the function evaluates to true if the input string contains an HTML object with class="error", template errors such as loops and recursions, and other "failsoft" parser errors:

{{#iferror: test string | value if error | value if correct }} (selects value based on whether the test string generates a parser error).

One or both of the return strings can be omitted. If the correct string is omitted, the test string is returned if it is not erroneous. If the error string is also omitted, an empty string is returned on an error:

{{#iferror: {{#expr: 1 + 2 }} | error | correct }}correct
{{#iferror: {{#expr: 1 + X }} | error | correct }}error
{{#iferror: {{#expr: 1 + 2 }} | error }}3
{{#iferror: {{#expr: 1 + X }} | error }}error
{{#iferror: {{#expr: 1 + 2 }} }}3
{{#iferror: {{#expr: 1 + X }} }}
{{#iferror: {{#expr: . }} | error | correct }}correct
{{#iferror: <strong class="error">a</strong> | error | correct }}error

Using #ifexist

The function #ifexist can check to see if a page name or image/media file exists yet. It is extremely fast, but has been limited to 500 instances per page.

{{#ifexist: page title | value if exists | value if doesn't exist }} (selects value depending on whether a page title exists)

The function evaluates to true if the page exists, whether it contains content, is visibly blank (contains meta-data such as category links or magic words, but no visible content), is blank, or is a redirect. Only pages that are redlinked evaluate to false, including if the page used to exist but has been deleted.

Using #expr

Using #expr can evaluate a mathematical or boolean expression, to augment the comparisons, and handle error messages.

{{#expr: expression }}

Examples:

{{#expr: ( {{{1}}}+{{{xshift}}} - 6 ) * 18.4}}
{{#expr: ln(7)^3 - abs(-0.344) + floor(5/3) round 3 }}
{{#expr: {{{n}}}>0 and {{{n}}}<1.0 }}

Conditionals for templates

To distinguish between a template parameter ( for example, {{{1}}} ) being defined and non-empty on one hand, or undefined or empty on the other hand, use #if: with a blank default:

{{ #if: {{{param|}}} | param is defined and non-empty | param is undefined or empty}}.

To distinguish between defined (and possibly empty) and undefined, use:

{{ #ifeq: {{{param|+}}} | {{{param|-}}} | param is defined | param is undefined }}.

See also