Add Average trait with integer average computation

[althonos]

Hi there !

This PR adds a new trait Average with two methods Average.average_ceil and Average.average_floor that uses bitwise operations to compute the average of two integers without overflowing. Reference is here, but this is probably known to people thanks to the Hacker's Delight.

Basically:

⌊(x+y)/2⌋ = (x&y) + ((x^y) >> 1)
⌈(x+y)/2⌉ = (x|y) - ((x^y) >> 1)

It comes with a blanket implementation for all Integer implementors that are closed under the -+|&^>> operators; in particular, this blanket implementation works for the BigInt and BigUint structs.

In terms of performance, this implementation is about 1.5 times faster than a naive implementation that checks for overflow, and as fast as an implementation that doesn't (i.e. (x+y)/2).

I'll add more tests for the std primitives, please do tell me if anything else needs to be changed.

[althonos]

bors retry

[bors]

🔒 Permission denied

Existing reviewers: click here to make althonos a reviewer

[cuviper]

Hi, sorry for the late review. This is a really neat trick!

Is there a reason you chose to make it a new trait, rather than adding to Integer? Especially since you provide a blanket implementation -- you can add the same on Integer, just with specific where clauses added to those new methods. That also makes it possible for someone to override with an even better version for their own type.

A few more tests would be nice to increase the floor/ceil coverage, like averaging a small negative with a big positive, and vice versa.

[althonos]

Hi !

Is there a reason you chose to make it a new trait, rather than adding to Integer? Especially since you provide a blanket implementation -- you can add the same on Integer, just with specific where clauses added to those new methods. That also makes it possible for someone to override with an even better version for their own type.

The blanket implementation needs BitAnd<&'b I, Output = I> + BitOr<&'b I, Output = I> + BitXor<&'b I, Output = I>, but that may not be needed a specialized implementation, so I believed adding this to Integer directly would make these traits necessary all the time.

I'll fix the other remarks this week.

[althonos]

Closing in favour of #31.