Formulas under the hood: details and examples

Conversion to numbers

In all functions and algebraic operators where a numeric argument is expected, the formula language will try to convert an argument of another type into a number using these rules:

• Strings that can be converted to numbers are converted (e.g., "25" becomes 25).
• Strings that cannot be converted to numbers become 0 (including empty strings).
• TRUE is converted to 1.
• FALSE is converted to 0.
• + does not work as a concatenator (use the concat function instead).
• If a vector of numbers is supplied, operation is done on the first element of the vector only.
• If an argument is a function, it is calculated first and its result is passed as an argument, which is then converted to a number according to the rules described above.

All numbers are treated as double-precision floating point numbers (“numeric” type in R).

Example usages of algebraic functions are provided below:

toNumber

The function toNumber(x) can be used to explicitly convert a value into a number using the same rules described above. It is equivalent to x*1 but can be more readable in some cases.

Signature: toNumber(x)

Examples:

• toNumber("25") returns 25.
• toNumber("abc") returns 0.
• toNumber(c("25", "abc")) returns 25 because the first element of the vector is considered.

Conversion to Booleans

In all functions and Boolean operators where a Boolean argument is expected, the formula language will try to convert an argument of another type into a Boolean using the x!=0 rule, where x is the argument value converted to a number according to the rules described above.

This means:

Conversion to strings

In all functions where a string argument is expected, the formula language will try to convert an argument of another type into a string using these rules:

• Numbers are converted to their string representation, e.g.:
  • 25 becomes "25",
  • -0.001 becomes "-0.001", and
  • 1234567.89 becomes "1234567.89".
• TRUE is converted to "1".
• FALSE is converted to "0".
• undefined values remain undefined.

toString

The function toString(x) can be used to explicitly convert a single value into a string using the same rules described above. It is equivalent to concat(x) if x is a single value (not a vector).

Signature: toString(x)

Examples:

• toString(25) returns "25".
• toString(-0.001) returns "-0.001".
• toString(c(1234567.89, 4)) returns "1234567.89".

Undefined values

If an undefined value is returned in a redirect formula, the redirect is not performed.

Undefined values are contagious and propagate through the formula. This means that if an argument of a function is undefined, the function will return undefined as well. For example, if answer(1234) returns undefined, then answer(1234) + 5 will also return undefined.

Undefined values are only automatically converted to 0 in the context of respondent weightings. In all other contexts, they remain undefined and propagate through the formula.

What if there are too many arguments?

If a function is supplied with more arguments than it expects, the extra arguments are ignored. For example, round(12.2, 2) will return the same result as round(12.2) because the second argument (2) is ignored.

If there is a an undefined value among the extra ignored arguments, it does not affect the result of the function. For example, round(12.2, 2, undefined) will still return the same result as round(12.2) because the extra arguments are ignored.

Custom functions

Functions prefixed with c_ (e.g. c_responseEnd) are treated as custom functions (specified in customisations) and skip formula validation.

These functions apply to pipe-in formulas in the respondent interface only. They are not valid in reports (e.g. for Deep probe).

While custom functions are not subject to the unknown function validation, the expression passed as an argument must still be syntactically valid. For example, c_answer(32233dsfsfgg) will fail validation as the argument (32233dsfsfgg) is not a valid expression.