feat: (common) rand_range

lib/common.c

@@ -34,3 +34,17 @@ srealloc (void *ptr, size_t size)
 
     return ptr;
 }
+
+/**
+ * create a random number within an interval
+ *
+ * @param   min: the lower bound (inclusive)
+ * @param   max: the upper bound (inclusive)
+ *
+ * @return  a pseudo-random number within the given bounds
+ */
+int
+rand_range (int min, int max)
+{
+    return (rand () % (max - min + 1)) + min;
+}

lib/inc/common.h

@@ -4,18 +4,19 @@
 #include <stddef.h>
 #include <stdint.h>
 
-#define max(a, b) ((a) > (b) ? (a) : (b))
-#define min(a, b) ((a) < (b) ? (a) : (b))
+#define max(a, b) ((a) > (b) ? (a) : (b)) /* find the maximum of two numbers */
+#define min(a, b) ((a) < (b) ? (a) : (b)) /* find the minimum of two numbers */
 
 #if UINTPTR_MAX == 0xffffffffffffffff
-# define next_pow_of_two(n) (((size_t) 1) << (64 - __builtin_clzll (n)))
+# define next_pow_of_two(n) (((size_t) 1) << (64 - __builtin_clzll (n))) /* round up a size_t number to the next power of two (64-bit) */
 #elif UINTPTR_MAX == 0xffffffff
-# define next_pow_of_two(n) (((size_t) 1) << (64 - __builtin_clz (n)))
+# define next_pow_of_two(n) (((size_t) 1) << (64 - __builtin_clz (n))) /* round up a size_t number to the next power of two (32-bit) */
 #else
 # error unsupported architecture: size_t expected to be 64-bit or 32-bit.
 #endif
 
-void *smalloc (size_t size);
-void *srealloc (void *ptr, size_t size);
+void *smalloc (size_t size); /* safe malloc */
+void *srealloc (void *ptr, size_t size); /* safe realloc */
+int rand_range (int min, int max); /* create a random number within an interval */
 
 #endif // CUTILS_COMMON_H_