Calculation Formulas

Back to Calculation Formulas Overview
Back to Functions Overview

Function "ToNum"

ToNum(arg)

Function: Tries to convert the given argument into a number or set of numbers.

Generates a runtime error if that is not possible (for example, if the argument is a text that contains characters that are not part of a number representation, like letters). If you are unsure if a certain argument can be converted into a number without an error, and you want to avoid this error, then use the companion function IsNum to first check if the argument can be converted at all, together with the function If (see the examples below.)

For example, can be used to convert a profile field of type Text that contains only numbers to the type Number, which can then be used in contexts that require the type Number (such as number operators and functions that require a number argument).

Return-Type: Number or Number Set

Arguments:
arg - can be of any type:

• Text: The text is parsed and an attempt is made to convert it into a number. This is possible if the text contains only digits and optionally a leading minus sign (otherwise an error is generated). A single number is returned.
• Text Set: All elements in the set are parsed and converted into numbers (if possible, otherwise an error is generated). A Number Set that contains all these numbers is returned.
• Boolean: The boolean value "true" is converted into the number "1", the boolean value "false" is converted into the number "0". This number is then returned.
• Number or Number Set: The argument is returned unchanged.

Examples:
ToNum("12345")
ToNum(&AGE;)
ToNum(true)
ToNum("123" + "456")
If(IsNum(&TEXTFIELD;), ToNum(&TEXTFIELD;), 0)

Note: The result of the second-to-last example will not be the number 579, but will instead be the number 123456. The string concatenation operator "+" is first applied to the two text strings and then the resulting string is converted into a number.

The last example shows how ToNum is used together with IsNum and If, to make sure that no runtime error is generated: If the field TEXTFIELD contains a number, then this number is supposed to be used. If not, then instead the default of "zero (0)" is to be used. So the result of this If function is in turn a number: Either the number that was parsed from TEXTFIELD, or the number "0". Thus, the result of the If function can safely be used in a context where a Number type is required, without fearing a runtime error if TEXTFIELD should contain a non-number text.