Skip to content

Commit 4e38d06

Browse files
tspiteritspiteri
committed
doc: rewrite doc for signed int::{carrying_add,borrowing_sub}
1 parent 84365ff commit 4e38d06

File tree

1 file changed

+75
-36
lines changed

1 file changed

+75
-36
lines changed

‎library/core/src/num/int_macros.rs

+75-36
Original file line numberDiff line numberDiff line change
@@ -1506,37 +1506,50 @@ macro_rules! int_impl {
15061506
(a as Self, b)
15071507
}
15081508

1509-
/// Calculates `self + rhs + carry` without the ability to overflow.
1509+
/// Calculates `self` + `rhs` + `carry` and checks for overflow.
15101510
///
1511-
/// Performs "signed ternary addition" which takes in an extra bit to add, and may return an
1512-
/// additional bit of overflow. This signed function is used only on the highest-ordered data,
1513-
/// for which the signed overflow result indicates whether the big integer overflowed or not.
1511+
/// Performs "ternary addition" of two integer operands and a carry-in
1512+
/// bit, and returns a tuple of the sum along with a boolean indicating
1513+
/// whether an arithmetic overflow would occur. On overflow, the wrapped
1514+
/// value is returned.
15141515
///
1515-
/// # Examples
1516+
/// This allows chaining together multiple additions to create a wider
1517+
/// addition, and can be useful for bignum addition. This method should
1518+
/// only be used for the most significant word; for the less significant
1519+
/// words the unsigned method
1520+
#[doc = concat!("[`", stringify!($UnsignedT), "::carrying_add`]")]
1521+
/// should be used.
15161522
///
1517-
/// Basic usage:
1523+
/// The output boolean returned by this method is *not* a carry flag,
1524+
/// and should *not* be added to a more significant word.
15181525
///
1519-
/// ```
1520-
/// #![feature(bigint_helper_methods)]
1521-
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".carrying_add(2, false), (7, false));")]
1522-
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".carrying_add(2, true), (8, false));")]
1523-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, false), (", stringify!($SelfT), "::MIN, true));")]
1524-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(0, true), (", stringify!($SelfT), "::MIN, true));")]
1525-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, true), (", stringify!($SelfT), "::MIN + 1, true));")]
1526-
#[doc = concat!("assert_eq!(",
1527-
stringify!($SelfT), "::MAX.carrying_add(", stringify!($SelfT), "::MAX, true), ",
1528-
"(-1, true));"
1529-
)]
1530-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.carrying_add(-1, true), (", stringify!($SelfT), "::MIN, false));")]
1531-
#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".carrying_add(", stringify!($SelfT), "::MAX, true), (", stringify!($SelfT), "::MIN, true));")]
1532-
/// ```
1526+
/// If the input carry is false, this method is equivalent to
1527+
/// [`overflowing_add`](Self::overflowing_add).
15331528
///
1534-
/// If `carry` is false, this method is equivalent to [`overflowing_add`](Self::overflowing_add):
1529+
/// # Examples
15351530
///
15361531
/// ```
15371532
/// #![feature(bigint_helper_methods)]
1538-
#[doc = concat!("assert_eq!(5_", stringify!($SelfT), ".carrying_add(2, false), 5_", stringify!($SelfT), ".overflowing_add(2));")]
1539-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.carrying_add(1, false), ", stringify!($SelfT), "::MAX.overflowing_add(1));")]
1533+
/// // Only the most significant word is signed.
1534+
/// //
1535+
#[doc = concat!("// 10 MAX (a = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
1536+
#[doc = concat!("// + -5 9 (b = -5 × 2^", stringify!($BITS), " + 9)")]
1537+
/// // ---------
1538+
#[doc = concat!("// 6 8 (sum = 6 × 2^", stringify!($BITS), " + 8)")]
1539+
///
1540+
#[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (10, ", stringify!($UnsignedT), "::MAX);")]
1541+
#[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")]
1542+
/// let carry0 = false;
1543+
///
1544+
#[doc = concat!("// ", stringify!($UnsignedT), "::carrying_add for the less significant words")]
1545+
/// let (sum0, carry1) = a0.carrying_add(b0, carry0);
1546+
/// assert_eq!(carry1, true);
1547+
///
1548+
#[doc = concat!("// ", stringify!($SelfT), "::carrying_add for the most significant word")]
1549+
/// let (sum1, overflow) = a1.carrying_add(b1, carry1);
1550+
/// assert_eq!(overflow, false);
1551+
///
1552+
/// assert_eq!((sum1, sum0), (6, 8));
15401553
/// ```
15411554
#[unstable(feature = "bigint_helper_methods", issue = "85532")]
15421555
#[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]
@@ -1600,25 +1613,51 @@ macro_rules! int_impl {
16001613
(a as Self, b)
16011614
}
16021615

