Tracking Issue for `int_abs_diff`

[orlp]

Feature gate: #![feature(int_abs_diff)]

This is a tracking issue for a method to compute the absolute difference between two integers.

Public API

This adds the method T::abs_diff(other: T) -> U to all built-in Rust integer types, both signed and unsigned, where U is the unsigned equivalent of T (or just T itself it it already was unsigned). This method always computes the mathematical absolute difference between the two numbers correctly, without any risk of overflow. Because the output is an unsigned type the result is always representable.

Steps / History

• Issue: Add a method for computing the absolute difference between unsigned integers #62111
  Note: scope has been expanded to implement abs_diff for all integers, not just unsigned integers.
• Implementation: Added abs_diff for integer types. #88780
• Final comment period (FCP)
• Stabilization PR: Stabilize int_abs_diff in 1.60.0. #93735

Unresolved Questions

• None yet.

[tspiteri]

For signed, I would prefer the name unsigned_abs_diff as it returns a different type, making it consistent with unsigned_abs.

[orlp]

For unsigned_abs a distinction needed to be made with a pre-existing abs function. We don't have to worry about that backwards compatibility here.

[tspiteri]

But I found i64::abs_diff returning u64 very surprising: a method that operates on two numbers to give a new number silently changes the type. The only other i64 method returning u64 is unsigned_abs, and its name clearly indicates that.

There are other methods that never return a negative value, and they still return the same type. For example i64::abs itself returns i64, not u64, even though it can overflow as well on signed (although only for one value).

[shreepads]

Current state:

u32vec.iter().fold(0, |acc, x| acc + (*x as i32 - median as i32).abs() as u32)

Desired state:

u32vec.iter().fold(0, |acc, x| acc + x.abs_diff(median))        // as per experimental API for u32

[MarcelRobitaille]

@shreepads I have done this:

fn abs_diff(a: u32, b: u32) -> u32 {
  if a > b {
    a - b
  } else {
    b - a
  }
}

Somehow this is cleaner to me than casting to signed. I think it's more efficient too? Not as nice as if it were a built-in method, but still cleans up your fold, no?

[rrokkam]

@tspiteri, if you want abs_diff to return an i64, what behavior do you suggest for the case when abs_diff can't fit in an i64? Panic? Change return type to result? I see no appealing options.

(The difference between two i64s can be 64 bits long, and i64 has 63 bits for magnitude)

[tspiteri]

@rrokkam I would expect the same overflow behaviour as abs itself.

[nhamovitz]

(FWIW, because I'm newish to Rust —)

I very much disagree — it doesn't make sense to me to ship an overflowing API when a 100% correct + infallible algorithm exists. I'll concede some case for naming it unsigned_abs_diff to highlight that the type is changing (although IMO that's what the function signature + your tooling is there for), but allowing overflows seems bad.

[shreepads]

@shreepads I have done this:

fn abs_diff(a: u32, b: u32) -> u32 {
  if a > b {
    a - b
  } else {
    b - a
  }
}

Somehow this is cleaner to me than casting to signed. I think it's more efficient too? Not as nice as if it were a built-in method, but still cleans up your fold, no?

Thanks @MarcelRobitaille , yes that is much better and would work till such time as a method is available in the std library - (there is already such a method in the experimental API for u32)...

I was only hacking one of the Advent of Code puzzles (https://adventofcode.com/2021/day/7) so didn't mind the casting/ re-casting..

[m-ou-se]

@rfcbot merge

[rfcbot]

Team member @m-ou-se has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @yaahc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.