mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Correct signed bit int documentation

Browse Source
This commit is contained in:
Stovent 2022-02-11 15:25:51 -05:00
parent 1266099742
commit 5c690555f2
1 changed files with 64 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
library/core/src/num/int_macros.rs
View File

@ -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)]