`Tol` Clause

Compares floating-point values with tolerance to rounding errors.

Syntax

comparison Tol [ tolerance ]

Parts

comparison: Mandatory expression that uses one or more comparison operators. Usually the tolerance applies to all comparisons in the given expression. But you can select which comparisons use the tolerance with the symbol ~ (tilde) written before the comparison operators.
tolerance: Optional floating-point literal used to calculate how near two values must compare to be equal.; The default is 1E-15.

Instructions

The clause Tol tries to give you a solution to a problem with floating-point calculations. Each time you use floating-point values in a calculation, it can cause more and more rounding errors. These errors can cause failures in comparisons of equality and inequality.

When you supply an expression with Tol, you can give a tolerance value, written as a floating-point literal. The typical tolerance is a very small number. The default is 0.000000000000001 or 1E-15. All applicable comparisons in the expression change how they are calculated. The table that follows gives all the equivalent expressions.

Equivalent expressions
With `Tol`	Without `Tol`
`x = y Tol`	`Math.Abs(x - y) <= Math.Max(Math.Abs(x), Math.Abs(y)) * 1E-15`
`x <> y Tol`	`Math.Abs(x - y) > Math.Max(Math.Abs(x), Math.Abs(y)) * 1E-15`
`x <= y Tol`	`Math.Abs(x - y) <= Math.Max(Math.Abs(x), Math.Abs(y)) * 1E-15 Or Else x < y`
`x >= y Tol`	`Math.Abs(x - y) <= Math.Max(Math.Abs(x), Math.Abs(y)) * 1E-15 Or Else x > y`
`x < y Tol`	`Math.Abs(x - y) > Math.Max(Math.Abs(x), Math.Abs(y)) * 1E-15 And Then x < y`
`x > y Tol`	`Math.Abs(x - y) > Math.Max(Math.Abs(x), Math.Abs(y)) * 1E-15 And Then x > y`

Note: Comparisons with tolerance are always slower than the usual comparisons. If performance is important, try to use only = or <>.

Mixing comparisons with and without tolerances

You can have comparisons with and without tolerances in one expression. But only comparisons that have a floating-point value are applicable.

If you must have a mixture of comparison tolerances, you can use a special indicator. The tilde (~) identifies a comparison that uses the supplied tolerance. You write the tilde before the comparison operator. For example, ~=, ~<>, ~<=, ~>=, ~<, and ~>.

It is an error to write a tilde without Tol on the expression. It is also an error to write a tilde on a comparison that does not compare floating-point values. But you can also use the tilde to show always which are floating-point comparisons.

Examples

Sub test a, b As Real64
    PrintLine $"{a} = {b} is {a = b Tol}"
End

test 1000000000000.01, 1000000000000.011
test 100.01, 100.011

Output:

1000000000000.01 = 1000000000000.011 is true
100.01 = 100.011 is false

Tol Clause