Bug 17418 – opCmp return value unclear

When implementing an opCmp, I pretty much always need to look up how it is defined and the specification constantly disappoints but not saying a word of what the function should actually return for which case. you can kind of extract that info from the re-write rules, but why make it so difficult and not just say something like RETURN A B -1 2 1 0 2 2 +1 1 2 (or whatever the correct numbers are) Link to unclear definition: http://dlang.org/spec/operatoroverloading.html#compare

I would point out that the return values don't need to be spcecific numbers. They only need to be < 0, == 0, or > 0. And requiring them to be -1, 0, and +1 would be less efficient in a number of cases. Now, looking over that page, I agree that it's not as clear as it should be, and the problem seems to be that it's focused on how the compiler is going to take the return value and use that to generate the correct code for the comparison rather than what the programmer needs to do with opCmp to make it work correctly. But from the perspective of the person writing opCmp, opCmp should return a value < 0 if lhs < rhs, 0 if lhs == rhs, and a value > 0 if lhs > rhs.

Meanwhile the definition [1] defines three cases returning an int (<, ==, >), but as far as I know, it's also possible to have reals as return types and in this cases NaN is a fourth possible result. [1] https://dlang.org/phobos/object.html#.Object.opCmp

This has been added to spec.