Merge pull request #543 from rust-osdev/enhancement/address-gap-panics

improve `VirtAddr` `Add` & `Sub` impls

Author: Freax13

src/addr.rs

@@ -364,13 +364,41 @@ impl fmt::Pointer for VirtAddr {
 
 impl Add<u64> for VirtAddr {
     type Output = Self;
+
+    #[cfg_attr(not(feature = "step_trait"), allow(rustdoc::broken_intra_doc_links))]
+    /// Add an offset to a virtual address.
+    ///
+    /// This function performs normal arithmetic addition and doesn't jump the
+    /// address gap. If you're looking for a successor operation that jumps the
+    /// address gap, use [`Step::forward`].
+    ///
+    /// # Panics
+    ///
+    /// This function will panic on overflow or if the result is not a
+    /// canonical address.
     #[inline]
     fn add(self, rhs: u64) -> Self::Output {
-        VirtAddr::new(self.0.checked_add(rhs).unwrap())
+        VirtAddr::try_new(
+            self.0
+                .checked_add(rhs)
+                .expect("attempt to add with overflow"),
+        )
+        .expect("attempt to add resulted in non-canonical virtual address")
     }
 }
 
 impl AddAssign<u64> for VirtAddr {
+    #[cfg_attr(not(feature = "step_trait"), allow(rustdoc::broken_intra_doc_links))]
+    /// Add an offset to a virtual address.
+    ///
+    /// This function performs normal arithmetic addition and doesn't jump the
+    /// address gap. If you're looking for a successor operation that jumps the
+    /// address gap, use [`Step::forward`].
+    ///
+    /// # Panics
+    ///
+    /// This function will panic on overflow or if the result is not a
+    /// canonical address.
     #[inline]
     fn add_assign(&mut self, rhs: u64) {
         *self = *self + rhs;
@@ -379,13 +407,41 @@ impl AddAssign<u64> for VirtAddr {
 
 impl Sub<u64> for VirtAddr {
     type Output = Self;
+
+    #[cfg_attr(not(feature = "step_trait"), allow(rustdoc::broken_intra_doc_links))]
+    /// Subtract an offset from a virtual address.
+    ///
+    /// This function performs normal arithmetic subtraction and doesn't jump
+    /// the address gap. If you're looking for a predecessor operation that
+    /// jumps the address gap, use [`Step::backward`].
+    ///
+    /// # Panics
+    ///
+    /// This function will panic on overflow or if the result is not a
+    /// canonical address.
     #[inline]
     fn sub(self, rhs: u64) -> Self::Output {
-        VirtAddr::new(self.0.checked_sub(rhs).unwrap())
+        VirtAddr::try_new(
+            self.0
+                .checked_sub(rhs)
+                .expect("attempt to subtract with overflow"),
+        )
+        .expect("attempt to subtract resulted in non-canonical virtual address")
     }
 }
 
 impl SubAssign<u64> for VirtAddr {
+    #[cfg_attr(not(feature = "step_trait"), allow(rustdoc::broken_intra_doc_links))]
+    /// Subtract an offset from a virtual address.
+    ///
+    /// This function performs normal arithmetic subtraction and doesn't jump
+    /// the address gap. If you're looking for a predecessor operation that
+    /// jumps the address gap, use [`Step::backward`].
+    ///
+    /// # Panics
+    ///
+    /// This function will panic on overflow or if the result is not a
+    /// canonical address.
     #[inline]
     fn sub_assign(&mut self, rhs: u64) {
         *self = *self - rhs;
@@ -394,9 +450,17 @@ impl SubAssign<u64> for VirtAddr {
 
 impl Sub<VirtAddr> for VirtAddr {
     type Output = u64;
+
+    /// Returns the difference between two addresses.
+    ///
+    /// # Panics
+    ///
+    /// This function will panic on overflow.
     #[inline]
     fn sub(self, rhs: VirtAddr) -> Self::Output {
-        self.as_u64().checked_sub(rhs.as_u64()).unwrap()
+        self.as_u64()
+            .checked_sub(rhs.as_u64())
+            .expect("attempt to subtract with overflow")
     }
 }