clar: introduce type-safe integer comparisons

pks-t · pks-t · commit 06f0c3531f93 · 2025-12-03T21:11:10.000+01:00
The macros we have to assert the state of integers are lacking due to
multiple reasons:

  - We explicitly cast the values to `int`, which causes problems in
    case the values do not fit into an `int`. Furthermore, this hides
    issues in case one accidentally passes the wrong type to this macro.

  - We only have macros to compare integers for equality. Notably
    lacking are constructs to compare for non-equality, like "less
    than" or "less or equal".

  - We only have macros to compare _signed_ integers, but lack macros to
    check for _unsigned_ macros.

Fix this issue by introducing `clar__assert_compare_i()` as well as an
equivalent for unsigned types, `clar__assert_compare_u()`. These macros:

  - Get `intmax_t` and `uintmax_t` as input, respectively, which allows
    us to get rid of the explicit casts. Instead, the compiler can now
    verify types for us and print warnings when there is an incompatible
    type.

  - Get an enum as input for the various different comparisons. Like
    this we don't only support equality checks, but also all the other
    checks one would typically expect.

Adapt existing macros to use `clar__assert_compare_i()`. Furthermore,
introduce new macros that supersede the older variants and which allow
the caller to perform integer comparisons.
diff --git a/clar.c b/clar.c
@@ -939,6 +939,92 @@ void clar__assert_equal(
 		clar__fail(file, function, line, err, buf, should_abort);
 }
 
