Document and add test for the result of converting between unsigned and negative

Signed-off-by: Mattias Andrée <m@maandree.se>

3 files changed, 28 insertions, 0 deletions

diff --git a/libj2/constructors.h b/libj2/constructors.h
index 763f838..6c37fa7 100644
--- a/libj2/constructors.h
+++ b/libj2/constructors.h
@@ -74,6 +74,11 @@ libj2_ji_to_j2i(intmax_t a, struct libj2_j2i *res)
  * 
  * Overflows if `libj2_j2u_test_bit(a, LIBJ2_J2U_BIT - 1U)`
  * 
+ * On overflow, the result wraps around to a negative
+ * value, which by design is holds the property that
+ * `-*res == 0 - *a`, where the right-hand of the
+ * equality is unsigned and therefore positive.
+ * 
  * @param  a    The value to assign to `*res`
  * @param  res  The integer to assign the value `a` to
  * 
@@ -95,6 +100,11 @@ libj2_j2u_to_j2i(const struct libj2_j2u *a, struct libj2_j2i *res)
  * 
  * Overflows if `libj2_j2i_is_negative(a)`
  * 
+ * On overflow, the result wraps around to a large
+ * value, which by design is holds the property that
+ * `0 - *res == -*a`, where the left-hand of the
+ * equality is unsigned and therefore positive.
+ * 
  * @param  a    The value to assign to `*res`
  * @param  res  The integer to assign the value `a` to
  * 
diff --git a/libj2_j2i_to_j2u.c b/libj2_j2i_to_j2u.c
index 4419c7a..b81c394 100644
--- a/libj2_j2i_to_j2u.c
+++ b/libj2_j2i_to_j2u.c
@@ -70,6 +70,15 @@ main(void)
 		EXPECT(u.low == b);
 	}
 
+	u = (struct libj2_j2u){111, 222};
+	v.high = a = 100;
+	v.low = b = 200;
+	libj2_minus_j2i(&v);
+	libj2_j2i_to_j2u(&v, &u);
+	libj2_j2u_rsub_ju(&u, 0);
+	EXPECT(u.high == a);
+	EXPECT(u.low == b);
+
 	return 0;
 }
 
diff --git a/libj2_j2u_to_j2i.c b/libj2_j2u_to_j2i.c
index eb5b404..f157b79 100644
--- a/libj2_j2u_to_j2i.c
+++ b/libj2_j2u_to_j2i.c
@@ -74,6 +74,15 @@ main(void)
 		EXPECT(u.low == b);
 	}
 
+	v = (struct libj2_j2i){111, 222};
+	u.high = a = 100;
+	u.low = b = 200;
+	libj2_j2u_rsub_ju(&u, 0);
+	libj2_j2u_to_j2i(&u, &v);
+	libj2_minus_j2i(&v);
+	EXPECT(v.high == a);
+	EXPECT(v.low == b);
+
 	return 0;
 }