BOOST_PP_MUL documentation regarding efficiency is confusing

[Jeffrey Lee Hellrung, Jr. <jeffrey.hellrung@…>]

From

http://www.boost.org/libs/preprocessor/doc/ref/mul.html

"This macro is the most efficient when x is less than or equal to y. However, the efficiency gain is not worth actually comparing the two arguments prior to invocation. In other words, x should be the value that is most likely to be the largest of the two operands."

The first sentence suggest that x <= y is more efficient; the last sentence suggests that x >= y is more efficient. I'm confused :(

[Jeffrey Lee Hellrung, Jr. <jeffrey.hellrung@…>]

It looks like the exact same wording is used for all of

BOOST_PP_ADD
BOOST_PP_ADD_D
BOOST_PP_MUL
BOOST_PP_MUL_D

[alex.cole@…]

I just wanted to bump this ticket, since I came across the exact same thing in the BOOST_PP_ADD documentation today. The ticket already notes that macro as well, so I figured this was better than a new ticket.

[Alex Cole <alex.cole@…>]

I've done some digging, and it seems BOOST_PP_ADD internally works by decrementing the second parameter while incrementing the first parameter in a BOOST_PP_WHILE loop until the second parameter is zero. I'm not the author, but this to me implies that having the second parameter likely to be smaller is the most efficient method, as it will result in slightly less iterations.

So by my reading of the code, the second statement that "In other words, x should be the value that is most likely to be the largest of the two operands." is the correct one.

[Edward Diener]

I have updated this on the 'develop' branch and will update the 'master' branch before the next release.

[Edward Diener]

This has ben updated so that the correct explanation is in the Boost 1.58 release.