hare

commit 468d2371b9d317706bb946c4acbd0c7c2ee59268
parent b324767d3c7a95542ac1157cfe5e2ce7a3a532c7
Author: Sebastian <sebastian@sebsite.pw>
Date:   Sun,  1 Dec 2024 20:25:27 -0500

math: improve docs for mulu, divu, and remu

Signed-off-by: Sebastian <sebastian@sebsite.pw>

Diffstat:
M
math/uints.ha
 | 
13
++++++++++---

1 file changed, 10 insertions(+), 3 deletions(-)
diff --git a/math/uints.ha b/math/uints.ha
@@ -279,7 +279,9 @@ export fn mulu64(x: u64, y: u64) (u64, u64) = {
 	return (hi, lo);
 };
 
-// Calls either mulu32() or mulu64() depending on size(uint).
+// Returns the product of x and y: (hi, lo) = x * y
+// with the product bits' upper half returned in hi and the lower
+// half returned in lo.
 export fn mulu(x: uint, y: uint) (uint, uint) = {
 	if (size(uint) == 4) {
 		const res = mulu32((x: u32), (y: u32));
@@ -375,7 +377,10 @@ export fn divu64(hi: u64, lo: u64, y: u64) (u64, u64) = {
 	return (quo, rem);
 };
 
-// Calls either divu32() or divu64() depending on size(uint).
+// Returns the quotient and remainder of (hi, lo) divided by y:
+// quo = (hi, lo) / y, rem = (hi, lo) % y with the dividend bits' upper
+// half in parameter hi and the lower half in parameter lo.
+// Aborts if y == 0 (division by zero) or y <= hi (quotient overflow).
 export fn divu(hi: uint, lo: uint, y: uint) (uint, uint) = {
 	if (size(uint) == 4) {
 		const res = divu32((hi: u32), (lo: u32), (y: u32));
@@ -453,7 +458,9 @@ export fn remu64(hi: u64, lo: u64, y: u64) u64 = {
 	return res.1;
 };
 
-// Calls either remu32() or remu64() depending on size(uint).
+// Returns the remainder of (hi, lo) divided by y.
+// Aborts if y == 0 (division by zero) but, unlike [[divu]], it doesn't abort on
+// a quotient overflow.
 export fn remu(hi: uint, lo: uint, y: uint) uint = {
 	if (size(uint) == 4) {
 		return (remu32((hi: u32), (lo: u32), (y: u32)): uint);