+void clar__assert_compare_i(
+	const char *file,
+	const char *func,
+	size_t line,
+	int should_abort,
+	enum clar_comparison cmp,
+	intmax_t value1,
+	intmax_t value2,
+	const char *error,
+	const char *description,
+	...)
+{
+	int fulfilled;
+	switch (cmp) {
+	case CLAR_COMPARISON_EQ:
+		fulfilled = value1 == value2;
+		break;
+	case CLAR_COMPARISON_LT:
+		fulfilled = value1 < value2;
+		break;
+	case CLAR_COMPARISON_LE:
+		fulfilled = value1 <= value2;
+		break;
+	case CLAR_COMPARISON_GT:
+		fulfilled = value1 > value2;
+		break;
+	case CLAR_COMPARISON_GE:
+		fulfilled = value1 >= value2;
+		break;
+	default:
+		cl_assert(0);
+		return;
+	}
+
+	if (!fulfilled) {
+		va_list args;
+		va_start(args, description);
+		clar__failv(file, func, line, should_abort, error,
+			    description, args);
+		va_end(args);
+	}
+}
+
+void clar__assert_compare_u(
+	const char *file,
+	const char *func,
+	size_t line,
+	int should_abort,
+	enum clar_comparison cmp,
+	uintmax_t value1,
+	uintmax_t value2,
+	const char *error,
+	const char *description,
+	...)
+{
+	int fulfilled;
+	switch (cmp) {
+	case CLAR_COMPARISON_EQ:
+		fulfilled = value1 == value2;
+		break;
+	case CLAR_COMPARISON_LT:
+		fulfilled = value1 < value2;
+		break;
+	case CLAR_COMPARISON_LE:
+		fulfilled = value1 <= value2;
+		break;
+	case CLAR_COMPARISON_GT:
+		fulfilled = value1 > value2;
+		break;
+	case CLAR_COMPARISON_GE:
+		fulfilled = value1 >= value2;
+		break;
+	default:
+		cl_assert(0);
+		return;
+	}
+
+	if (!fulfilled) {
+		va_list args;
+		va_start(args, description);
+		clar__failv(file, func, line, should_abort, error,
+			    description, args);
+		va_end(args);
+	}
+}
+
 void cl_set_cleanup(void (*cleanup)(void *), void *opaque)
 {
 	_clar.local_cleanup = cleanup;
diff --git a/clar.h b/clar.h
@@ -7,6 +7,7 @@
 #ifndef __CLAR_TEST_H__
 #define __CLAR_TEST_H__
 
+#include <inttypes.h>
 #include <stdlib.h>
 #include <limits.h>
 
@@ -169,9 +170,34 @@ const char *cl_fixture_basename(const char *fixture_name);
 #define cl_assert_equal_wcsn(wcs1,wcs2,len) clar__assert_equal(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,"String mismatch: " #wcs1 " != " #wcs2, 1, "%.*ls", (wcs1), (wcs2), (int)(len))
 #define cl_assert_equal_wcsn_(wcs1,wcs2,len,note) clar__assert_equal(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,"String mismatch: " #wcs1 " != " #wcs2 " (" #note ")", 1, "%.*ls", (wcs1), (wcs2), (int)(len))
 
-#define cl_assert_equal_i(i1,i2) clar__assert_equal(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,#i1 " != " #i2, 1, "%d", (int)(i1), (int)(i2))
-#define cl_assert_equal_i_(i1,i2,note) clar__assert_equal(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,#i1 " != " #i2 " (" #note ")", 1, "%d", (i1), (i2))
-#define cl_assert_equal_i_fmt(i1,i2,fmt) clar__assert_equal(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,#i1 " != " #i2, 1, (fmt), (int)(i1), (int)(i2))
+/* The following three macros are essentially deprecated now in favor of the macros in subsequent blocks. */
+#define cl_assert_equal_i(i1,i2) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_EQ,#i1 " != " #i2,"%"PRIdMAX " != %"PRIdMAX,(intmax_t)(i1),(intmax_t)(i2))
+#define cl_assert_equal_i_(i1,i2,note) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_EQ,#i1 " != " #i2 " (" #note ")","%"PRIdMAX " != %"PRIdMAX,(intmax_t)(i1),(intmax_t)(i2))
+#define cl_assert_equal_i_fmt(i1,i2,fmt) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_EQ,#i1 " != " #i2, fmt " != " fmt, (int)(i1), (int)(i2))
+
+#define cl_assert_compare_i(i1,i2,cmp,error,description,...) clar__assert_compare_i(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,1,cmp,(i1),(i2),error,description,__VA_ARGS__)
+#define cl_assert_eq_i_(i1,i2,description,...) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_EQ,"Expected comparison to hold: " #i1 " == " #i2,description,__VA_ARGS__)
+#define cl_assert_eq_i(i1,i2) cl_assert_eq_i_(i1,i2,"%"PRIdMAX " != %"PRIdMAX,(intmax_t)(i1),(intmax_t)(i2))
+#define cl_assert_lt_i_(i1,i2,description,...) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_LT,"Expected comparison to hold: " #i1 " < " #i2,description,__VA_ARGS__)
+#define cl_assert_lt_i(i1,i2) cl_assert_lt_i_(i1,i2,"%"PRIdMAX " >= %"PRIdMAX,(intmax_t)(i1),(intmax_t)(i2))
+#define cl_assert_le_i_(i1,i2,description,...) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_LE,"Expected comparison to hold: " #i1 " <= " #i2,description,__VA_ARGS__)
+#define cl_assert_le_i(i1,i2) cl_assert_le_i_(i1,i2,"%"PRIdMAX " > %"PRIdMAX,(intmax_t)(i1),(intmax_t)(i2))
+#define cl_assert_gt_i_(i1,i2,description,...) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_GT,"Expected comparison to hold: " #i1 " > " #i2,description,__VA_ARGS__)
+#define cl_assert_gt_i(i1,i2) cl_assert_gt_i_(i1,i2,"%"PRIdMAX " <= %"PRIdMAX,(intmax_t)(i1),(intmax_t)(i2))
+#define cl_assert_ge_i_(i1,i2,description,...) cl_assert_compare_i(i1,i2,CLAR_COMPARISON_GE,"Expected comparison to hold: " #i1 " >= " #i2,description,__VA_ARGS__)
+#define cl_assert_ge_i(i1,i2) cl_assert_ge_i_(i1,i2,"%"PRIdMAX " < %"PRIdMAX,(intmax_t)(i1),(intmax_t)(i2))
+
+#define cl_assert_compare_u(u1,u2,cmp,error,description,...) clar__assert_compare_u(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,1,cmp,(u1),(u2),error,description,__VA_ARGS__)
+#define cl_assert_eq_u_(u1,u2,description,...) cl_assert_compare_u(u1,u2,CLAR_COMPARISON_EQ,"Expected comparison to hold: " #u1 " == " #u2,description,__VA_ARGS__)
+#define cl_assert_eq_u(u1,u2) cl_assert_eq_u_(u1,u2,"%"PRIuMAX " != %"PRIuMAX,(uintmax_t)(u1),(uintmax_t)(u2))
+#define cl_assert_lt_u_(u1,u2,description,...) cl_assert_compare_u(u1,u2,CLAR_COMPARISON_LT,"Expected comparison to hold: " #u1 " < " #u2,description,__VA_ARGS__)
+#define cl_assert_lt_u(u1,u2) cl_assert_lt_u_(u1,u2,"%"PRIuMAX " >= %"PRIuMAX,(uintmax_t)(u1),(uintmax_t)(u2))
+#define cl_assert_le_u_(u1,u2,description,...) cl_assert_compare_u(u1,u2,CLAR_COMPARISON_LE,"Expected comparison to hold: " #u1 " <= " #u2,description,__VA_ARGS__)
+#define cl_assert_le_u(u1,u2) cl_assert_le_u_(u1,u2,"%"PRIuMAX " > %"PRIuMAX,(uintmax_t)(u1),(uintmax_t)(u2))
+#define cl_assert_gt_u_(u1,u2,description,...) cl_assert_compare_u(u1,u2,CLAR_COMPARISON_GT,"Expected comparison to hold: " #u1 " > " #u2,description,__VA_ARGS__)
+#define cl_assert_gt_u(u1,u2) cl_assert_gt_u_(u1,u2,"%"PRIuMAX " <= %"PRIuMAX,(uintmax_t)(u1),(uintmax_t)(u2))
+#define cl_assert_ge_u_(u1,u2,description,...) cl_assert_compare_u(u1,u2,CLAR_COMPARISON_GE,"Expected comparison to hold: " #u1 " >= " #u2,description,__VA_ARGS__)
+#define cl_assert_ge_u(u1,u2) cl_assert_ge_u_(u1,u2,"%"PRIuMAX " < %"PRIuMAX,(uintmax_t)(u1),(uintmax_t)(u2))
 
 #define cl_assert_equal_b(b1,b2) clar__assert_equal(CLAR_CURRENT_FILE,CLAR_CURRENT_FUNC,CLAR_CURRENT_LINE,#b1 " != " #b2, 1, "%d", (int)((b1) != 0),(int)((b2) != 0))
 
@@ -214,6 +240,38 @@ void clar__assert_equal(
 	const char *fmt,
 	...);
 
+enum clar_comparison {
+	CLAR_COMPARISON_EQ,
+	CLAR_COMPARISON_LT,
+	CLAR_COMPARISON_LE,
+	CLAR_COMPARISON_GT,
+	CLAR_COMPARISON_GE,
+};
+
+void clar__assert_compare_i(
+	const char *file,
+	const char *func,
+	size_t line,
+	int should_abort,
+	enum clar_comparison cmp,
+	intmax_t value1,
+	intmax_t value2,
+	const char *error,
+	const char *description,
+	...);
+
+void clar__assert_compare_u(
+	const char *file,
+	const char *func,
+	size_t line,
+	int should_abort,
+	enum clar_comparison cmp,
+	uintmax_t value1,
+	uintmax_t value2,
+	const char *error,
+	const char *description,
+	...);
+
 void clar__set_invokepoint(
 	const char *file,
 	const char *func,
diff --git a/test/expected/quiet b/test/expected/quiet
@@ -47,3 +47,13 @@ combined::failf [file:42]
   Test failed.
   some reason: foo
 
+  11) Failure:
+combined::compare_i [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
+  12) Failure:
+combined::compare_u [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
diff --git a/test/expected/summary_with_filename b/test/expected/summary_with_filename
@@ -1,6 +1,6 @@
 Loaded 1 suites:
 Started (test status codes: OK='.' FAILURE='F' SKIPPED='S')
-FFFFFFFFFF
+FFFFFFFFFFFF
 
   1) Failure:
 combined::1 [file:42]
@@ -51,4 +51,14 @@ combined::failf [file:42]
   Test failed.
   some reason: foo
 
+  11) Failure:
+combined::compare_i [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
+  12) Failure:
+combined::compare_u [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
 written summary file to different.xml
diff --git a/test/expected/summary_without_filename b/test/expected/summary_without_filename
@@ -1,6 +1,6 @@
 Loaded 1 suites:
 Started (test status codes: OK='.' FAILURE='F' SKIPPED='S')
-FFFFFFFFFF
+FFFFFFFFFFFF
 
   1) Failure:
 combined::1 [file:42]
