stillwater-sc / universal / 24969843496

84%

master: 84%

push

github

fix(integer): implement WholeNumber/NaturalNumber operator-= (#779)

Replaces the placeholder std::cerr "subtractor TBD" no-op with a real
constexpr-safe magnitude subtractor. Both NumberType modes are
unsigned-domain, so the implementation is a straightforward limb-wise
borrow loop.

The borrow propagation uses the formulation:
  incoming borrow == 0: borrow-out iff a < b
  incoming borrow == 1: borrow-out iff a <= b   (a-b-1 wraps when a == b)
which works uniformly across bt = uint8/uint16/uint32/uint64 limbs
without overflow concerns from widening (b + borrow) at the largest
limb size.

Critical design choice: the WholeNumber/NaturalNumber semantic
preconditions (result >= 1 / result >= 0) are gated behind
INTEGER_THROW_ARITHMETIC_EXCEPTION -- matching the convention already
used in operator/= and convert_signed/unsigned. Under THROW=0 (the
default) the magnitude subtractor runs unconditionally.

This gating is necessary because internal algorithms call -= with
operands that would violate the semantic preconditions in the user-
facing sense:
  - Long division (line 1598/1632): accumulator -= subtractand,
    where accumulator == subtractand at the boundary
  - Decimal conversion (line 1862-1863): the / and % chain calls into
    long division
  - Stream output (operator<<): wraps decimal conversion
Throwing in those paths would break printing and division for
WholeNumber and NaturalNumber types entirely, which is exactly the
failure mode this PR was authored to fix.

Out-of-domain user code under THROW=0 gets defined modular wraparound,
the same convention IntegerNumber uses by default. Out-of-domain user
code under THROW=1 still throws integer_wholenumber_cannot_be_negative
or integer_wholenumber_cannot_be_zero as before.

Tests:
  - static/integer/binary/api/constexpr.cpp: extended the
    "Edge cases" block with 5 new static_asserts covering N32/W32
    single-limb subtraction, multi-limb cross-limb borrow (256 - 1
    via N64u8), and the Natura... (continued)

9 of 11 new or added lines in 1 file covered. (81.82%)

45489 of 53953 relevant lines covered (84.31%)

6354648.95 hits per line