Add a white magic header

book/pages/03_log.md

@@ -382,11 +382,9 @@ Two objectives remain:
 
 While our logs do have a log level associated, there's currently no way to filter out certain levels.
 
-Because we're only creating a simplistic header-only logging library, we will not allow arbitrary filters (like allowing debug and warning but not info and error), only a threshold level.
-
-What that means is that there will be a target log level, and logs as critical or more are outputted, while others are not.
-Which implies that there must be a way to compare levels.
+Because we're only creating a simplistic header-only logging library, we will not allow arbitrary filters (like outputting debug and warning but not info and error), only a threshold level: only logs as critical as the threshold or more shall be output.
 
+This implies that there must be a way to compare levels.
 Currently, log levels are just string literals like `"DEBUG"`{l=C} and `"ERROR"`{l=C}, and cannot be compared meaningfully to determine which is "more critical".
 
 ### Run-time comparison

book/pages/reference/index.md

@@ -5,4 +5,5 @@ internal
 color
 log
 enum
+white
 :::

book/pages/reference/internal.md

@@ -28,3 +28,13 @@
 
 :::{doxygenfile} for.h
 :::
+
+## Manipulate pairs
+
+:::{doxygenfile} pair.h
+:::
+
+## Misc.
+
+:::{doxygenfile} codegen.h
+:::

book/pages/reference/white.md

@@ -0,0 +1,4 @@
+# White magic
+
+:::{doxygenfile} white.h
+:::

include/blackmagic/codegen.h

@@ -5,7 +5,8 @@
 /** Expands to its arguments */
 #define IDENTITY(...) __VA_ARGS__
 
-/** Apply @F to the rest of the arguments, adding a comma at the end. */
+/** Apply @p F to the rest of the arguments, adding a comma at the end. */
 #define ADD_COMMA(F, ...) F(__VA_ARGS__),
 
+/** . */
 #define ADD_COMMA_FLAT(A, B) A B,

include/blackmagic/enum.h

@@ -26,7 +26,8 @@
 #define ES_MAX(NAME) JOIN2(NAME, count)
 ///@endcond
 
-/**
+/** Declare an enum with custom values, with string conversions.
+@section exEV Example
 @code{.c}
 DECLARE_ENUM_WITH_VALUES(
 	cardinal,
@@ -86,6 +87,8 @@ static inline enum cardinal cardinal_from_cstring(const char* string)
 	return cardinal_upper_bound;
 }
 @endcode
+
+@since 0.1
 */
 #define DECLARE_ENUM_WITH_VALUES(NAME, ...)                                            \
 	enum NAME                                                                          \
@@ -118,7 +121,8 @@ static inline enum cardinal cardinal_from_cstring(const char* string)
 		return EV_MAX(NAME);                                                           \
 	}
 
-/**
+/** Declare an enum with custom strings.
+@section exES Example
 @code{.c}
 DECLARE_ENUM_WITH_STRINGS(
     grocery,
@@ -184,6 +188,8 @@ static inline enum grocery grocery_from_cstring(const char* string)
 	return grocery_upper_bound;
 }
 @endcode
+
+@since 0.1
 */
 #define DECLARE_ENUM_WITH_STRINGS(NAME, ...)                                                      \
 	enum NAME                                                                                     \

include/blackmagic/for.h

@@ -1,7 +1,7 @@
 #pragma once
 
 #include "blackmagic/arg_count.h" // ARG_COUNT
