Help:Calculation

From Meta, a Wikimedia project coordination wiki
Jump to: navigation, search
MediaWiki Handbook: Contents, Readers, Editors, Moderators, System admins +/-
The accuracy and format of numeric results varies with the server. Currently the results produced by Wikimedia servers seem to be uniform.

The functions #expr: and #ifexpr: of MediaWiki extension ParserFunctions evaluate numerical expressions, and also boolean expressions involving numbers and booleans (not strings). The syntax is

{{ #expr: expression }}

Spaces are not needed, except between words (for operators and constants). Inside numbers no grouping separators (spaces, commas, apostrophes) are allowed, the only decimal separator supported is the period (dot, full stop, excluding commas), and currently the only supported digits are the European decimal digits 0-9.

In calculation expressions embedded within templates, be careful when using magic words for date and time elements, such as {{CURRENTHOUR}} as their return value may be formatted differently on translated pages and will break expressions (instead, use the parser function #time with the appropriate xg flags before each formatting element). Similar errors will occur with some other magic words that return quantities (make sure you include the appropriate raw formatting flag).

General[edit]

An expression is a string representing a tree structure with type/value pairs as nodes, with binary operators in infix notation, unary operators in prefix notation, and end nodes represented by numbers and constants. Letters in operators and names of constants are case-insensitive.

The ParserFunctions software determines which operators and constants, and what numbers, are supported. The e in scientific notation and the sign of a number are treated as operators, the supported literal numbers are unsigned numbers in ordinary decimal format. The ParserFunctions software also determines the precedence of the operators and the error messages, and it converts all literal numbers to type float.

For the rest the ParserFunctions software just defines the operators in terms of PHP functions and operators, and any type conversions and pecularities of the operators are properties of these PHP functions and operators themselves. Also, the format of the result is entirely determined by PHP.

The data types are the PHP data types float (double precision floating-point format) and integer (64-bit integer). The range for type integer is from -(2^63) = -9,223,372,036,854,775,808 through 2^63 - 1 = 9,223,372,036,854,775,807. Type float allows fractions and very large numbers, but only in the range -(2^53) = -9,007,199,254,740,992 through (2^53) = 9,007,199,254,740,992 all integer values can be exactly represented in type float (see Help:Calculation accuracy).

Dynamic typing is applied. The end nodes are all of type float (as mentioned, numbers are converted to float; this applies even for numbers with an integer value and format). The data type of the result of an operation depends on the operator, and for some operators on the type(s) of the argument(s), and in some cases on their value(s). If according to these rules the result is of type float, any argument of type integer is converted to float before the operation, and the result is also rounded to float:

  • {{numfh|(trunc2^trunc62+trunc512)-2^62}} → 0
  • {{numfh|(trunc2^trunc62+trunc512)+(trunc2^trunc62+trunc1535)}} → 9,223,372,036,854,776,000 (ca. 9.2e18) 1.0000000000000hex*2^63
  • {{numfh|2^63+2047}} → 9,223,372,036,854,777,600 (ca. 9.2e18) 1.0000000000001hex*2^63

Apart from that, a numerical value outside the range of type integer is converted to float, except in the case of trunc (and mod, which involves applying trunc to the arguments first).

There are 31 operators (excluding two synonyms), two constants, and the unsigned numbers in ordinary decimal notation.

Operators, numbers, and constants[edit]

Since literal numbers are of type float, trunc is sometimes used in the examples to construct an integer-type argument, to demonstrate the result of an operator for this case.

Operator Args Operation PHP Data type Prio Examples
- 1 unary - sign (negation) - same as argument &1000000000000001000000010
{{#expr:-12}} -12
{{#expr:-trunc12}} -12
{{#expr:-trunc(-2^63)}} 9.2233720368548E+18
e between subexpressions 2 *10^ * pow (10,..) float unless the factor on the left is of type integer and the exponent is non-negative and of type integer &1000000000000001000000010
{{#expr:2e3}} 2000
{{#expr:-2.3e-4}} -0.00023
{{#expr:(trunc2)e(trunc-3)}} 0.002
{{#expr:(trunc2)e(trunc0)}} 2
{{#expr:(trunc2)e(trunc18)}} 2000000000000000000
{{#expr:(trunc2)e(trunc19)}} 2.0E+19
{{#expr:6e(5-2)e-2}} 60
{{#expr:1e.5}} 3.1622776601684

Wrong:

{{#expr:e4}} Expression error: Unexpected number.
exp 1 exponential function ex exp float &100000000000000090000009
{{#expr:exp43}} 4.7278394682293E+18
{{#expr:exp trunc0}} 1
{{#expr:exp709}} 8.218407461555E+307
{{#expr:exp-744}} 9.8813129168249E-324

Compare:

{{#expr:e^43}} 4.7278394682293E+18
{{#expr:trunc exp43}} 4727839468229346304
ln 1 natural logarithm log float &100000000000000090000009
{{#expr:ln2}} 0.69314718055995
{{#expr:ln trunc1}} 0
{{#expr:ln8.9e307}} 709.07967482591
{{#expr:ln.5e-323}} -744.44007192138

Hence, the common logarithm of e.g. 2:

{{#expr:ln2/ln10}} 0.30102999566398
abs 1 absolute value abs same as argument &100000000000000090000009
{{#expr:abs-2}} 2
{{#expr:abs trunc-2}} 2
{{#expr:abs trunc-2^63}} 9.2233720368548E+18
trunc 1 truncation (int), i.e. type-casting to integer integer &100000000000000090000009
{{#expr:trunc1.2}} 1
{{#expr:trunc1.8}} 1
{{#expr:trunc-1.2}} -1
{{#expr:trunc(-2^64+1e5)}} 0
{{#expr:trunc(-2^63+1e5)}} -9223372036854675456
{{#expr:trunc(2^63)}} -9223372036854775808
{{#expr:trunc(2^63+1e5)}} -9223372036854675456
{{#expr:trunc(2^64+1e5)}} 0
floor 1 floor function floor float &100000000000000090000009
{{#expr:floor1.2}} 1
{{#expr:floor-1.2}} -2
{{#expr:floor trunc3}} 3
ceil 1 ceiling function ceil float &100000000000000090000009
{{#expr:ceil1.2}} 2
{{#expr:ceil-1.2}} -1
{{#expr:ceil trunc3}} 3
sin 1 sine sin float &100000000000000090000009
{{#expr:sin.1}} 0.099833416646828
{{#expr:sin trunc1}} 0.8414709848079

With an angle in degrees, e.g. 30°:

{{#expr:sin(30*pi/180)}} 0.5
cos 1 cosine cos float &100000000000000090000009
{{#expr:cos.1}} 0.99500416527803
{{#expr:cos trunc1}} 0.54030230586814
tan 1 tangent tan float &100000000000000090000009
{{#expr:tan.1}} 0.10033467208545
{{#expr:tan trunc1}} 1.5574077246549
asin 1 arcsine asin float &100000000000000090000009
{{#expr:asin.1}} 0.10016742116156
{{#expr:asin trunc1}} 1.5707963267949
acos 1 arccosine acos float &100000000000000090000009
{{#expr:acos.1}} 1.4706289056333
{{#expr:acos trunc1}} 0
{{#expr:2*acos 0}} 3.1415926535898
atan 1 arctangent atan float &100000000000000090000009
{{#expr:atan.1}} 0.099668652491162
{{#expr:atan trunc1}} 0.78539816339745
{{#expr:4*atan 1}} 3.1415926535898
not 1 negation, logical NOT ! integer (1 or 0) &100000000000000090000009
{{#expr:not0}} 1
{{#expr:not1}} 0
{{#expr:not2}} 0
{{#expr:not trunc1}} 0
^ 2 exponentiation (power) pow float unless the base is of type integer and the exponent is non-negative and of type integer &100000000000000080000008
{{#expr:2^3}} 8
{{#expr:-2^3}} -8
{{#expr:-2^4}} 16
{{#expr:(trunc2)^(trunc-3)}} 0.125
{{#expr:(trunc2)^(trunc0)}} 1
{{#expr:(trunc2)^(trunc62)}} 4611686018427387904
{{#expr:(trunc2)^(trunc63)}} 9.2233720368548E+18
{{#expr:(-2)^1.2}} NAN
{{#expr:(-2)^.5}} NAN
* 2 multiplication * integer if both arguments are integer, otherwise float &100000000000000070000007
{{#expr:2*3}} 6
{{#expr:(trunc2)*3}} 6
{{#expr:2*trunc3}} 6
{{#expr:(trunc2)*trunc3}} 6
{{#expr:(trunc1e10)*trunc1e9}} 1.0E+19
/ (also written div) 2 division (div is not integer division[1]) / float, unless both arguments are integer and the mathematical result is an integer &100000000000000070000007
{{#expr:6/3}} 2
{{#expr:(trunc6)/3}} 2
{{#expr:2/trunc6}} 0.33333333333333
{{#expr:(trunc6)/trunc3}} 2
{{#expr:(trunc6)/trunc4}} 1.5
mod 2 modulo operation, remainder of division after truncating both operands to an integer.[1] % integer &100000000000000070000007
{{#expr:30mod7}} 2
{{#expr:-30mod7}} -2
{{#expr:30mod-7}} 2
{{#expr:-30mod-7}} -2
{{#expr:30.5mod7.9}} 2
+ 2 addition + integer if both arguments are integer, otherwise float &100000000000000060000006
{{#expr:2+3}} 5
{{#expr:(trunc2)+3}} 5
{{#expr:2+trunc3}} 5
{{#expr:(trunc2)+trunc3}} 5
{{#expr:(trunc7e18)+trunc4e18}} 1.1E+19
- 2 subtraction - integer if both arguments are integer, otherwise float &100000000000000060000006
{{#expr:3-2}} 1
{{#expr:(trunc3)-2}} 1
{{#expr:2-trunc2}} 0
{{#expr:(trunc3)-trunc2}} 1
{{#expr:(trunc-7e18)-trunc4e18}} -1.1E+19
round 2 rounds off the number on the left to a multiple of 1/10 raised to a power, with the exponent equal to the truncated value of the number given on the right round float &100000000000000050000005
{{#expr:9.876round2}} 9.88
{{#expr:(trunc1234)round trunc-2}} 1200
{{#expr:4.5round0}} 5
{{#expr:-4.5round0}} -5
{{#expr:46.857round1.8}} 46.9
{{#expr:46.857round-1.8}} 50
= 2 equality (numerical incl. logical, not for strings) == integer (1 or 0) &100000000000000040000004
{{#expr:3.0=3}} 1
{{#expr:3.1=3}} 0
{{#expr:3.0=trunc3}} 1
{{#expr:3.1=trunc3}} 0
{{#expr:1e16=trunc(1e16)}} 1
{{#expr:1e16=trunc(1e16)+trunc1}} 1
{{#expr:trunc(1e16)=trunc(1e16)+trunc1}} 0

wrong:

{{#expr:a=a}} Expression error: Unrecognized word "a".
<> (also written !=) 2 inequality, logical xor; not for strings (negation of =) != integer (1 or 0) &100000000000000040000004
{{#expr:3<>3}} 0
{{#expr:3<>4}} 1
< 2 less than (not for ordering of strings) < integer (1 or 0) &100000000000000040000004
{{#expr:3<3}} 0
{{#expr:3<4}} 1
{{#expr:2.9<3}} 1
{{#expr:3.0<3}} 0
{{#expr:2.9<trunc3}} 1
{{#expr:3.0<trunc3}} 0
{{#expr:1e16<trunc(1e16)+trunc1}} 0

wrong:

{{#expr:a<b}} Expression error: Unrecognized word "a".
> 2 greater than (same as <, with arguments reversed) > integer (1 or 0) &100000000000000040000004
{{#expr:4>3}} 1
{{#expr:3>3}} 0
<= 2 less than or equal to (same as >=, with arguments reversed) <= integer (1 or 0) &100000000000000040000004
{{#expr:3<=4}} 1
{{#expr:3<=3}} 1
>= 2 greater than or equal to (negation of <) >= integer (1 or 0) &100000000000000040000004
{{#expr:4>=3}} 1
{{#expr:3>=3}} 1
and 2 logical AND && integer (1 or 0) &100000000000000030000003
{{#expr:3and4}} 1
{{#expr:-3and0}} 0
{{#expr:0and4}} 0
{{#expr:0and0}} 0
or 2 logical OR || integer (1 or 0) &100000000000000020000002
{{#expr:3or4}} 1
{{#expr:-3or0}} 1
{{#expr:0or4}} 1
{{#expr:0or0}} 0
+ 1 unary + sign (nothing) same as argument n.a.
{{#expr:+1}} 1
{{#expr:+-1}} -1
{{#expr:+trunc1}} 1
(number) 0 unsigned number in ordinary decimal notation (unary plus and minus and e are treated as operators, see elsewhere in this table) floatval float n.a.
{{#expr:1234567890123456789}} 1.2345678901235E+18
{{#expr:123456789.0123456789}} 123456789.01235
e as subexpression 0 constant e exp(1) float n.a.
{{#expr:e}} 2.718281828459
pi 0 constant π pi() float n.a.
{{#expr:pi}} 3.1415926535898

Logical operators return 1 for true and 0 for false, and interpret 0 as false and any other number as true. Thus {{#expr: (2 < 3) + 1}} gives 2 [1]. Note that "and" and "or" work with #expr and #ifexpr only; for use with #if, #ifeq, and #ifexist, use 1 as then-text and 0 as else-text, and combine results with "and" and "or" in an outer #expr or #ifexpr. Instead of {{ #expr: {{#if:{{{a}}}|1|0}} or {{#if:{{{b}}}|1|0}} }} we can also use {{#if:{{{a}}}{{{b}}}|1|0}}}}. For negation, simply subtract from 1 or interchange then- and else-part.

Precedence is indicated in the table, a higher number means that the operator is applied first. Examples (">" refers to going before, "~" means application from left to right):

  • e > floor, not, etc.: {{#expr:floor1.5e1}} → 15, {{#expr:not0e1}} → 1
  • floor > ^: {{#expr:floor1.5^2}} → 1
  • ^ > *: {{#expr:2*3^2}} → 18
  • * ~ / ~ mod: {{#expr:12/3*2}} → 8, {{#expr:111/3mod10}} → 7, {{#expr:358mod10*2}} → 16,
  • * > +, -: {{#expr:2+3*4}} → 14, {{#expr:2-3*4}} → -10
  • + ~ -: {{#expr:6-2+3}} → 7, {{#expr:-2+3}} → 1
  • +, - > round: {{#expr:1.234round2-1}} → 1.2
  • round > = etc.: {{#expr:1.23=1.234round2}} → 1
  • = etc. > and: {{#expr:1 and 2=1}} → 0
  • and > or: {{#expr:1 or 1 and 0}} → 1

In the case of equal precedence number, evaluation is from left to right:

  • {{#expr:12/2*3}} → 18
  • {{#expr:3^3^3}} → 19683

Parentheses can force a different precedence: {{#expr:(2+3)*4}} → 20

Blank spaces are good for readability but not needed for working properly, except between words (including "e"), and not allowed within numbers:

  • {{#expr:7mod3}} gives 1 [2]
  • {{#expr:7.5round0}} gives 8 [3]
  • {{#expr:0and1}} gives 0 [4]
  • {{#expr:0or not0}} gives 1 [5]
  • {{#expr:0ornot0}} gives Expression error: Unrecognized word "ornot". [6]
  • {{#expr:123 456}} gives Expression error: Unexpected number. [7]
  • {{#expr:not not3}} gives 1 [8]
  • {{#expr:notnot3}} gives Expression error: Unrecognized word "notnot". [9]
  • {{#expr:---2}} gives -2 [10]
  • {{#expr:-+-2}} gives 2 [11]
  • {{#expr:2*-3}} gives -6 [12]
  • {{#expr:-not-not-not0}} gives -1 [13]
  • {{#expr:2*/3}} gives Expression error: Unexpected / operator. [14]
  • {{#expr:sinln1.1}} gives Expression error: Unrecognized word "sinln". [15]
  • {{#expr:sin ln1.1}} gives 0.095165945236752 [16]

For scientific notation e is treated as an operator. An e between subexpressions works just like *10^, except that together with the unary minus, it has the highest precedence, e.g. before a separate ^, and that the implicit 10 is of type integer, not float. An e as subexpression (i.e., with an each side either nothing or an operator) is Euler's constant. An e with on one side nothing or an operator and on the other side a subexpression gives an error message.

Transitivity[edit]

For comparing a number of type float with one of type integer, the integer is converted to float. Therefore the operators =, <= and >= are not transitive with mixed types:

  • {{#expr:trunc1e16=1e16}} → 1
  • {{#expr:1e16=trunc1e16+trunc1}} → 1
  • {{#expr:trunc1e16=trunc1e16+trunc1}} → 0
  • {{#expr:trunc1e16>=1e16}} → 1
  • {{#expr:1e16>=trunc1e16+trunc1}} → 1
  • {{#expr:trunc1e16>=trunc1e16+trunc1}} → 0

Similarly, a >= b and b = c does not imply a >=c:

  • {{#expr:trunc1e16>=1e16}} → 1
  • {{#expr:1e16=trunc1e16+trunc1}} → 1
  • {{#expr:trunc1e16>=trunc1e16+trunc1}} → 0

However, < and > are transitive.

Monotonicity[edit]

In division of numbers of type integer, a small change in the dividend can change the type of the result. Therefore, if the absolute value of the result is greater than 2^53, it is not always a monotonic function of the dividend:

  • {{numf|(trunc1e18-trunc2)/trunc3}} → 333,333,333,333,333,312
  • {{numf|(trunc1e18-trunc1)/trunc3}} → 333,333,333,333,333,333
  • {{numf|trunc1e18/trunc3}} → 333,333,333,333,333,312

Template:Divint rectifies this.

Numbers as input[edit]

Leading zeros are allowed, as well as a trailing decimal point (for an integer) and trailing zeros in a number with a decimal point.

  • "{{#expr: +01.20}}" gives "1.2" [17]
  • "{{#expr: 12.}}" gives "12" [18]

These equivalences apply also for #ifeq and #switch, see below.

The part of the expression representing a number is a sequence of digits and points; due to floatval a second point and any digits and points immediately after it are ignored, and do not give an error message. Group separators are not allowed: a comma is considered an unrecognised punctuation character:

Thus a number can only consist of:

  • one or more digits, or
  • zero or more digits, a point, and zero or more digits.
  • "{{#expr:123}}" gives "123" [19]
  • "{{#expr:123.456}}" gives "123.456" [20]
  • "{{#expr:.456}}" gives "0.456" [21]
  • "{{#expr:0}}" gives "0" [22]

Also accepted:

  • "{{#expr: 123.}}" gives "123" [23]
  • "{{#expr:000123.4560}}" gives "123.456" [24]
  • "{{#expr:.}}" gives "0" [25]

With ignored part:

  • "{{#expr:123.456.789}}" gives "123.456" [26]

Wrong:

  • "{{#expr: 123,456}}" gives "Expression error: Unrecognized punctuation character ","." [27]
  • "{{#expr: 123 456}}" gives "Expression error: Unexpected number." [28]

Combinations with the operator e:

Float:

  • "{{#expr:2.3e-5}}" gives "2.3E-5" [29]
  • {{#expr:2e18}} → 2.0E+18

Integer type:

  • {{#expr:(trunc123456789012345)e trunc4}} → 1234567890123450000

Compare:

  • {{#expr:123456789012345e4}} → 1.2345678901235E+18
  • {{#expr:trunc123456789012345e4}} → 1234567890123450112
  • {{#expr:(trunc123456789012345)e4}} → 1.2345678901235E+18
  • "{{#expr: e5}}" gives "Expression error: Unexpected number." [30]

Commas can be removed as follows:

  • {{formatnum:1,2,,34.567,8|R}} → 1234.5678

Input of a number of type integer is not possible. A float can be converted to type integer with the function trunc. An integer with a value that is not a float value can be constructed, e.g. with Template:Trunc, where the number is given in two pieces:

  • {{numf|{{trunc|12345678|90123456789}}}} → 1,234,567,890,123,456,789

The smallest positive float can be written:

  • {{#expr:.5e-323}} → 4.9406564584125E-324

but we cannot use that output as input:

  • {{#expr:4.9406564584125E-324}} → 0

All digits are used to determine the float to which a number is rounded, as demonstrated in a borderline case:

{{hex|0.00000000000000011102230246251566636831481088739149080825}}1.0000000000000hex*2^-53
{{hex|0.00000000000000011102230246251566636831481088739149080826}}1.0000000000001hex*2^-53

  • {{numf|2^-53}} → .00000000000000011102230246251565
  • {{numf|2^-53+2^-105}} → .00000000000000011102230246251568

Similarly:

  • {{numfh|4398046511104.00048828125}} → 4,398,046,511,104 (ca. 4.4e12) 1.0000000000000hex*2^42
  • {{numfh|4398046511104.00048828125000000000000000000000000000000000000000000000001}} → 4,398,046,511,104.001 (ca. 4.4e12) 1.0000000000001hex*2^42
  • 2^42+2^-10 = 4,398,046,511,104.000,976,562,5

Thus we see that the value halfway the two consecutive floats is rounded down in this case, while the other decimal fractions between the two floats are rounded to the nearest of the two.

Function plural[edit]

As opposed to ParserFunctions, "plural" accepts points and commas in numbers and interprets them in a site-language-specific way (depending on $separatorTransformTable in Messagesxx.php); on this site:

  • "{{plural:1.000|a|b|c}}" gives "a" [31]
  • "{{plural:1,000|a|b|c}}" gives "b" [32]

(on e.g. the German and the Dutch sites reversed w.r.t. the result on English sites).

However, this can be used instead of #ifeq, #ifexpr or #switch only for distinguishing a few site-language-specific categories of numbers (for English: 1 and "not equal to 1", for French <=1 and >1, etc.). Also, since it is designed for linguistic distinction of singular and plural, in some languages the categories of numbers are numerically less useful.

Numbers as output[edit]

The MediaWiki software simply passes on the literal result of the php computation, except that logical values are changed to 1 and 0. Therefore the format can depend on the server.

A number of type integer is displayed without rounding and in ordinary decimal notation:

  • {{#expr:trunc(2^52)}} → 4503599627370496
  • {{#expr:-trunc(2^52)}} → -4503599627370496
  • {{#expr:trunc1100000}} → 1100000
  • {{#expr:trunc1200000}} → 1200000
  • {{#expr:trunc1300000}} → 1300000
  • {{#expr:trunc4100000}} → 4100000

while a number of type double is rounded to 14 significant digits, while inconsistently displaying some numbers in scientific format. This is reportedly a bug in the Zend Engine which has been fixed [33], but on Wikimedia apparently not yet:

  • {{#expr:2^52}} → 4.5035996273705E+15
  • {{#expr:-(2^52)}} → -4.5035996273705E+15
  • {{#expr:1100000}} → 1100000
  • {{#expr:1200000}} → 1200000
  • {{#expr:1300000}} → 1300000
  • {{#expr:4100000}} → 4100000
  • {{#expr:1/7}} → 0.14285714285714

Note: Internally, the expression may be computed with more digits (typically 18 significant digits, for example on Wikimedia servers which are using IEEE 64-bit double in the implementation of PHP used by MediaWiki, but possibly more depending on the hardware architecture supported by PHP, which may have been itself compiled to use "long double" with an extended precision using 80- to 128-bit binary formats), so the formatted value returned by #expr will not exhibit some small differences.

If MediaWiki is installed on a server whose PHP engine was compiled for an architecture using different binary storage formats for its C/C++ datatype "double" (possibly with less precision than the IEEE 64-bit format), and possibly optimized for speed (the compiled C code or its linked-in mathematical libraries may then not use "strict" IEEE rounding modes for every floatting point operation, but may keep some precision for intermediate results by not rounding them at each step, or could also compute results faster using internal values with less precision), you will get different results in PHP: MediaWiki will not be able to use the same precision (or the same range of magnitudes), and the results of calculations may vary between servers. When installing MediaWiki on a PHP server, make sure you look at PHP configuration options.

For example if the architecture supports fast floatting points only with 32-bit format,s you'll get only 7 or 8 significant digits, and the 14 digits displayed by MediaWiki may exceed what the server can really compute. As well you may get unexpected "infinite" values or zero where another server could have returned accurate values).

For some representable round numbers, notably some multiples of 100,000, scientific notation is produced, which, if reused in an expression, is not even exactly equal to the original number:

  • {{numfh|4.1e6}} → 4,099,999.9999999995 (ca. 4.1e6) 1.f47cfffffffffhex*2^21

Thus we may want to either compare two results of #expr (for equality up to 14 digits) or compare two expressions, such as 4100000 and 4000000+100000 (for exact equality); depending on context and intention, the negative result of the comparison of the result of expr with the exact number may be confusing.

The function formatnum adds commas (on the left of the point only), but does not convert from or to scientific format:

  • {{formatnum:1234567.890123}} → 1,234,567.890123
  • {{formatnum:1234567.890123E16}} → 1,234,567.890123E16

The number output is suitable for many other calculation programs, also the scientific notation. In that sense output like 6E23 is more convenient than 6×1023.

Template:Num displays a number with high accuracy (such that in the case of float the specific internal value is reconstructed when using the output as input), with the variant Template:Numf showing thousands separators:

  • {{numf|trunc3^trunc39}} → 4,052,555,153,018,976,267
  • {{numf|trunc3^trunc40}} → 12,157,665,459,056,928,000
  • {{numf|1/7}} → .14285714285714284

Negative zero[edit]

Although the literal "-0" (the unary minus applied to 0) gives 0, some operations give the float "-0" (preserving commutativity of + and *):

Generating -0 with *, /, ceil, round:

  • {{#expr: -1*0}} → -0
  • {{#expr: (-1e-200)*1e-200}} → -0
  • {{#expr: -1/1e333}} → -0
  • {{#expr: 0/-1}} → -0
  • {{#expr: (-1e-200)/1e200}} → -0
  • {{#expr: (1e-200)/-1e200}} → -0
  • {{#expr: ceil(-.1)}} → -0
  • {{#expr: -.2round0}} → -0

Passing -0 on with unary +, binary + and -, * (and hence operator e), /, floor, ceil:

  • {{#expr: +(-1*0)}} → -0
  • {{#expr: (-1*0)+(-1*0)}} → -0
  • {{#expr: (-1*0)-0}} → -0
  • {{#expr: 1*(-1*0)}} → -0
    • {{#expr: (-1*0)e0}} → -0
  • {{#expr: (-1*0)/1}} → -0
  • {{#expr: floor(-1*0)}} → -0
  • {{#expr: ceil(-1*0)}} → -0

However:

  • {{#expr: -0}} → 0
  • {{#expr: -10^-401}} → 0

Since 2011 the function #ifexpr takes both 0 and the float -0 as false:

  • {{#ifexpr:0|1|0}} → 0
  • {{#ifexpr:-1*0|1|0}} → 0

Also, as argument of a logical operator -0 is taken as false:

  • {{#expr:not(-1*0)}} → 1
  • {{#expr:(-1*0)and1}} → 0
  • {{#expr:(-1*0)or0}} → 0

If an expression of type float can have the value -0, then an operation that removes the minus sign from a possible -0, but does not affect any other result, is the addition of 0. If an expression may be of type integer then one can add trunc0.

  • {{#expr:0+(-1*0)}} → 0

Type conversion[edit]

A float can be converted to type integer by operator trunc (note however that for 2^63 <= x <= 2^64 we get x - 2^64, for larger x we get 0; for x < -2^63 we get -2^63).

An expression of type integer can be converted to float by adding 0. Note that for integers greater than 2^53 this involves rounding.

Limitations and workarounds[edit]

The operator trunc gives the correct mathematical result of rounding toward 0 to an integer for integer-type numbers and for floats x inside the integer range: -2^63 <= x < 2^63. To also get the correct mathematical result for floats outside this range is simple, because these floats all have an integer value, so they can be left unchanged. Template:Trunc does this.

The operator mod gives strange errors for some fairly large values of the second argument:

  • {{#expr:123mod(2^32-1)}} → 123

Template:Modint works correctly for a larger range.

The operator round with second argument 0 gives wrong results for odd numbers between 2^52 and 2^53, even though the exact results are representable as float. Also, the operator rounds integer-type numbers with an absolute value between 2^53 and 2^63 to float. Template:Round0 always gives the expression for the exact result, for subsequent use in an expression, or for display (with the accuracy of this depending on the accuracy of the display function or template only).

The operator floor rounds integer-type numbers with an absolute value between 2^53 and 2^63 to float, and not necessarily downward. Similarly the operator ceil rounds these numbers not necessarily upward. Template:Floor and Template:Ceil always give the expressions for the exact results, for subsequent use in an expression, or for display (with the accuracy of this, and the direction of rounding, depending on the display function or template only).

Branching depending on an expression[edit]

The function #ifexpr: produces one of two specified results, depending on the value of a boolean expression involving numbers and booleans (not strings). Examples:

  • {{#ifexpr: {{CURRENTDOW}} = 0 or {{CURRENTDOW}} = 6 | weekEND | weekDAY}} yields weekDAY because today is Monday and so "{{CURRENTDOW}}" is "1" [34].
  • {{#expr:2^10=1024}} → 1

Note that rounding errors can affect a comparison, even if they are not visible in the displayed values: the internal values are compared. This applies even to large integers:

  • {{#expr:1024e20-1e23}} → 2.4E+21
  • {{#expr:1024e20-1e23=2.4e21}} → 0

Instead one may want to allow a relatively small difference that could be present due to rounding errors:

  • {{#expr:abs(1024e20-1e23-2.4e21)<1e8}} → 1

Again, for comparing a number of type float with one of type integer, the integer is converted to float. In this case the type is determined by the format of the number, e.g. 2 is an integer, but 2.0 and 2e0 are floats; also 12345678901234567890 is a float, because it is too large for an integer.

Again, equality is not transitive with mixed types:

  • {{#ifeq:12345678901234567|12345678901234568.0|1|0}} → 1
  • {{#ifeq:12345678901234568.0|12345678901234568|1|0}} → 1
  • {{#ifeq:12345678901234567|12345678901234568|1|0}} → 0
  • {{#ifeq:12345678901234567|12345678901234567e0|1|0}} → 1
  • {{#ifeq:12345678901234567e0|12345678901234568|1|0}} → 1
  • {{#ifeq:12345678901234567|12345678901234568|1|0}} → 0
  • {{num|trunc(2^62)-trunc1+trunc(2^62)}} → 9223372036854775807
  • {{#ifeq:9223372036854775700|9223372036854775900|1|0}} → 1
  • {{#ifeq:9223372036854775900|9223372036854775800|1|0}} → 1
  • {{#ifeq:9223372036854775700|9223372036854775800|1|0}} → 0

Comparisons[edit]

The functions #ifeq and #switch compare numbers and strings for equality using PHP operator ==, the same as the equality operator mentioned above, but now applied directly to the expanded wikitext of the arguments. For comparison as numbers no expressions (not even constants) are allowed, but in this case the unary plus and minus and the e of scientific notation are taken as part of the number, instead of as operators. Without e and decimal point the type is integer, otherwise it is float. As mentioned above, when an integer is compared with a float, the integer is converted to float first.

  • {{#ifeq:3|3.0|1|0}} → 1
  • {{#ifeq:3|03|1|0}} → 1
  • {{#ifeq:0.00003456|3.456E-05|1|0}} → 1
  • {{#ifeq:1e23|.1e24|1|0}} → 1 although rounding both numbers to float gives different internal numbers:
    • {{#expr:1e23-.1e24}} → -16777216
    • {{#expr:1e23=.1e24}} → 0
    • {{#ifexpr:1e23=.1e24|1|0}} → 0
  • {{#ifeq:9034567890123456789|9034567890123456788|1|0}} → 0 (two numbers of type integer, therefore only true if exactly equal); compare:
  • {{#ifeq:9034567890123456700.0|9034567890123456800|1|0}} → 1 (due to the decimal point in one number, both are rounded to float before the comparison, so the comparison is cruder)

Length of expressions[edit]

Long expressions are allowed, see Template:Long expression demo. However, see also efficiency.

Error messages[edit]

Examples for all known #expr: and #ifexpr: error messages. The error texts are within the tags <strong class="error">..</strong>.

  • "{{#expr:1/0}}" → "Expression error: Division by zero" [35]
  • "{{#expr:2*}}" → "Expression error: Missing operand for *." [36]
  • "{{#expr:1 2}}" → "Expression error: Unexpected number." [37]
  • "{{#ifexpr:1*/2}}" → "Expression error: Unexpected / operator." [38]
  • "{{#expr: 1 (2)}}" → "Expression error: Unexpected ( operator." [39]
  • "{{#expr: (1}}" → "Expression error: Unclosed bracket." [40]
  • "{{#expr: 1)}}" → "Expression error: Unexpected closing bracket." [41]
  • "{{#expr:2*123,456}}" → "Expression error: Unrecognized punctuation character ","." [42]
  • "{{#expr:{{{a}}}}}" → "Expression error: Unrecognized punctuation character "{"." [43]
  • "{{#ifexpr:3%2}}" → "Expression error: Unrecognized punctuation character "%"." [44]
  • "{{#ifexpr:abc}}" → "Expression error: Unrecognized word "abc"." [45]
  • "{{#expr:abc.def}}" → "Expression error: Unrecognized word "abc"." [46]

{{ #expr:{{ x|102|1000*}} 18 }} gives 1.8E+307

{{ #expr:{{ x|102|1000*}} 179 }} gives 1.79E+308

{{ #expr:{{ x|102|1000*}} 180 }} gives INF (on Wikimedia "INF", but depending on the operating system of the server it may also be e.g. "1.#INF")

INF also appears when an intermediate result is of range:

  • {{#expr:1e309/1e308}} → INF
  • {{#expr:1e200*1e200*1e-300}} → INF.

but

  • {{#expr:1e200*(1e200*1e-300)}} → 1.0E+100.

{{ #expr:{{ x|33|(1+(}} 1 {{ x|33|))}} }} gives 34

{{ #expr:{{ x|34|(1+(}} 1 {{ x|34|))}} }} gives Expression error: Stack exhausted.

"{{#expr:3.4.5.6}}" gives "3.4" [47]   (no feature, only an oddity)


Note: template:x ( talk edit history links ) copies a given string, here parts of an expression, for the specified times (max. 120).

Wikitext without error message from the parser functions, but typically unintended:

{{{#expr:2*3}}}   {{{#expr:2*3}}}   (triple braces, the whole is interpreted as parameter tag with parameter name "#expr:2*3")
{{#expr:2*3}}} 6} (one closing brace too many; the last of the three is interpreted as plain text, so that the rest works fine)
{{{#expr:2*3}} {6 (one opening brace too many; the first of the three is interpreted as plain text, so that the rest works fine)
{{#expr:2*3} {{#expr:2*3} (too few braces, the whole is interpreted as plain text)

Checking for a number[edit]

Check whether a string is a valid numeric expression:

  • {{#if:{{#ifexpr:3}}|0|1}} gives 1
  • {{#if:{{#ifexpr:3-2}}|0|1}} gives 1
  • {{#if:{{#ifexpr:3 2}}|0|1}} gives 0

Find the value represented by a string if it is a valid numeric expression, otherwise just return the string:

  • {{#iferror:{{#expr:3}}|3}} gives 3
  • {{#iferror:{{#expr:3-2}}|3-2}} gives 1
  • {{#iferror:{{#expr:3 2}}|3 2}} gives 3 2

Check whether a string is a number:

  • {{#ifeq:3|{{#expr:3}}|1|0}} gives 1
  • {{#ifeq:03|{{#expr:03}}|1|0}} gives 1
  • {{#ifeq:3-2|{{#expr:3-2}}|1|0}} gives 0
  • {{#ifeq:3 2|{{#expr:3 2}}|1|0}} gives 0

Minus sign[edit]

Only the hyphen-minus character or minus sign character, typed directly, work as a minus sign operator in expressions.

  • The HTML character references (by name or by numeric code point value) are not recognized when evaluating expressions: numerical character references are converted only when generating the final HTML document (after expansion of templates and parser functions)
  • Only a handful of character references by name are substituted early by MediaWiki, all others are interpreted only by the browser.
  • The other dash characters (such as the hyphen, the figure dash, en dash, em dash and others), though often similar visually, are not valid minus signs, but punctuation signs or typographical variants.
hyphen-minus, typed directly as the character '-' (U+002D) "{{#expr:-12}}" "-12" [48]
hyphen-minus, typed as the numerical character reference &#x2D; "{{#expr:&#x2D;12}}" "Expression error: Unrecognized punctuation character "&"." [49]
hyphen-minus, typed as the numerical character reference &#45; "{{#expr:&#45;12}}" "Expression error: Unrecognized punctuation character "&"." [50]
minus sign, typed directly as the character '−' (U+2212) "{{#expr:−12}}" "-12" [51]
minus sign, typed as the numerical character reference &#x2212; "{{#expr:&#x2212;12}}" "Expression error: Unrecognized punctuation character "&"." [52]
minus sign, typed as the numerical character reference &#8722; "{{#expr:&#8722;12}}" "Expression error: Unrecognized punctuation character "&"." [53]
minus sign, typed as the symbolic character reference &minus; "{{#expr:&minus;12}}" "-12" [54]
figure dash, typed directly as the character '‒' (U+2012) "{{#expr:‒12}}" "Expression error: Unrecognized punctuation character "�"." [55]
figure dash, typed as the numerical character reference &#x2012; "{{#expr:&#x2012;12}}" "Expression error: Unrecognized punctuation character "&"." [56]
figure dash, typed as the numerical character reference &#8210; "{{#expr:&#8210;12}}" "Expression error: Unrecognized punctuation character "&"." [57]
en dash, typed directly as the character '–' (U+2013) "{{#expr:–12}}" "Expression error: Unrecognized punctuation character "�"." [58]
en dash, typed as the numerical character reference &#x2013; "{{#expr:&#x2013;12}}" "Expression error: Unrecognized punctuation character "&"." [59]
en dash, typed as the numerical character reference &#8211; "{{#expr:&#8211;12}}" "Expression error: Unrecognized punctuation character "&"." [60]
en dash, typed as the symbolic character reference &ndash; "{{#expr:&ndash;12}}" "Expression error: Unrecognized punctuation character "&"." [61]

Also many other calculation programs require a hyphen. Therefore, in order to be able to copy rendered numbers and expressions to the edit box or input them through a copy operation into other calculation programs, displayed minus signs also need to be hyphens.

Displaying numbers and numeric expressions[edit]

Guidelines such as w:Wikipedia:Manual of Style (dates and numbers)#Numbershttp://en.wikipedia.org/wiki/Wikipedia:Manual of Style (dates and numbers)#Numbers focus on number display as end product. However, a point of consideration can also be the possibility to apply the rendered output to #expr or #ifexpr, or to input it without conversion into other calculation programs. This would require the following:

  • use digits, not words
  • as mentioned above, use the hyphen as minus sign
  • use *, <=, and >=, not ×, ≤, or ≥
  • do not use thousands separators (however, some programs allow them)
  • use output like 6E23 or 6e23 rather than 6×1023

Examples:

  • "{{#expr:three}}" gives "Expression error: Unrecognized word "three"." [62]
  • "{{#expr:2<3}}" gives "1" [63]
  • "{{#expr:2≤3}}" gives "Expression error: Unrecognized punctuation character "�"." [64]
  • "{{#expr:2<=3}}" gives "1" [65]
  • "{{#expr:2>3}}" gives "0" [66]
  • "{{#expr:2≥3}}" gives "Expression error: Unrecognized punctuation character "�"." [67]
  • "{{#expr:2>=3}}" gives "0" [68]
  • "{{#expr:2*3}}" gives "6" [69]
  • "{{#expr:2×3}}" gives "Expression error: Unrecognized punctuation character "�"." [70]
  • "{{#expr:2,300}}" gives "Expression error: Unrecognized punctuation character ","." [71]
  • "{{#expr:6E23}}" gives "6.0E+23" [72]

If the number is the result of a computation by MediaWiki and unsuitable for use in a new computation due to application of a formatting function such as #formatnum or a formatting template, one can copy the wikitext and apply the additional computation before the formatting. However, when templates are used, and copying is done to another wiki, these templates have to be copied too, or substituted.

If you want to calculate with Magic words and return group seperated results you can use formatnum:
{{formatnum: {{#expr: {{NUMBEROFPAGES:R}} - {{NUMBEROFFILES:R}} }} }} = 4,230,701 (instead of 4230701).

See also[edit]

  1. a b div and mod are different from all programming languages, see bugzilla:6068


Links to other help pages[edit]

Help contents
Meta · Wikinews · Wikipedia · Wikiquote · Wiktionary · Commons: · Wikidata · Mediawiki · Wikibooks · Wikisource · Mediawiki:Manual · Google
Versions of this help page (for other languages see further)
What links here on Meta or from Meta · Wikipedia · MediaWiki
Reading
Go · Search · Stop words · Namespace · Page name · Section · Backlinks · Redirect · Category · Image page · Special pages · Printable version
Tracking changes
Recent changes (enhanced) | Related changes · Watching pages · Diff · Page history · Edit summary · User contributions · Minor edit · Patrolled edit
Logging in and preferences
Logging in · Preferences · User style
Editing
Starting a new page · Advanced editing · Editing FAQ · Edit toolbar · Export · Import · Shortcuts · Edit conflict · Page size
Referencing
Links · URLs · Piped links · Interwiki linking · Footnotes
Style and formatting
Wikitext examples · CSS · Reference card · HTML in wikitext · Formula · List · Table · Sorting · Colors · Images and file uploads
Fixing mistakes
Show preview · Testing · Reverting edits
Advanced functioning
Expansion · Template · Advanced templates · Parser function · Parameter default · Variable · System message · Substitution · Array · Calculation · Embed page
Others
Special characters · Renaming (moving) a page · Preparing a page for translation · Talk page · Signatures · Sandbox · Legal issues for editors
Languages: English  · slovenščina