This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

Mathematics Operators

21st March 2023 at 1:30pm

Introduced in v5.1.20The mathematics filter operators allow numerical calculations to be performed within filters.

Using mathematics operators

The mathematics operators interpret their arguments as numbers according to the following rules:

  • Any non-numeric characters after a valid number are ignored (e.g. 28px is interpreted as the number 28)
  • If the argument cannot be interpreted as a number, the value 0 is used (e.g. foo is interpreted as the number 0)
  • The special values Infinity and -Infinity can be used to represent positive and negative infinity respectively

Warning
Some filter operators remove duplicate items which can cause unexpected results when using the mathematics operators. See Dominant Append for details.

The mathematics operators take three different forms:

  • Unary operators apply an operation to each number in the input list (e.g. negate, truncate, sign)
    • =1 =2 =3 =4 +[negate[]]evaluates to-1-2-3-4
    • =1.2 =2.4 =3.6 =4.8 +[trunc[]]evaluates to1234
    • =1.2 =2.4 =3.6 =4.8 +[round[]]evaluates to1245
  • Binary operators apply an operation and parameter to each number in the input list (e.g. add, multiply, remainder)
    • =1 =2 =3 =4 +[add[3]]evaluates to4567
    • =1 =2 =3 =4 +[multiply[8]]evaluates to8162432
  • Reducing operators apply an operation to all of the numbers in the input list, returning a single result (e.g. sum, product)
    • =1 =2 =3 =4 +[sum[]]evaluates to10
    • =1 =2 =3 =4 +[product[]]evaluates to24
    • =1 =2 =3 =4 +[average[]]evaluates to2.5

Operations Combination

Operations can be combined by concatenating them while merging the inner ][ characters.

  • [[355]divide[113]fixed[5]]evaluates to3.14159
  • [range[100]sum[]divide[100]]evaluates to50.5
  • [tag[HelloThere]get[text]length[]sum[]]evaluates to10375

Complex operations will sometimes need to be split up into separate filters. For example, to compute the average length of the text field of tiddlers tagged "HelloThere":

<$set name="number-of-tiddlers" value={{{ [tag[HelloThere]count[]] }}}>
Average length of <$text text=<<number-of-tiddlers>>/> tiddlers tagged <<tag "HelloThere">>: <$text text={{{ [tag[HelloThere]get[text]length[]sum[]divide<number-of-tiddlers>fixed[3]] }}}/>
</$set>

That renders as:

Average length of 8 tiddlers tagged : 1296.875

Mathematics Operators list

Operator Purpose
abs calculate the absolute value of a list of numbers
acos calculate the arccosine value (in radians) of a list of numbers
add treating each input title as a number, add to each the numeric value of the parameter
asin calculate the arcsine value (in radians) of a list of numbers
atan calculate the arctangent value (in radians) of a list of numbers
atan2 returns the angle in the plane (in radians) between the positive x-axis and the ray from (0,0) to the point (x,y), for [Y]atan2[X]
average treating each input title as a number, compute their arithmetic mean
ceil rounds a list of numbers up to the next largest integer
compare filter the input by comparing each item against the parameter
cos calculate the cosine value of a list of angles (given in radians)
divide treating each input title as a number, divide it by the numeric value of the parameter
exponential convert each number to exponential notation with N digits
fixed convert each number to fixed point notation with N digits after the decimal point
floor rounds a list of numbers to the largest integer less than or equal to each number
log treating each input title as a number, return its logarithm with base equal to the numeric value of the parameter if specified, otherwise base e
max treating each input title as a number, take the maximum of its value and the numeric value of the parameter
maxall find the largest of a list of numbers
median treating each input title as a number, compute their median value
min treating each input title as a number, take the minimum of its value and the numeric value of the parameter
minall find the smallest of a list of numbers
multiply treating each input title as a number, multiply it by the numeric value of the parameter
negate calculate the negation of a list of numbers
power treating each input title as a number, raise it to the power of the numeric value of the parameter
precision convert each number to a string with N significant digits
product produce the product of the input numbers
remainder treating each input title as a number, return the remainder when divided by the numeric value of the parameter
round rounds a list of numbers to the nearest integer
sign return -1, 0 or 1 for a list of numbers according to whether each number is negative, zero, or positive
sin calculate the sine value of a list of angles (given in radians)
standard-deviation treating each input title as a number, compute their standard-deviation
subtract treating each input title as a number, subtract from each the numeric value of the parameter
sum produce the sum of the input numbers
tan calculate the tangent value of a list of angles (given in radians)
trunc truncates a list of numbers to their integer part, removing any fractional part
untrunc rounds a list of numbers to the next integer with largest absolute value, that is, away from zero
variance treating each input title as a number, compute their variance