DoxigAlpha
std › math › big › int.Mutable › addSat

addSat

r = a + b with 2s-complement saturating semantics. r, a and b may be aliases.

Assets the result fits in r. Upper bound on the number of limbs needed by r is calcTwosCompLimbCount(bit_count).

Function parameters

Parameters

#
r:*Mutable
bit_count:usize

Used to indicate either limit of a 2s-complement integer.

Types

#
TwosCompIntLimit
Used to indicate either limit of a 2s-complement integer.
Mutable
A arbitrary-precision big integer, with a fixed set of mutable limbs.
Const
A arbitrary-precision big integer, with a fixed set of immutable limbs.
Managed
An arbitrary-precision big integer along with an allocator which manages the memory.

Returns the number of limbs needed to store `scalar`, which must be a

Functions

#
calcLimbLen
Returns the number of limbs needed to store `scalar`, which must be a
calcSetStringLimbCount
Assumes `string_len` doesn't account for minus signs if the number is negative.
calcNonZeroTwosCompLimbCount
Compute the number of limbs required to store a 2s-complement number of `bit_count` bits.
calcTwosCompLimbCount
Compute the number of limbs required to store a 2s-complement number of `bit_count` bits.
addMulLimbWithCarry
a + b * c + *carry, sets carry to the overflow bits
llcmp
Returns -1, 0, 1 if |a| < |b|, |a| == |b| or |a| > |b| respectively for limbs.

Source

Implementation

#
pub fn addSat(r: *Mutable, a: Const, b: Const, signedness: Signedness, bit_count: usize) void {
    const req_limbs = calcTwosCompLimbCount(bit_count);

    // Slice of the upper bits if they exist, these will be ignored and allows us to use addCarry to determine
    // if an overflow occurred.
    const x = Const{
        .positive = a.positive,
        .limbs = a.limbs[0..@min(req_limbs, a.limbs.len)],
    };

    const y = Const{
        .positive = b.positive,
        .limbs = b.limbs[0..@min(req_limbs, b.limbs.len)],
    };

    if (r.addCarry(x, y)) {
        // There are two possibilities here:
        // - We overflowed req_limbs, in which case we need to saturate.
        // - a and b had less elements than req_limbs, and those were overflowed.
        //   Note: In this case, might _also_ need to saturate.
        const msl = @max(a.limbs.len, b.limbs.len);
        if (msl < req_limbs) {
            r.limbs[msl] = 1;
            r.len = req_limbs;
            // Note: Saturation may still be required if msl == req_limbs - 1
        } else {
            // Overflowed req_limbs, definitely saturate.
            r.setTwosCompIntLimit(if (r.positive) .max else .min, signedness, bit_count);
        }
    }

    // Saturate if the result didn't fit.
    r.saturate(r.toConst(), signedness, bit_count);
}