Add method for computing the difference of two unsigned integers in a signed

[davidzeng0]

Proposal

Problem statement

async fn seek(&mut self, seek: SeekFrom) -> Result<u64> {
  match seek {
    SeekFrom::Current(pos) => self.seek_relative(pos).await,
    SeekFrom::End(pos) => ...
    SeekFrom::Start(pos: u64) => {
      if !self.stream_position_fast() {
        return self.seek_inner(seek).await;
      }

      let stream_pos: u64 = self.stream_position().await?;
 
      /* want to make sure pos - stream_pos can fit in an i64 without overflow */
      /* stream_pos = u64::MAX, pos = 0, seek_relative = -1: wrong */
      self.seek_relative(pos.wrapping_sub(stream_pos) as i64).await
    }
  }
}

Motivating examples or use cases

let (pos: i64, overflow: bool) = pos.overflowing_difference_signed(stream_pos);

if overflow {
  // buf reader seek underlying stream
  self.seek_inner(seek).await
} else {
  // seek relative, which checks if `pos` is within the current buffer
  self.seek_relative(pos)
}

Solution sketch

Benchmarking
https://godbolt.org/z/dxrP4d9vT

Implementation
https://github.com/davidzeng0/xx-core/blob/main/src/impls/uint.rs#L12

Links and related work

rust-lang/rust#117476

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[scottmcm]

Given that we have https://doc.rust-lang.org/std/primitive.u32.html#method.checked_add_signed and friends now, it does seem plausible to have something like this. Naming it is hard, though -- it's like sub_ptr but for integers.

[davidzeng0]

A little off topic, but that does remind me, is there a reason why checked_sub_signed does not exist? Maybe I can open another ACP for that

[kennytm]

checked_sub_signed

For most cases a.xxxx_sub_signed(b) is equivalent to a.xxxx_add_signed(-b), but there is an edge case b == i64::MIN so I think it should also exist.

Naming

I'd prefer one of xxxx_diff(), xxxx_signed_diff() or xxxx_signed_sub(). Given .abs_diff() I don't think we should spell out "difference" fully.

[Amanieu]

We discussed this in the libs-api meeting today. We think there is a good case for having this function in the standard library, however we prefer the following signature instead:

impl Unsigned {
    fn checked_signed_diff(self, other: Unsigned) -> Option<Signed>;
}

We are accepting the ACP with this modified signature.

[davidzeng0]

It would also make sense then to have

impl Signed {
    fn checked_unsigned_diff(...)
}

in the implementation PR, for fullness