qxLib
asserts.h
Go to the documentation of this file.
1 /**
2 
3  @file asserts.h
4  @author Khrapov
5  @date 27.12.2025
6  @copyright © Nick Khrapov, 2025. All right reserved.
7 
8  @section qx_assert_table Assert Types Comparison Table
9 
10  | Assertion type | Crash on failure | Remains in shipping (can have side effects) | Returns condition | Description |
11  |:--------------:|:----------------:|:-------------------------------------------:|:-----------------:|-------------|
12  | QX_ASSERT | + | - | - | Fast fail, similar to `assert()` |
13  | QX_VERIFY | + | + | - | Critical places: allocation errors, security checks, encryption, anti-cheat, etc. |
14  | QX_EXPECT | - | + | + | Defensive programming |
15  | QX_ENSURE | - | - | - | Possibly heavy checks that will not stay in a fast build |
16 
17 **/
18 #pragma once
19 
21 
22 #include <qx/asserts/asserts.inl>
23 
24 /**
25  @brief Use this as a condition in any macro above to indicate that this part of your code must never be executed
26 **/
27 #define QX_NO_ENTRY (false && "No entry")
28 
29 /**
30  @brief Use this as a condition in any macro above to indicate that this part of your code is not ready yet
31 **/
32 #define QX_NOT_IMPLEMENTED (false && "Not implemented")
33 
34 /**
35  @brief Verifies that the condition is true
36  @details QX_ASSERT macros generate fatal failures and disappear in shipping. See @ref qx_assert_table for details.
37  @param condition - a condition to check. if false, assert fails
38  @param category - a category to use for logging and reporting
39  @param ... - optional user message and its format args. the format string should be without QXT
40 **/
41 #define QX_ASSERT_C(condition, category, ...) QX_DETAILS_ASSERT_C(condition, category __VA_OPT__(, ) __VA_ARGS__)
42 
43 /**
44  @brief Verifies that the condition is true
45  @details QX_ASSERT macros generate fatal failures and disappear in shipping. See @ref qx_assert_table for details.
46  @param condition - a condition to check. if false, assert fails
47  @param ... - optional user message and its format args. the format string should be without QXT
48 **/
49 #define QX_ASSERT(condition, ...) QX_ASSERT_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)
50 
51 /**
52  @brief Verifies that the condition is true
53  @details QX_VERIFY macros generate fatal failures and remain in shipping. See @ref qx_assert_table for details.
54  @param condition - a condition to check. if false, assert fails
55  @param category - a category to use for logging and reporting
56  @param ... - optional user message and its format args. the format string should be without QXT
57 **/
58 #define QX_VERIFY_C(condition, category, ...) \
59  QX_DETAILS_COMMON_ASSERT( \
60  condition, \
61  category, \
62  qx::assert_type::verify, \
63  QX_DETAILS_ASSERT_AFTER_DEBUG_BREAK_FATAL, \
64  void __VA_OPT__(, ) __VA_ARGS__)
65 
66 /**
67  @brief Verifies that the condition is true
68  @details QX_VERIFY macros generate fatal failures and remain in shipping. See @ref qx_assert_table for details.
69  @param condition - a condition to check. if false, assert fails
70  @param ... - optional user message and its format args. the format string should be without QXT
71 **/
72 #define QX_VERIFY(condition, ...) QX_VERIFY_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)
73 
74 /**
75  @brief Verifies that the condition is true
76  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
77  @param condition - a condition to check. if false, assert fails
78  @param category - a category to use for logging and reporting
79  @param ... - optional user message and its format args. the format string should be without QXT
80  @return - condition
81 **/
82 #define QX_EXPECT_C(condition, category, ...) \
83  QX_DETAILS_COMMON_ASSERT( \
84  condition, \
85  category, \
86  qx::assert_type::expect, \
87  QX_DETAILS_ASSERT_AFTER_DEBUG_BREAK_NON_FATAL, \
88  bool __VA_OPT__(, ) __VA_ARGS__)
89 
90 /**
91  @brief Verifies that the condition is true
92  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
93  @param condition - a condition to check. if false, assert fails
94  @param ... - optional user message and its format args. the format string should be without QXT
95  @return - condition
96 **/
97 #define QX_EXPECT(condition, ...) QX_EXPECT_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)
98 
99 /**
100  @brief Verifies that the condition is true and calls continue; otherwise
101  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
102  @param condition - a condition to check. if false, assert fails
103  @param category - a category to use for logging and reporting
104  @param ... - optional user message and its format args. the format string should be without QXT
105 **/
106 #define QX_EXPECT_CONTINUE_C(condition, category, ...) \
107  QX_DETAILS_EXPECT_ACTION(condition, category, continue __VA_OPT__(, ) __VA_ARGS__)
108 
109 /**
110  @brief Verifies that the condition is true and calls continue; otherwise
111  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
112  @param condition - a condition to check. if false, assert fails
113  @param ... - optional user message and its format args. the format string should be without QXT
114 **/
115 #define QX_EXPECT_CONTINUE(condition, ...) \
116  QX_EXPECT_CONTINUE_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)
117 
118 /**
119  @brief Verifies that the condition is true and calls break; otherwise
120  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
121  @param condition - a condition to check. if false, assert fails
122  @param category - a category to use for logging and reporting
123  @param ... - optional user message and its format args. the format string should be without QXT
124 **/
125 #define QX_EXPECT_BREAK_C(condition, category, ...) \
126  QX_DETAILS_EXPECT_ACTION(condition, category, break __VA_OPT__(, ) __VA_ARGS__)
127 
128 /**
129  @brief Verifies that the condition is true and calls break; otherwise
130  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
131  @param condition - a condition to check. if false, assert fails
132  @param ... - optional user message and its format args. the format string should be without QXT
133 **/
134 #define QX_EXPECT_BREAK(condition, ...) QX_EXPECT_BREAK_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)
135 
136 /**
137  @brief Verifies that the condition is true and calls return; otherwise
138  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
139  @param condition - a condition to check. if false, assert fails
140  @param category - a category to use for logging and reporting
141  @param ... - optional user message and its format args. the format string should be without QXT
142 **/
143 #define QX_EXPECT_RETURN_C(condition, category, ...) \
144  QX_DETAILS_EXPECT_ACTION(condition, category, return __VA_OPT__(, ) __VA_ARGS__)
145 
146 /**
147  @brief Verifies that the condition is true and calls return; otherwise
148  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
149  @param condition - a condition to check. if false, assert fails
150  @param ... - optional user message and its format args. the format string should be without QXT
151 **/
152 #define QX_EXPECT_RETURN(condition, ...) \
153  QX_EXPECT_RETURN_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)
154 
155 /**
156  @brief Verifies that the condition is true and calls return return_value; otherwise
157  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
158  @param condition - a condition to check. if false, assert fails
159  @param category - a category to use for logging and reporting
160  @param return_value - a value to return in case of failure
161  @param ... - optional user message and its format args. the format string should be without QXT
162 **/
163 #define QX_EXPECT_RETURN_CT(condition, category, return_value, ...) \
164  QX_DETAILS_EXPECT_ACTION(condition, category, return return_value __VA_OPT__(, ) __VA_ARGS__)
165 
166 /**
167  @brief Verifies that the condition is true and calls return return_value; otherwise
168  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
169  @param condition - a condition to check. if false, assert fails
170  @param return_value - a value to return in case of failure
171  @param ... - optional user message and its format args. the format string should be without QXT
172 **/
173 #define QX_EXPECT_RETURN_T(condition, return_value, ...) \
174  QX_EXPECT_RETURN_CT(condition, QX_GET_FILE_CATEGORY(), return_value __VA_OPT__(, ) __VA_ARGS__)
175 
176 /**
177  @brief Verifies that the condition is true and calls co_return; otherwise
178  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
179  @param condition - a condition to check. if false, assert fails
180  @param category - a category to use for logging and reporting
181  @param ... - optional user message and its format args. the format string should be without QXT
182 **/
183 #define QX_EXPECT_CO_RETURN_C(condition, category, ...) \
184  QX_DETAILS_EXPECT_ACTION(condition, category, co_return __VA_OPT__(, ) __VA_ARGS__)
185 
186 /**
187  @brief Verifies that the condition is true and calls co_return; otherwise
188  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
189  @param condition - a condition to check. if false, assert fails
190  @param ... - optional user message and its format args. the format string should be without QXT
191 **/
192 #define QX_EXPECT_CO_RETURN(condition, ...) \
193  QX_EXPECT_CO_RETURN_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)
194 
195 /**
196  @brief Verifies that the condition is true and calls co_return return_value; otherwise
197  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
198  @param condition - a condition to check. if false, assert fails
199  @param category - a category to use for logging and reporting
200  @param return_value - a value to return in case of failure
201  @param ... - optional user message and its format args. the format string should be without QXT
202 **/
203 #define QX_EXPECT_CO_RETURN_CT(condition, category, return_value, ...) \
204  QX_DETAILS_EXPECT_ACTION(condition, category, co_return return_value __VA_OPT__(, ) __VA_ARGS__)
205 
206 /**
207  @brief Verifies that the condition is true and calls co_return return_value; otherwise
208  @details QX_EXPECT macros generate nonfatal failures and remain in shipping. See @ref qx_assert_table for details.
209  @param condition - a condition to check. if false, assert fails
210  @param return_value - a value to return in case of failure
211  @param ... - optional user message and its format args. the format string should be without QXT
212 **/
213 #define QX_EXPECT_CO_RETURN_T(condition, return_value, ...) \
214  QX_EXPECT_CO_RETURN_CT(condition, QX_GET_FILE_CATEGORY(), return_value __VA_OPT__(, ) __VA_ARGS__)
215 
216 /**
217  @brief Verifies that the condition is true
218  @details QX_ENSURE macros generate nonfatal failures and disappear in shipping. See @ref qx_assert_table for details.
219  @param condition - a condition to check. if false, assert fails
220  @param category - a category to use for logging and reporting
221  @param ... - optional user message and its format args. the format string should be without QXT
222 **/
223 #define QX_ENSURE_C(condition, category, ...) QX_DETAILS_ENSURE_C(condition, category __VA_OPT__(, ) __VA_ARGS__)
224 
225 /**
226  @brief Verifies that the condition is true
227  @details QX_ENSURE macros generate nonfatal failures and disappear in shipping. See @ref qx_assert_table for details.
228  @param condition - a condition to check. if false, assert fails
229  @param ... - optional user message and its format args. the format string should be without QXT
230 **/
231 #define QX_ENSURE(condition, ...) QX_ENSURE_C(condition, QX_GET_FILE_CATEGORY() __VA_OPT__(, ) __VA_ARGS__)