From 5c690555f226909786a43b4bf0dc58f8bffa7a6b Mon Sep 17 00:00:00 2001 From: Stovent Date: Fri, 11 Feb 2022 15:25:51 -0500 Subject: [PATCH] Correct signed bit int documentation --- library/core/src/num/int_macros.rs | 74 ++++++++++++++++++++++++++---- 1 file changed, 64 insertions(+), 10 deletions(-) diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs index 4e51b90b835..0cd64753f9b 100644 --- a/library/core/src/num/int_macros.rs +++ b/library/core/src/num/int_macros.rs @@ -1514,15 +1514,41 @@ pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) { /// Calculates `self + rhs + carry` without the ability to overflow. /// - /// Performs "ternary addition" which takes in an extra bit to add, and may return an - /// additional bit of overflow. This allows for chaining together multiple additions - /// to create "big integers" which represent larger values. - /// - #[doc = concat!("This can be thought of as a ", stringify!($BITS), "-bit \"full adder\", in the electronics sense.")] + /// Performs "signed ternary addition" which takes in an extra bit to add, and may return an + /// additional bit of overflow. This signed function is used only on the highest-ordered data, + /// for which the signed overflow result indicates whether the big integer overflowed or not. /// /// # Examples /// - /// Basic usage + /// Standard signed bit integer implementation + /// + /// ```rs + /// #![feature(bigint_helper_methods)] + /// struct I16 { + /// pub low: u8, // Low-order bytes has to be unsigned. + /// /// Most Significant Data has to be of the same signedness as the desired type. + /// /// So u8 to implement U16, i8 to implement I16. + /// pub high: i8, + /// } + /// + /// impl I16 { + /// /// Adds `rhs` to `self` and returns true if signed overflow occurs, false otherwise. + /// pub fn overflowing_add(&mut self, rhs: Self) -> bool { + /// let (low_res, low_carry) = self.low.carrying_add(rhs.low, false); + /// + /// // The signed `carrying_add` method is used to detect signed overflow. + /// let (high_res, high_carry) = self.high.carrying_add(rhs.high, low_carry); + /// + /// self.low = low_res; + /// self.high = high_res; + /// high_carry + /// } + /// } + /// + /// fn main() {} + /// ``` + /// + /// General behavior /// /// ``` /// #![feature(bigint_helper_methods)] @@ -1612,13 +1638,41 @@ pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) { /// Calculates `self - rhs - borrow` without the ability to overflow. /// - /// Performs "ternary subtraction" which takes in an extra bit to subtract, and may return - /// an additional bit of overflow. This allows for chaining together multiple subtractions - /// to create "big integers" which represent larger values. + /// Performs "signed ternary subtraction" which takes in an extra bit to subtract, and may return an + /// additional bit of overflow. This signed function is used only on the highest-ordered data, + /// for which the signed overflow result indicates whether the big integer overflowed or not. /// /// # Examples /// - /// Basic usage + /// Standard signed bit integer implementation + /// + /// ```rs + /// #![feature(bigint_helper_methods)] + /// struct I16 { + /// pub low: u8, // Low-order bytes has to be unsigned. + /// /// Most Significant Data has to be of the same signedness as the desired type. + /// /// So u8 to implement U16, i8 to implement I16. + /// pub high: i8, + /// } + /// + /// impl I16 { + /// /// Subtracts `rhs` from `self` and returns true if signed overflow occurs, false otherwise. + /// pub fn overflowing_sub(&mut self, rhs: Self) -> bool { + /// let (low_res, low_carry) = self.low.borrowing_sub(rhs.low, false); + /// + /// // The signed `borrowing_sub` method is used to detect signed overflow. + /// let (high_res, high_carry) = self.high.borrowing_sub(rhs.high, low_carry); + /// + /// self.low = low_res; + /// self.high = high_res; + /// high_carry + /// } + /// } + /// + /// fn main() {} + /// ``` + /// + /// General behavior /// /// ``` /// #![feature(bigint_helper_methods)]