Introduction to FormulaScript

To create dynamic and useful calculators it is important to be able to leverage ConvertCalculator's powerful formula system named FormulaScript.

Introduction

First of all, what exactly are formulas? Formulas are a collection of operations on values to produce a result. Right.. that does not seem to help, but let's start with an example. 1 + 2 is a formula that when calculated produces the result 3. In this example 1 and 2 are values, addition is the operation (denoted by the operator +), and 3 is the result. As you would expect, FormulaScript has all the common arithmetic operators: + for addition, - for subtraction, * for multiplication, / for division, and ^ for exponentiation.

FormulaScript conforms with the standard operator precedent, but you may use brackets to change the order in which the operations are run: 3 * (1 + 2). Note that + and - have a dual function since they can be used to add and subtract two values, but can also be used to turn a value positive and negative respectively: +(5 - 10) and -(5 + 10).

Basics

Until now FormulaScript seems like a glorified calculator, but FormulaScript offers more powerful features that allow you to build interesting calculators.

Numbers

As shown above, you can use numbers in your calculations. Numbers can be whole numbers such as 1, 2 and 912748127, but they can also have fractional values behind the decimal separator . such as 1.5, 0.37182 and 1.0. Note that for decimal numbers that lead with a 0 you can omit this 0, so 0.23 can also be .23. To improve readability for large numbers you can insert _ to separate the digits e.g. 1_000_000, note that the underscores have no meaning and are disregarded entirely meaning they can be inserted anywhere in the number except at the start e.g. _10.

Strings

FormulaScript also allows you to work with textual data known as strings. Strings are any text enclosed by quotes e.g. "This is a string" and "Strings can also have numbers 1191847" and 'Strings can be enclosed by single quotes as well'. To combine two strings you can use the concatenation operator & e.g. "A" & "B" to get "AB". It is possible to use quotes inside of strings just make sure the outer quotes are not used within the string e.g. "This is a 'string' with quotes" or 'this is a "string" with quotes'.

Booleans

Sometimes it is useful to encode if values are true or false. In such cases it is entirely possible to use the numbers 1 and 0 to define true of false. However, since this is a common pattern, FormulaScript allows you to use the literal words true and false. Note that these words are case-insensitive so you could also write True, FALSE or even tRuE. Boolean values by themselves are not extremely useful, but boolean values happen to be the results of comparisons.

Comparisons

Comparisons are how you compare two values with each other. For example, you could check if a number is smaller than another number 10 < 15 and in this case the result of this comparison is true, because 10 is smaller than 15.

  • To check if two values are bigger or smaller you can use > and < respectively.
  • To check if two values are greater or equal use >= or less than or equal use <= .
  • To check if two values are the same you can use = e.g. (10 + 1) = 11.
  • To check if two values are NOT similar use <> e.g. 10 <> 11.

You can use compare strings too, but only to check if they are the same e.g. "A" = "A" or "A" <> "B".

Note that comparisons have the lowest precedence in formulas so 2 < 1 + 1 is interpreted as 2 < (1 + 1).

Functions

The real power of FormulaScript comes from functions. Functions are collections of code written for you to achieve some common or even complex case. To use functions you must first define its name, then give the arguments, delimited by comma's or semicolon's, enclosed by parentheses: FUNCTION(argument_1, argument_2; argument_3, ...; argument_n). Note that function names are case-insensitive. ConvertCalculator provides a lot of functions for different use-cases such as logical operations, financial and statistical calculations, and math functions. To see a full list of functions refer to this overview.

References

Now all of these features are useless if you cannot interact with dynamic values which come from your forms. FormulaScript allows you to reference values by a name. The names you can use depend on the elements you have added to your calculator as well as the variables you have added. A common name is QA which is the default name for the first question element you added to your calculator. To use this value you can reference it in a formula either by itself, then it will just return the value QA, or in some sort of calculation (QA * 5) - 10_000. Every feature explained above allows references instead of a normal value.

ConvertCalculator Icon