Calculator formula syntax
Every operator, function, and formatting method you can use in a popup equation, with the rules for attribute names and blank results.
Look up any operator, function, or formatting method here before you type it into an equation. This page covers Custom popup equations and Calculator popup Step 3, which use the same syntax.
Type every formula on this page in the equation editor, which opens when you click Insert equation. A formula typed straight into the popup text does not calculate.
Numbers only
An equation takes numbers and gives one number. It cannot show text.
- Every attribute value is read as a number.
- The result must be a number. A formula that gives text or true/false stays blank.
- Each branch of a condition must give a number.
if({stock} > 0, {price}, 'Sold out')shows the price whenstockis above zero, but is blank for every other feature.
To show text that depends on an attribute, such as Sold out, use conditional content, not an equation.
Variable syntax
| Syntax | {field_name} |
Refers to the value of a feature attribute. Wrap each attribute in its own braces: {population} / {area} works, but {population / area} does not. A name without braces, such as area, is not read as an attribute, and the equation stays blank. The attribute name is the field’s underlying name (not the alias from the Format tab).
Every attribute value is read as a number. A text value, such as Bay, makes the equation blank. So does an attribute that is missing or blank on the feature.
Any attribute name works
Names with spaces or other characters, such as {land value}, work.
Operators
Operators run in this order, first to last. Use parentheses to change the order.
| Operator | Meaning | Example | Result for the example |
|---|---|---|---|
( ) |
Group | ({a} + {b}) / 2 |
Average of a and b |
! |
Factorial | {n}! |
6 when n is 3 |
^ |
Power | {side} ^ 2 |
9 when side is 3 |
- (before a value) |
Negative | -{change} |
-4 when change is 4 |
+ (before a value) |
No change | +{a} |
Same as {a} |
* |
Multiply | {rate} * {total} |
|
/ |
Divide | {total} / {households} |
|
% |
Remainder after dividing | {total} % {per_box} |
2 when total is 17 and per_box is 5 |
+ |
Add | {male} + {female} |
|
- |
Subtract | {total} - {male} |
|
==, != |
Equal, not equal | {code} == 3 ? 1 : 0 |
1 when code is 3 |
<, <=, >, >= |
Less than, at most, more than, at least | {a} > {b} ? {a} : {b} |
The larger value |
in |
Is in a list | {code} in [1, 2, 3] ? 1 : 0 |
1 when code is 2 |
and |
Both are true | {a} > 0 and {b} > 0 ? 1 : 0 |
|
or |
One or both are true | {a} > 0 or {b} > 0 ? 1 : 0 |
|
not |
Is not true | not ({a} > 0) ? 1 : 0 |
|
? : |
If, then, else | {stock} > 0 ? {price} : 0 |
price when stock is above zero, else 0 |
The ×, ÷, and − symbols also work, and mean *, /, and -.
A comparison (==, >, in, and, and the others) gives true or false, not a number. Use it inside ? : or if(...), or the equation stays blank.
Functions
Function names are case-sensitive: round, not Round. Put the arguments in parentheses, separated by commas.
Rounding
| Function | Result | Example | Result for the example |
|---|---|---|---|
round(x) |
x rounded to the nearest whole number |
round(2.5) |
3 |
roundTo(x, n) |
x rounded to n decimal places |
roundTo(98.76, 1) |
98.8 |
floor(x) |
x rounded down |
floor(2.9) |
2 |
ceil(x) |
x rounded up |
ceil(2.1) |
3 |
trunc(x) |
x with its decimals removed |
trunc(-3.7) |
-3 |
round, roundTo, floor, ceil, and trunc change the value. Decimal Places changes only how many decimals show.
Sign, smallest, and largest
| Function | Result | Example | Result for the example |
|---|---|---|---|
abs(x) |
x without its negative sign |
abs(-3.7) |
3.7 |
sign(x) |
-1, 0, or 1, for a negative value, zero, or a positive value |
sign(-3.7) |
-1 |
min(a, b, ...) |
The smallest value | min({this_year}, {last_year}) |
|
max(a, b, ...) |
The largest value | max({this_year}, {last_year}) |
Powers and roots
| Function | Result | Example | Result for the example |
|---|---|---|---|
sqrt(x) |
Square root. Blank if x is negative. |
sqrt(9) |
3 |
cbrt(x) |
Cube root | cbrt(27) |
3 |
pow(x, y) |
x to the power y, the same as x ^ y |
pow(3, 3) |
27 |
hypot(a, b) |
Square root of a² + b². pyt(a, b) is the same. |
hypot(3, 4) |
5 |
fac(n) |
Factorial, the same as n! |
fac(5) |
120 |
exp(x) |
E to the power x |
exp(1) |
2.718... |
expm1(x) |
exp(x) - 1 |
expm1(0) |
0 |
Logarithms
| Function | Result | Example | Result for the example |
|---|---|---|---|
ln(x) |
Natural logarithm (base E) |
ln(E) |
1 |
log(x) |
Natural logarithm (base E), the same as ln. Not base 10. |
log(E) |
1 |
log10(x) |
Base-10 logarithm | log10(1000) |
3 |
log2(x) |
Base-2 logarithm | log2(8) |
3 |
log1p(x) |
ln(1 + x) |
log1p(0) |
0 |
Angles
Angles are in radians. To change degrees to radians, multiply by PI / 180.
| Function | Result |
|---|---|
sin(x), cos(x), tan(x) |
Sine, cosine, tangent |
asin(x), acos(x), atan(x) |
Inverse sine, cosine, tangent |
atan2(y, x) |
The angle from (0, 0) to the point (x, y) |
sinh(x), cosh(x), tanh(x) |
Hyperbolic sine, cosine, tangent |
asinh(x), acosh(x), atanh(x) |
Inverse hyperbolic sine, cosine, tangent |
Example: sin({bearing} * PI / 180) gives the sine of a bearing in degrees.
Conditions
| Function | Result | Example |
|---|---|---|
if(condition, a, b) |
a if the condition is true, else b. The same as condition ? a : b. |
if({stock} > 0, {price}, 0) |
a and b must both be numbers. Text, such as 'Sold out', makes the equation blank for every feature that gets that branch. To show text, use conditional content.
Other
| Function | Result |
|---|---|
random(n) |
A random number from 0 up to (but not including) n. The number changes each time the popup opens. |
Constants
| Constant | Value |
|---|---|
PI |
3.14159… |
E |
2.71828… |
Example: PI * {radius} ^ 2 gives the area of a circle.
Format the result
By default, the result shows with the number of decimals in Decimal Places, and with no thousand separators: 12508.28. To format it another way, add a formatting method to the end of the formula.
Decimal places
| Default | 2 |
| Range | 0–10 |
| Where | Decimal Places field in the equation editor modal |
Sets the number of decimals in the result. Each equation has its own setting. A formatting method replaces this setting.
.toLocaleString()
| Syntax | (formula).toLocaleString() or (formula).toLocaleString('locale') |
| Default | en-US |
Adds thousand separators, in the number style of a locale (a country or language code). The result shows up to 3 decimals, with no zeros at the end. To set the decimals, round inside the formula first, with round(...) or roundTo(..., n). You can also add .toFixed(n).
| Formula | Result |
|---|---|
round({population} / {area}).toLocaleString() |
12,508 |
roundTo({population} / {area}, 1).toLocaleString() |
12,508.3 |
({population} / {area}).toFixed(2).toLocaleString() |
12,508.28 |
({a} + {b}).toLocaleString() |
4,000.75 |
({a} + {b}).toLocaleString('en-GB') |
4,000.75 |
({a} + {b}).toLocaleString('de-DE') |
4.000,75 |
({a} + {b}).toLocaleString('fr-FR') |
4 000,75 |
({population} * 10).toLocaleString('en-IN') |
1,23,45,670 |
A locale code in the wrong form, such as en_US, makes the equation blank. A code in the right form that no locale uses, such as xx-YY, gives a default number style.
Locales and number scripts
The locale code sets the separators. A code that ends in -u-nu- and a script name also shows the digits in that script. These results are for the value 123456789.01:
| Number style | Locale code | Result |
|---|---|---|
| Comma separators, point decimal (UK, US) | en-GB, en-US |
123,456,789.01 |
| Space separators, comma decimal (France, Russia) | fr-FR, ru-RU |
123 456 789,01 |
| Point separators, comma decimal (Germany) | de-DE |
123.456.789,01 |
| Apostrophe separators (Switzerland) | de-CH |
123'456'789.01 |
| Lakh separators (India) | en-IN |
12,34,56,789.01 |
| Arabic digits | ar-EG |
١٢٣٬٤٥٦٬٧٨٩٫٠١ |
| Persian digits | fa-AF |
۱۲۳٬۴۵۶٬۷۸۹٫۰۱ |
| Thai digits | th-TH-u-nu-thai |
๑๒๓,๔๕๖,๗๘๙.๐๑ |
| Devanagari digits | hi-u-nu-deva |
१२,३४,५६,७८९.०१ |
| Chinese digits | zh-Hans-CN-u-nu-hanidec |
一二三,四五六,七八九.〇一 |
| Full-width digits | ja-JP-u-nu-fullwide |
１２３,４５６,７８９.０１ |
Other locale codes and scripts also work. For every script name, see the list of numbering systems. A script shows correctly only if the viewer’s device has a font for it.
Only the locale code can change. Currency, percent, and unit styles are not available.
Moving from v3? The v3 locale examples work in v4. Type them in the equation editor without #{ }#: ({attribute}).toLocaleString('th-TH-u-nu-thai'). v4 shows up to 3 decimals, so (24586 / 6548).toLocaleString('fr-FR') shows 3,755. Use roundTo(..., 2) for 3,75.
.toFixed(n)
| Syntax | (formula).toFixed(n) |
| Range | 0–100 |
Shows exactly n decimals: ({pct} * 100).toFixed(1) gives 45.7, and .toFixed(0) gives a whole number. On its own, .toFixed(n) adds no thousand separators. Add .toLocaleString() as well to get them.
Rules for formatting methods
- Put the method at the end of the formula. It formats the result of the whole formula. Parentheses around the formula, as in
({a} + {b}).toLocaleString(), make this clear to the reader. - You can use both methods, in either order. For the value
4000.5,.toFixed(2).toLocaleString()and.toLocaleString().toFixed(2)both give4,000.50.
Preview messages
The Preview (with sample values) panel in the equation editor calculates the formula the same way as the popup. It uses the values of one sample feature from the layer. When the formula fails, the panel text is red. Below it, the panel shows A failed formula shows blank on the map.
| Message | When it shows | Popup on the map |
|---|---|---|
= <value>, such as = 12,508 |
The formula gives a number for the sample feature | The result |
Field not found: {name} |
The layer has no attribute with that name, for example because of a spelling mistake | Blank |
No sample value for {name} |
The sample feature has no value for that attribute | Blank for a feature with no value, and the result for the others |
Not a number: name |
The sample feature has a text value for that attribute, such as Bay |
Blank for a feature with a text value |
Result is not a number |
The formula gives true or false, or text, such as {a} > 5. 0 / 0 also gives this message. |
Blank |
Division by zero |
The formula divides a number other than zero by zero | Blank |
Syntax error |
The formula has a missing parenthesis, a misspelled function, or a name without braces. A formatting method or locale code in the wrong form also gives this message. | Blank |
The preview checks one feature only. A condition with a text branch, such as if({stock} > 0, {price}, 'Sold out'), shows a number when the sample feature takes the number branch. The popup is blank for every feature that takes the text branch.
In a Calculator popup, a user input such as {form_1} has no sample value. A formula that uses one shows No sample value for {form_1}.
Sample formulas
| Goal | Formula |
|---|---|
| Sum two attributes | {revenue} + {costs} |
| Compute a ratio, such as people per km² | {population} / {area} |
| Share of a total, as a percentage | ({part} / {total}) * 100 |
| Round a result | round({population} / {area}) |
| Round a result, with thousand separators | round({population} / {area}).toLocaleString() |
| Square a value | {side} ^ 2 |
| Remainder after dividing | {total} % {per_box} |
| Larger of two attributes | max({this_year}, {last_year}) |
| A value only when a condition is true | {stock} > 0 ? {price} : 0 |
| Change hectares to acres | {hectares} * 2.47105 |
| Use a user input | {area} * {form_1} |
| Combine attributes with user input | ({form_1} - {area}) / {area} * 100 |
Related
- How to use operators and functions in equations — worked examples for the operators and functions above.
- Popup tab controls
- How to build a calculator popup
- How to add a calculated value to a custom popup
- Report templating syntax — where the aggregate variable syntax (
{field:sum}, etc.) lives.