fixed

commit d005913bf324ca4db9d90550765433fed30ed22e
parent 4730a3b70f0dfa70d726d54d46d2f764a315df0e
Author: Jared Tobin <jared@jtobin.io>
Date:   Sat,  1 Aug 2026 14:09:03 -0230

lib: document add_c# and sub_b# carry conventions

add_c# ORs its two internal carry bits, so it is only correct for a
carry-in of 0 or 1; sub_b# reads only the most significant bit of
its borrow-in. Neither convention was documented, and both differ
from what a reader might expect (e.g. crypto-bigint's adc accepts
arbitrary carries).

Diffstat:
M
lib/Data/Word/Limb.hs
 | 
8
++++++++

1 file changed, 8 insertions(+), 0 deletions(-)
diff --git a/lib/Data/Word/Limb.hs b/lib/Data/Word/Limb.hs
@@ -268,6 +268,9 @@ add_o# (Limb a) (Limb b) = case Exts.plusWord2# a b of
 
 -- | Carrying addition, computing augend + addend + carry, returning
 --   the sum and new carry.
+--
+--   The carry-in must be 0 or 1; this is not checked. The carry-out
+--   is always 0 or 1.
 add_c#
   :: Limb             -- ^ augend
   -> Limb             -- ^ addend
@@ -304,6 +307,11 @@ add_s# (Limb a) (Limb b) =
 
 -- | Borrowing subtraction, computing minuend - (subtrahend + borrow),
 --   returning the difference and new borrow mask.
+--
+--   The borrow-in is interpreted as a mask, of which only the most
+--   significant bit is examined; a full-word mask (as produced by
+--   this function) borrows 1. The borrow-out is 0 or a full-word
+--   mask.
 sub_b#
   :: Limb              -- ^ minuend
   -> Limb              -- ^ subtrahend