1603-
/// Calculates `self - rhs - borrow` without the ability to overflow.
1616+
/// Calculates `self` − `rhs` − `borrow` and checks for
1617+
/// overflow.
16041618
///
1605-
/// Performs "signed ternary subtraction" which takes in an extra bit to subtract, and may return an
1606-
/// additional bit of overflow. This signed function is used only on the highest-ordered data,
1607-
/// for which the signed overflow result indicates whether the big integer overflowed or not.
1619+
/// Performs "ternary subtraction" by subtracting both an integer
1620+
/// operandand a borrow-in bit from `self`, and returns a tuple of the
1621+
/// difference along with a boolean indicating whether an arithmetic
1622+
/// overflow would occur. On overflow, the wrapped value is returned.
16081623
///
1609-
/// # Examples
1624+
/// This allows chaining together multiple subtractions to create a
1625+
/// wider subtraction, and can be useful for bignum subtraction. This
1626+
/// method should only be used for the most significant word; for the
1627+
/// less significant words the unsigned method
1628+
#[doc = concat!("[`", stringify!($UnsignedT), "::borrowing_sub`]")]
1629+
/// should be used.
16101630
///
1611-
/// Basic usage:
1631+
/// The output boolean returned by this method is *not* a borrow flag,
1632+
/// and should *not* be subtracted from a more significant word.
1633+
///
1634+
/// If the input borrow is false, this method is equivalent to
1635+
/// [`overflowing_sub`](Self::overflowing_sub).
1636+
///
1637+
/// # Examples
16121638
///
16131639
/// ```
16141640
/// #![feature(bigint_helper_methods)]
1615-
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".borrowing_sub(2, false), (3, false));")]
1616-
#[doc = concat!("assert_eq!(5", stringify!($SelfT), ".borrowing_sub(2, true), (2, false));")]
1617-
#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".borrowing_sub(1, false), (-1, false));")]
1618-
#[doc = concat!("assert_eq!(0", stringify!($SelfT), ".borrowing_sub(1, true), (-2, false));")]
1619-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.borrowing_sub(1, true), (", stringify!($SelfT), "::MAX - 1, true));")]
1620-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.borrowing_sub(-1, false), (", stringify!($SelfT), "::MIN, true));")]
1621-
#[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.borrowing_sub(-1, true), (", stringify!($SelfT), "::MAX, false));")]
1641+
/// // Only the most significant word is signed.
1642+
/// //
1643+
#[doc = concat!("// 6 8 (a = 6 × 2^", stringify!($BITS), " + 8)")]
1644+
#[doc = concat!("// - -5 9 (b = -5 × 2^", stringify!($BITS), " + 9)")]
1645+
/// // ---------
1646+
#[doc = concat!("// 10 MAX (diff = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")]
1647+
///
1648+
#[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (6, 8);")]
1649+
#[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")]
1650+
/// let borrow0 = false;
1651+
///
1652+
#[doc = concat!("// ", stringify!($UnsignedT), "::borrowing_sub for the less significant words")]
1653+
/// let (diff0, borrow1) = a0.borrowing_sub(b0, borrow0);
1654+
/// assert_eq!(borrow1, true);
1655+
///
1656+
#[doc = concat!("// ", stringify!($SelfT), "::borrowing_sub for the most significant word")]
1657+
/// let (diff1, overflow) = a1.borrowing_sub(b1, borrow1);
1658+
/// assert_eq!(overflow, false);
1659+
///
1660+
#[doc = concat!("assert_eq!((diff1, diff0), (10, ", stringify!($UnsignedT), "::MAX));")]
16221661
/// ```
16231662
#[unstable(feature = "bigint_helper_methods", issue = "85532")]
16241663
#[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")]

0 commit comments

Comments
 (0)