REBOL 3 Functions: round

Description

"Rounding is meant to loose precision in a controlled way." -- Volker Nitsch

The round function is quite flexible. With the various refinements and the scale option, you can easily round in various ways. Most of the refinements are mutually exclusive--that is, you should use only one of them--the /to refinement is an obvious exception; it can be combined with any other refinement.

By default, round returns the nearest integer, with halves rounded up (away from zero).

probe round 1.4999
1

probe round 1.5
2

probe round -1.5
-2

If the result of the rounding operation is a number! with no decimal component, and the SCALE value is not time! or money!, an integer will be returned. This makes it easy to use the result of ROUND directly with iterator functions such as LOOP and REPEAT.

The /TO refinment controls the "precision" of the rounding. That is, the result will be a multiple of the SCALE parameter. In order to round to a given number of decimal places, you don't pass in the number of decimal places, but rather the "level of precision" they represent. For example, to round to two decimal places, often used for money values, you would do this:

probe round/to $1.333 .01
$0.5558830792256812207833088

To round to the nearest 1/8, often used for interest rates, you would do this:

probe round/to 1.333 .125
1.375

To round to the nearst 1K increment (e.g. 1024 bytes):

probe round/to 123'456 1024
123904

If the /TO refinement is used, and SCALE is a time! or money! value, the result will be coerced to that type. If SCALE is not used, or is not a time! or money! value, the datatype of the result will be the same as the valued being rounded.

The /EVEN refinement is designed to reduce bias when rounding large groups of values. It is sometimes called Banker's rounding, or statistical rounding. For cases where the final digit of a number is 5 (e.g. 1.5 or 15), the previous digit will be rounded to an even result (2, 4, etc.).

repeat i 10 [val: i + .5 print [val round/even val]]
10.5 10

repeat i 10 [val: i * 10 + 5 print [val round/even/to val 10]]
105 100

The /DOWN refinement rounds toward zero, ignoring discarded digits. It is often called "truncate".

probe round/down 1.999
1

probe round/down -1.999
-1

probe round/down/to 1999 1000
1000

probe round/down/to 1999 500
1500

The /HALF-DOWN refinement causes halves to round toward zero; by default they are rounded up.

probe round/half-down 1.5
1

probe round/half-down -1.5
-1

probe round/half-down 1.50000000001
2

probe round/half-down -1.50000000001
-2

The /HALF-CEILING refinement causes halves to round in a positive direction; by default they are rounded up (away from zero). This works like the default behavior for positive values, but is not the same for negative values.

probe round -1.5
-2

probe round/half-ceiling -1.5
-1

/FLOOR causes numbers with any decimal component to be rounded in a negative direction. It works like /DOWN for positive numbers, but not for negative numbers.

round/floor 1.999

round/floor -1.01

round/floor -1.00000000001

/CEILING is the reverse of /FLOOR; numbers with any decimal component are rounded in a positive direction.

round/ceiling 1.01

round/ceiling 1.0000000001

round/ceiling -1.999

If you are rounding extremely large numbers (e.g. 562'949'953'421'314), or using very high precision decimal values (e.g. 13 or more decimal places), you may run up against REBOL's native limits for values and its internal rounding rules. The ROUND function is a mezzanine and has no control over that behavior.

Sometimes, it might appear that ROUND is doing something strange, so before submitting a bug to RAMBO, think about what you're actually asking it to do. For example, look at the results from this piece of code:

repeat i 10 [
    scale: .9 + (i * .01) 
    print [scale  round/down/to 10.55 scale]
]
1.0 10.0

The results approach 10.55 for values from 0.91 to 0.95, but then jump back when using values in the range 0.96 to 0.99. Those are the expected results, because you're truncating, that is, truncating to the nearest multiple of SCALE.

The design and development of the ROUND function involved many members of the REBOL community. There was much debate about the interface (one function with refinement versus individual functions for each rounding type, what words to use for parameter names, behavior with regards to type coercion).