[Mesa-dev] [PATCH 1/3] mesa: Replace _mesa_round_to_even() with _mesa_roundeven().

[Matt Turner]

On Thu, Mar 12, 2015 at 2:59 PM, Carl Worth <cworth at cworth.org> wrote:
> On Thu, Mar 12 2015, Matt Turner wrote:
>> +/* The C standard library has functions round()/rint()/nearbyint() that round
>> + * their arguments according to the rounding mode set in the floating-point
>> + * control register. While there are trunc()/ceil()/floor() functions that do
>> + * a specific operation without modifying the rounding mode, there is no
>> + * roundeven() in any version of C.
>> + *
>> + * Technical Specification 18661 (ISO/IEC TS 18661-1:2014) adds roundeven(),
>> + * but it's unfortunately not implemented by glibc.
>> + *
>> + * This implementation differs in that it does not raise the inexact exception.
>> + */
>
> This documentation needs the actual description of the behavior of the
> function. Most of the above comment is commentary on the implementation
> itself.
>
> Perhaps something like the following?
>
>         Round \x to the nearest even integer (returned in floating-point
>         format).

I didn't read this closely enough the first time, but if I had I think
I could have short circuited a lot of the confusion.

To clarify, the "roundeven" function rounds to the nearest integer,
with halfway cases rounding to the even integer. E.g., 1.5 rounds to
2.0, but 2.5 also rounds to 2.0. This is known, less confusingly, as
"half-to-even" in some other places [1]. It's the same as round(3),
except for the behavior of the halfway cases.

This behavior is evidently simpler for hardware to implement, so it's
what IEEE-754 specifies. It's because of this behavior that we get the
somewhat surprising result that nextafterf(0.5, 0.0) + 0.5 == 1.0 --
which is itself the reason that the typical trunc(x + 0.5) is subtly
broken. See [2].

Sorry for the confusion, and thanks for reviewing!

[1] http://userguide.icu-project.org/formatparse/numbers/rounding-modes
[2] http://ericlippert.com/2013/05/16/spot-the-defect-rounding-part-two/