@@ -51,4 +51,14 @@ combined::failf [file:42]
   Test failed.
   some reason: foo
 
+  11) Failure:
+combined::compare_i [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
+  12) Failure:
+combined::compare_u [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
 written summary file to summary.xml
diff --git a/test/expected/tap b/test/expected/tap
@@ -99,4 +99,24 @@ not ok 10 - combined::failf
       line: 42
       function: 'func'
     ...
-1..10
+not ok 11 - combined::compare_i
+    ---
+    reason: |
+      Expected comparison to hold: two < 1
+      2 >= 1
+    at:
+      file: 'file'
+      line: 42
+      function: 'func'
+    ...
+not ok 12 - combined::compare_u
+    ---
+    reason: |
+      Expected comparison to hold: two < 1
+      2 >= 1
+    at:
+      file: 'file'
+      line: 42
+      function: 'func'
+    ...
+1..12
diff --git a/test/expected/without_arguments b/test/expected/without_arguments
@@ -1,6 +1,6 @@
 Loaded 1 suites:
 Started (test status codes: OK='.' FAILURE='F' SKIPPED='S')
-FFFFFFFFFF
+FFFFFFFFFFFF
 
   1) Failure:
 combined::1 [file:42]
@@ -51,3 +51,13 @@ combined::failf [file:42]
   Test failed.
   some reason: foo
 
