Add midpoint function for all integers and floating numbers

[Urgau]

This pull-request adds the midpoint function to {u,i}{8,16,32,64,128,size}, NonZeroU{8,16,32,64,size} and f{32,64}.

This new function is analog to the C++ midpoint function, and basically compute (a + b) / 2 with a rounding towards a negative infinity in the case of integers. Or simply said: midpoint(a, b) is (a + b) >> 1 as if it were performed in a sufficiently-large signed integral type.

Note that unlike the C++ function this pull-request does not implement this function on pointers (*const T or *mut T). This could be implemented in a future pull-request if desire.

Implementation

For f32 and f64 the implementation in based on the libcxx one. I originally tried many different approach but all of them failed or lead me with a poor version of the libcxx. Note that libstdc++ has a very similar one; Microsoft STL implementation is also basically the same as libcxx. It unfortunately doesn't seems like a better way exist.

For unsigned integers I created the macro midpoint_impl!, this macro has two branches:

• The first one take $SelfT and is used when there is no unsigned integer with at least the double of bits. The code simply use this formula a + (b - a) / 2 with the arguments in the correct order and signs to have the good rounding.
• The second branch is used when a $WideT (at least double of bits as $SelfT) is provided, using a wider number means that no overflow can occur, this greatly improve the codegen (no branch and less instructions).

For signed integers the code basically forwards the signed numbers to the unsigned version of midpoint by mapping the signed numbers to their unsigned numbers (ex: i8 [-128; 127] to [0; 255]) and vice versa.
I originally created a version that worked directly on the signed numbers but the code was "ugly" and not understandable. Despite this mapping "overhead" the codegen is better than my most optimized version on signed integers.

Note that in the case of unsigned numbers I tried to be smart and used #[cfg(target_pointer_width = "64")] to determine if using the wide version was better or not by looking at the assembly on godbolt. This was applied to u32, u64 and usize and doesn't change the behavior only the assembly code generated.

[rust-highfive]

r? @joshtriplett

(rust-highfive has picked a reviewer for you, use r? to override)

[falk-hueffner]

For unsigned integers, it might be worthwhile to consider a branchless version using the well-known fact that the average rounding down can be calculated by ((a ^ b) >> 1) + (a & b), e.g.

pub const fn midpoint(a: u64, b: u64) -> u64 {
    let b1 = b + ((b < a) as u64);
    return ((a ^ b1) >> 1) + (a & b1);
}

However, in many applications the branch will be perfectly predictable, in which case the method in this PR would probably be faster.

[Urgau]

I've done some comparisons on x86_64 with -C opt-level=3 between my implementation and your proposed implementation:

• u16: +1 instruction, 211 vs 342 cycles (for 100 iterations), more expensive
• u32: +1 instruction, 209 vs 333 cycles (for 100 iterations), more expensive
• u64: -2 instructions, 407 vs 333 cycles (for 100 iterations), less expensive
• u128: -5 instructions, -1 branch, 1404 vs 1403 cycles (for 100 iterations), similar
• i16: +2 instructions, 283 vs 433 cycles (for 100 iterations), more expensive
• i32: +3 instructions, 233 vs 407 cycles (for 100 iterations), more expensive
• i64: -2 instructions, 509 vs 408 cycles (for 100 iterations), less expensive
• i128: -6 instructions, -1 branch, 1604 vs 1505 cycles (for 100 iterations), similar

It seems that given the current optimization of LLVM (and GCC in a similar manner), my understanding of llvm-mca and x86_64 (witch is not much) that your proposed implementation is better for u64 and u128 (and by incidence also i64 and i128).

If you (@falk-hueffner) or @joshtriplett think this is worthwhile I'm happy to change my implementation to use your solution for u64 and u128. (I may also if I find the time change it, just to simplify the code and remove the #[cfg])

[Urgau]

I've rebase the branch, inline the implementation of the signed numbers and added the function to NonZeroU{8,16,32,64,size} (NonZeroI{..} is a bit tricky because of the opposites numbers that can output 0, so I left it out for now).

[joshtriplett]

r? @rust-lang/libs-api

[cuviper]

FWIW, num-integer has similar methods in its Average trait, offering average_ceil and average_floor. It does use the same branchless implementation from Hacker's Delight too. (cc rust-num/num-integer#31)

At least we won't collide names if we stick with midpoint here...

[yaahc]

I'm reassigning this PR because I'm taking a break from the review rotation for a little while. Thank you for your patience.

r? rust-lang/libs-api