Add saturating_mul() and refactor Saturating into subtraits. Fixes #40.

[trepetti]

Hi all,

Taking the suggestion from #40, this pull request breaks out the saturating trait into three separate SaturatingAdd, SaturatingSub and SaturatingMul traits, borrowing the idea from Checked* and Wrapping*. In terms of native ops, SaturatingNeg would be an option on signed types once the saturating_neg() API is stable on signed integer primitives.

I know there is concern about breaking changes, so I was thinking that I could add a wrapping Saturating trait for backwards compatibility that retains the original functionality:

pub trait Saturating: SaturatingAdd + SaturatingSub {}
impl<T> Saturating for T where T: SaturatingAdd + SaturatingSub {}

This is not included in the current version, but I would be happy to add.

-Tom (trepetti@cs.columbia.edu)

[trepetti]

Also, it occurred to me that there is no harm in making a backwards compatible compound Saturating trait from SaturatingAdd + SaturatingSub + SaturatingMul since there are no primitive integer types that support the first two without SaturatingMul. So that may be an option, too.

[cuviper]

I know there is concern about breaking changes, so I was thinking that I could add a wrapping Saturating trait for backwards compatibility that retains the original functionality:

pub trait Saturating: SaturatingAdd + SaturatingSub {}
impl<T> Saturating for T where T: SaturatingAdd + SaturatingSub {}

Breaking changes are definitely a concern, and unfortunately this idea doesn't solve it. That would be fine for users of the trait, but it still breaks any implementors of the trait. Since the trait is not sealed, 3rd parties can and do implement it as well, e.g. extprim::u128. That concern applies to the constraint change on PrimInt too.

We can instead deprecate Saturating, nudging folks to use the new separate traits. PrimInt will be stuck with the old one, but that's life.

[trepetti]

Good point! Sorry I did not think that through entirely.

I restored the original Saturating trait and updated the doc comment to mention it has been deprecated. Similarly, I restored PrimInt to its original state with just Saturating and now expose all four Saturating, SaturatingAdd, SaturatingSub and SaturatingMul in lib.rs.

Let me know if there is a better way to go about deprecating Saturating, if that is the route you want to take. Looking back, it seemed that just mentioning as much in the doc comments is what has been done historically.

Thank you for looking at my pull request.

[cuviper]

Is this second macro pattern actually used? I think not, because your new traits don't have a generic RHS.

[cuviper]

bors r+

[bors]

Build succeeded:

• Test (beta)
• Test (1.8.0)
• Test (1.15.0)
• Test (nightly)
• Test (1.31.0)
• Test (stable)
• Format
• Test (1.20.0)
• Test (i586)
• No Std
• Test (1.26.0)