-#include "blackmagic/token.h" // CONCAT
+#include "blackmagic/token.h"     // CONCAT
 
 /**
  * @file
@@ -31,17 +31,22 @@
 #define FOR(LIST, MACRO, ...) FOR_(LIST, MACRO __VA_OPT__(,) __VA_ARGS__)
 
 ///@cond
-#define FOR_(N, ...)  CONCAT(FOR_, N)(__VA_ARGS__)
+#define FOR_(N, ...) CONCAT(FOR_, N)(__VA_ARGS__)
 #define FOR_0(M, ...)
-#define FOR_1(A, M, ...)          M(__VA_ARGS__ __VA_OPT__(,) A)
-#define FOR_2(A, B, M, ...)       M(__VA_ARGS__ __VA_OPT__(,) A) M(__VA_ARGS__ __VA_OPT__(,) B)
-#define FOR_3(A, B, C, M, ...)    M(__VA_ARGS__ __VA_OPT__(,) A) M(__VA_ARGS__ __VA_OPT__(,) B) M(__VA_ARGS__ __VA_OPT__(,) C)
-#define FOR_4(A, B, C, D, M, ...) M(__VA_ARGS__ __VA_OPT__(,) A) M(__VA_ARGS__ __VA_OPT__(,) B) M(__VA_ARGS__ __VA_OPT__(,) C) M(__VA_ARGS__ __VA_OPT__(, ) D)
+#define FOR_1(A, M, ...)    M(__VA_ARGS__ __VA_OPT__(,) A)
+#define FOR_2(A, B, M, ...) M(__VA_ARGS__ __VA_OPT__(,) A) M(__VA_ARGS__ __VA_OPT__(,) B)
+#define FOR_3(A, B, C, M, ...) \
+	M(__VA_ARGS__ __VA_OPT__(,) A) \
+	M(__VA_ARGS__ __VA_OPT__(,) B) \
+	M(__VA_ARGS__ __VA_OPT__(,) C)
+#define FOR_4(A, B, C, D, M, ...) \
+	M(__VA_ARGS__ __VA_OPT__(,) A) M(__VA_ARGS__ __VA_OPT__(,) B) \
+	M(__VA_ARGS__ __VA_OPT__(,) C) M(__VA_ARGS__ __VA_OPT__(,) D)
 #define FOR_5(A, B, C, D, E, M, ...) \
 	M(__VA_ARGS__ __VA_OPT__(,) A) \
 	FOR_4(B, C, D, E, M __VA_OPT__(,) __VA_ARGS__)
 #define FOR_6(A, B, C, D, E, F, M, ...) \
-	FOR_3(A, B, C, M __VA_OPT__(,) __VA_ARGS__)	\
+	FOR_3(A, B, C, M __VA_OPT__(,) __VA_ARGS__) \
 	FOR_3(D, E, F, M __VA_OPT__(,) __VA_ARGS__)
 #define FOR_7(A, B, C, D, E, F, G, M, ...) \
 	M(__VA_ARGS__ __VA_OPT__(,) A) \
@@ -50,17 +55,23 @@
 	FOR_4(A, B, C, D, M __VA_OPT__(,) __VA_ARGS__) \
 	FOR_4(E, F, G, H, M __VA_OPT__(,) __VA_ARGS__)
 #define FOR_9(A, B, C, D, E, F, G, H, I, M, ...) \
-	FOR_3(A, B, C, M __VA_OPT__(,) __VA_ARGS__)	\
+	FOR_3(A, B, C, M __VA_OPT__(,) __VA_ARGS__) \
 	FOR_3(D, E, F, M __VA_OPT__(,) __VA_ARGS__) \
 	FOR_3(G, H, I, M __VA_OPT__(,) __VA_ARGS__)
 #define FOR_10(A, B, C, D, E, F, G, H, I, J, M, ...) \
 	FOR_5(A, B, C, D, E, M __VA_OPT__(,) __VA_ARGS__) \
 	FOR_5(F, G, H, I, J, M __VA_OPT__(,) __VA_ARGS__)
-#define FOR_11(A, B, C, D, E, F, G, H, I, J, K, M, ...)	\
+#define FOR_11(A, B, C, D, E, F, G, H, I, J, K, M, ...) \
 	M(__VA_ARGS__ __VA_OPT__(,) A) \
 	FOR_10(B, C, D, E, F, G, H, I, J, K, M __VA_OPT__(,) __VA_ARGS__)
-#define FOR_12(A, B, C, D, E, F, G, H, I, J, K, L, M, ...)	\
+#define FOR_12(A, B, C, D, E, F, G, H, I, J, K, L, M, ...) \
 	FOR_4(A, B, C, D, M __VA_OPT__(,) __VA_ARGS__) \
 	FOR_4(E, F, G, H, M __VA_OPT__(,) __VA_ARGS__) \
 	FOR_4(I, J, K, L, M __VA_OPT__(,) __VA_ARGS__)
+#define FOR_13(A, B, C, D, E, F, G, H, I, J, K, L, N, M, ...) \
+	M(__VA_ARGS__ __VA_OPT__(,) A) \
+	FOR_12(B, C, D, E, F, G, H, I, J, K, L, N, M __VA_OPT__(,) __VA_ARGS__)
+#define FOR_14(A, B, C, D, E, F, G, H, I, J, K, L, N, O, M, ...) \
+	FOR_7(A, B, C, D, E, F, G, M __VA_OPT__(,) __VA_ARGS__) \
+	FOR_7(H, I, J, K, L, N, O, M __VA_OPT__(,) __VA_ARGS__)
 ///@endcond

include/blackmagic/join.h

@@ -22,5 +22,6 @@
  * @code{.c}
  * prefix_name_2
  * @endcode
+ * @since 0.2
  */
 #define JOIN(...) FOLD(JOIN2 __VA_OPT__(,) __VA_ARGS__)

include/blackmagic/pair.h

@@ -12,5 +12,6 @@
 
 /** Expand to both elements of a pair following each other */
 #define PAIR_FLATTEN(A, B) A B
+
 /** Expands to an assignation */
 #define PAIR_ASSIGN(A, B) A = B

include/blackmagic/white.h

@@ -0,0 +1,25 @@
+#pragma once
+
+/**
+ * @file
+ * White magic: Straightforward macros
+ */
+
+/**
+ * Number of elements of a C array.
+ *
+ * __Example__
+ * @code{.c}
+ * short    foo    = {21, 84, 57};
+ * unsigned length = ARRAY_LENGTH(foo);
+ * @endcode
+ * Will result in `length = 3`
+ * @since 0.2
+ */
+#define ARRAY_LENGTH(ARRAY) (sizeof(ARRAY) / sizeof(*(ARRAY)))
+
+/** Highest of two numbers */
+#define max(A, B) ({ typeof(A) _a = (A); typeof(B) _b = (B); _a >= _b ? _a : _b; })
+
+/** Lowest of two numbers */
+#define min(A, B) ({ typeof(A) _a = (A); typeof(B) _b = (B); _a <= _b ? _a : _b; })