+  11) Failure:
+combined::compare_i [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
+  12) Failure:
+combined::compare_u [file:42]
+  Expected comparison to hold: two < 1
+  2 >= 1
+
diff --git a/test/selftest.c b/test/selftest.c
@@ -298,7 +298,7 @@ void test_selftest__help(void)
 
 void test_selftest__without_arguments(void)
 {
-	cl_invoke(assert_output("combined", "without_arguments", 10, NULL));
+	cl_invoke(assert_output("combined", "without_arguments", 12, NULL));
 }
 
 void test_selftest__specific_test(void)
@@ -313,12 +313,12 @@ void test_selftest__stop_on_failure(void)
 
 void test_selftest__quiet(void)
 {
-	cl_invoke(assert_output("combined", "quiet", 10, "-q", NULL));
+	cl_invoke(assert_output("combined", "quiet", 12, "-q", NULL));
 }
 
 void test_selftest__tap(void)
 {
-	cl_invoke(assert_output("combined", "tap", 10, "-t", NULL));
+	cl_invoke(assert_output("combined", "tap", 12, "-t", NULL));
 }
 
 void test_selftest__suite_names(void)
@@ -329,15 +329,15 @@ void test_selftest__suite_names(void)
 void test_selftest__summary_without_filename(void)
 {
 	struct stat st;
-	cl_invoke(assert_output("combined", "summary_without_filename", 10, "-r", NULL));
+	cl_invoke(assert_output("combined", "summary_without_filename", 12, "-r", NULL));
 	/* The summary contains timestamps, so we cannot verify its contents. */
 	cl_must_pass(stat("summary.xml", &st));
 }
 
 void test_selftest__summary_with_filename(void)
 {
 	struct stat st;
-	cl_invoke(assert_output("combined", "summary_with_filename", 10, "-rdifferent.xml", NULL));
+	cl_invoke(assert_output("combined", "summary_with_filename", 12, "-rdifferent.xml", NULL));
 	/* The summary contains timestamps, so we cannot verify its contents. */
 	cl_must_pass(stat("different.xml", &st));
 }
