Rounding modes

  Last updated July 19, 2019

Fastly VCL provides access to various rounding modes by way of independent functions for rounding values. These functions have explicit rounding modes. There is no stateful interface to set a "current" rounding mode.

Fastly VCL does not provide interfaces to round values to a given number of significant figures, to a given multiple, or to a given power.

Tie-breaking when rounding to nearest

The roundoff errors introduced by rounding values to their nearest integers are symmetric, except for treatment of the exact midpoint between adjacent integers.

That is, for every value that gets rounded up (such as 3.77 rounding up to the nearest integer 4.0), there is a corresponding value (3.23) which is rounded down by the same amount. This can be seen visually:

       Nearest integer is 3.0 ‹────┤ ├────› Nearest integer is 4.0
    
         3.23  3.24  3.25          3.5           3.75  3.76  3.77
    ╸╸╸━━━┷━━━━━┷━━━━━┷━━━╺╺╺ ╸╸╸━━━┷━━━╺╺╺ ╸╸╸━━━┷━━━━━┷━━━━━┷━━━╺╺╺
          ╰─────────────────────────┴─────────────────────────╯ Equidistant around 3.5

Rounding to the nearest integer requires a tie-breaking rule for when the fractional part of a value is exactly 0.5. There are several ways to break these ties, enumerated in the "to nearest" rounding modes below.

Overview

Example values:

Input ceil floor trunc round roundeven roundhalfup roundhalfdown
-1.8 -1.0 -2.0 -1.0 -2.0 -2.0 -2.0 -2.0
-1.5 -1.0 -2.0 -1.0 -2.0 -2.0 -1.0 -2.0
-1.2 -1.0 -2.0 -1.0 -1.0 -1.0 -1.0 -1.0
-0.5 -0.0 -1.0 -0.0 -1.0 -0.0 -0.0 -1.0
0.5 1.0 0.0 0.0 1.0 0.0 1.0 0.0
1.2 2.0 1.0 1.0 1.0 1.0 1.0 1.0
1.5 2.0 1.0 1.0 2.0 2.0 2.0 1.0
1.8 2.0 1.0 1.0 2.0 2.0 2.0 2.0

A visual representation of the same:

                        ‹──         ──›                           ‹──           ──›
                       -1.8  -1.5  -1.2      -0.5       0.5       1.2    1.5    1.8
                   ╸╸╸━━━┷━━━━━┷━━━━━┷━━╺╺ ╸╸━━┷━━╺╺ ╸╸━━┷━━╺╺ ╸╸━━┷━━━━━━┷━━━━━━┷━━━╺╺╺
"Direct" modes:
math.ceil               ──›   ──›   ──›       ──›       ──›       ──›    ──›    ──›
math.floor              ‹──   ‹──   ‹──       ‹──       ‹──       ‹──    ‹──    ‹──
math.trunc              ──›   ──›   ──›       ──›       ‹──       ‹──    ‹──    ‹──
    
"To nearest" modes:
math.round              ‹──   ‹──   ──›       ‹──       ──›       ‹──    ──›    ──›
math.roundeven          ‹──   ‹──   ──›       ──›       ‹──       ‹──    ──›    ──›
math.roundhalfup        ‹──   ──›   ──›       ──›       ──›       ‹──    ──›    ──›
math.roundhalfdown      ‹──   ‹──   ──›       ‹──       ‹──       ‹──    ‹──    ‹──

"Direct" rounding modes

"To nearest" rounding modes

All of the following modes round non-tie values to their nearest integer. These modes differ only in their treatment of ties.

Floating point numbers have more computational nuances than are described by the cursory discussion of biases here. For more details, see What every computer scientist should know about floating-point arithmetic.

Back to Top