diff --git a/test/suites/combined.c b/test/suites/combined.c
@@ -88,3 +88,34 @@ void test_combined__failf(void)
 {
 	cl_failf("some reason: %s", "foo");
 }
+
+void test_combined__compare_i(void)
+{
+	int one = 1, two = 2;
+
+	cl_assert_equal_i(one, 1);
+	cl_assert_eq_i(one, 1);
+	cl_assert_lt_i(one, 2);
+	cl_assert_le_i(one, 2);
+	cl_assert_le_i(two, 2);
+	cl_assert_gt_i(two, 1);
+	cl_assert_ge_i(two, 2);
+	cl_assert_ge_i(3, two);
+
+	cl_assert_lt_i(two, 1); /* this one fails */
+}
+
+void test_combined__compare_u(void)
+{
+	unsigned one = 1, two = 2;
+
+	cl_assert_eq_u(one, 1);
+	cl_assert_lt_u(one, 2);
+	cl_assert_le_u(one, 2);
+	cl_assert_le_u(two, 2);
+	cl_assert_gt_u(two, 1);
+	cl_assert_ge_u(two, 2);
+	cl_assert_ge_u(3, two);
+
+	cl_assert_lt_u(two, 1); /* this one fails */
+}

Original file line number	Diff line number	Diff line change
`@@ -298,7 +298,7 @@ void test_selftest__help(void)`
`298`	`298`
`299`	`299`	`void test_selftest__without_arguments(void)`
`300`	`300`	`{`
`301`		`- cl_invoke(assert_output("combined", "without_arguments", 10, NULL));`
	`301`	`+ cl_invoke(assert_output("combined", "without_arguments", 12, NULL));`
`302`	`302`	`}`
`303`	`303`
`304`	`304`	`void test_selftest__specific_test(void)`
`@@ -313,12 +313,12 @@ void test_selftest__stop_on_failure(void)`
`313`	`313`
`314`	`314`	`void test_selftest__quiet(void)`
`315`	`315`	`{`
`316`		`- cl_invoke(assert_output("combined", "quiet", 10, "-q", NULL));`
	`316`	`+ cl_invoke(assert_output("combined", "quiet", 12, "-q", NULL));`
`317`	`317`	`}`
`318`	`318`
`319`	`319`	`void test_selftest__tap(void)`
`320`	`320`	`{`
`321`		`- cl_invoke(assert_output("combined", "tap", 10, "-t", NULL));`
	`321`	`+ cl_invoke(assert_output("combined", "tap", 12, "-t", NULL));`
`322`	`322`	`}`
`323`	`323`
`324`	`324`	`void test_selftest__suite_names(void)`
`@@ -329,15 +329,15 @@ void test_selftest__suite_names(void)`
`329`	`329`	`void test_selftest__summary_without_filename(void)`
`330`	`330`	`{`
`331`	`331`	`struct stat st;`
`332`		`- cl_invoke(assert_output("combined", "summary_without_filename", 10, "-r", NULL));`
	`332`	`+ cl_invoke(assert_output("combined", "summary_without_filename", 12, "-r", NULL));`
`333`	`333`	`/* The summary contains timestamps, so we cannot verify its contents. */`
`334`	`334`	`cl_must_pass(stat("summary.xml", &st));`
`335`	`335`	`}`
`336`	`336`
`337`	`337`	`void test_selftest__summary_with_filename(void)`
`338`	`338`	`{`
`339`	`339`	`struct stat st;`
`340`		`- cl_invoke(assert_output("combined", "summary_with_filename", 10, "-rdifferent.xml", NULL));`
	`340`	`+ cl_invoke(assert_output("combined", "summary_with_filename", 12, "-rdifferent.xml", NULL));`
`341`	`341`	`/* The summary contains timestamps, so we cannot verify its contents. */`
`342`	`342`	`cl_must_pass(stat("different.xml", &st));`
`343`	`343`	`}`