assertables/assert_fn/assert_fn_eq_x.rs
1//! Assert a function output is equal to an expression.
2//!
3//! Pseudocode:<br>
4//! function(a) = b
5//!
6//! # Example
7//!
8//! ```rust
9//! use assertables::*;
10//!
11//! let a: i8 = -1;
12//! let b: i8 = 1;
13//! assert_fn_eq_x!(i8::abs, a, b);
14//! ```
15//!
16//! # Module macros
17//!
18//! * [`assert_fn_eq_x`](macro@crate::assert_fn_eq_x)
19//! * [`assert_fn_eq_x_as_result`](macro@crate::assert_fn_eq_x_as_result)
20//! * [`debug_assert_fn_eq_x`](macro@crate::debug_assert_fn_eq_x)
21
22/// Assert a function output is equal to an expression.
23///
24/// Pseudocode:<br>
25/// function(a) = b
26///
27/// * If true, return Result `Ok(a)`.
28///
29/// * Otherwise, return Result `Err(message)`.
30///
31/// This macro is useful for runtime checks, such as checking parameters,
32/// or sanitizing inputs, or handling different results in different ways.
33///
34/// # Module macros
35///
36/// * [`assert_fn_eq_x`](macro@crate::assert_fn_eq_x)
37/// * [`assert_fn_eq_x_as_result`](macro@crate::assert_fn_eq_x_as_result)
38/// * [`debug_assert_fn_eq_x`](macro@crate::debug_assert_fn_eq_x)
39///
40#[macro_export]
41macro_rules! assert_fn_eq_x_as_result {
42
43 //// Arity 1
44
45 ($a_function:path, $a_param:expr, $b_expr:expr $(,)?) => {{
46 match (&$a_function, &$a_param, &$b_expr) {
47 (_a_function, a_param, b_expr) => {
48 let a = $a_function($a_param);
49 if a == $b_expr {
50 Ok(a)
51 } else {
52 Err(
53 format!(
54 concat!(
55 "assertion failed: `assert_fn_eq_x!(a_function, a_param, b_expr)`\n",
56 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html\n",
57 " a_function label: `{}`,\n",
58 " a_param label: `{}`,\n",
59 " a_param debug: `{:?}`,\n",
60 " b_expr label: `{}`,\n",
61 " b_expr debug: `{:?}`,\n",
62 " a: `{:?}`,\n",
63 " b: `{:?}`"
64 ),
65 stringify!($a_function),
66 stringify!($a_param),
67 a_param,
68 stringify!($b_expr),
69 b_expr,
70 a,
71 b_expr
72 )
73 )
74 }
75 }
76 }
77 }};
78
79 //// Arity 0
80
81 ($a_function:path, $b_expr:expr $(,)?) => {{
82 match (&$a_function, &$b_expr) {
83 (_a_function, b_expr) => {
84 let a = $a_function();
85 if a == $b_expr {
86 Ok(a)
87 } else {
88 Err(
89 format!(
90 concat!(
91 "assertion failed: `assert_fn_eq_x!(a_function, b_expr)`\n",
92 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html\n",
93 " a_function label: `{}`,\n",
94 " b_expr label: `{}`,\n",
95 " b_expr debug: `{:?}`,\n",
96 " a: `{:?}`,\n",
97 " b: `{:?}`"
98 ),
99 stringify!($a_function),
100 stringify!($b_expr),
101 b_expr,
102 a,
103 b_expr
104 )
105 )
106 }
107 }
108 }
109 }};
110
111}
112
113#[cfg(test)]
114mod test_assert_fn_eq_x_as_result {
115
116 mod arity_1 {
117
118 fn f(i: i8) -> i8 {
119 return i;
120 }
121
122 #[test]
123 fn eq() {
124 let a: i8 = 1;
125 let b: i8 = 1;
126 let actual = assert_fn_eq_x_as_result!(f, a, b);
127 assert_eq!(actual.unwrap(), 1);
128 }
129
130 #[test]
131 fn failure() {
132 let a: i8 = 1;
133 let b: i8 = 2;
134 let actual = assert_fn_eq_x_as_result!(f, a, b);
135 let message = concat!(
136 "assertion failed: `assert_fn_eq_x!(a_function, a_param, b_expr)`\n",
137 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html\n",
138 " a_function label: `f`,\n",
139 " a_param label: `a`,\n",
140 " a_param debug: `1`,\n",
141 " b_expr label: `b`,\n",
142 " b_expr debug: `2`,\n",
143 " a: `1`,\n",
144 " b: `2`"
145 );
146 assert_eq!(actual.unwrap_err(), message);
147 }
148 }
149
150 mod arity_0 {
151
152 fn f() -> i8 {
153 return 1;
154 }
155
156 #[test]
157 fn eq() {
158 let b: i8 = 1;
159 let actual = assert_fn_eq_x_as_result!(f, b);
160 assert_eq!(actual.unwrap(), 1);
161 }
162
163 #[test]
164 fn ne() {
165 let b: i8 = 2;
166 let actual = assert_fn_eq_x_as_result!(f, b);
167 let message = concat!(
168 "assertion failed: `assert_fn_eq_x!(a_function, b_expr)`\n",
169 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html\n",
170 " a_function label: `f`,\n",
171 " b_expr label: `b`,\n",
172 " b_expr debug: `2`,\n",
173 " a: `1`,\n",
174 " b: `2`"
175 );
176 assert_eq!(actual.unwrap_err(), message);
177 }
178 }
179}
180
181/// Assert a function output is equal to an expression.
182///
183/// Pseudocode:<br>
184/// function(a) = b
185///
186/// * If true, return `a`.
187///
188/// * Otherwise, call [`panic!`] with a message and the values of the
189/// expressions with their debug representations.
190///
191/// # Examples
192///
193/// ```rust
194/// use assertables::*;
195/// # use std::panic;
196///
197/// # fn main() {
198/// let a: i8 = -1;
199/// let b: i8 = 1;
200/// assert_fn_eq_x!(i8::abs, a, b);
201///
202/// # let result = panic::catch_unwind(|| {
203/// // This will panic
204/// let a: i8 = -1;
205/// let b: i8 = 2;
206/// assert_fn_eq_x!(i8::abs, a, b);
207/// # });
208/// // assertion failed: `assert_fn_eq_x!(a_function, a_param, b_expr)`
209/// // https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html
210/// // a_function label: `i8::abs`,
211/// // a_param label: `a`,
212/// // a_param debug: `-1`,
213/// // b_expr label: `b`,
214/// // b_expr debug: `2`,
215/// // a: `1`,
216/// // b: `2`
217/// # let actual = result.unwrap_err().downcast::<String>().unwrap().to_string();
218/// # let message = concat!(
219/// # "assertion failed: `assert_fn_eq_x!(a_function, a_param, b_expr)`\n",
220/// # "https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html\n",
221/// # " a_function label: `i8::abs`,\n",
222/// # " a_param label: `a`,\n",
223/// # " a_param debug: `-1`,\n",
224/// # " b_expr label: `b`,\n",
225/// # " b_expr debug: `2`,\n",
226/// # " a: `1`,\n",
227/// # " b: `2`"
228/// # );
229/// # assert_eq!(actual, message);
230/// # }
231/// ```
232///
233/// # Module macros
234///
235/// * [`assert_fn_eq_x`](macro@crate::assert_fn_eq_x)
236/// * [`assert_fn_eq_x_as_result`](macro@crate::assert_fn_eq_x_as_result)
237/// * [`debug_assert_fn_eq_x`](macro@crate::debug_assert_fn_eq_x)
238///
239#[macro_export]
240macro_rules! assert_fn_eq_x {
241
242 //// Arity 1
243
244 ($a_function:path, $a_param:expr, $b_expr:expr $(,)?) => {{
245 match $crate::assert_fn_eq_x_as_result!($a_function, $a_param, $b_expr) {
246 Ok(x) => x,
247 Err(err) => panic!("{}", err),
248 }
249 }};
250
251 ($a_function:path, $a_param:expr, $b_expr:expr, $($message:tt)+) => {{
252 match $crate::assert_fn_eq_x_as_result!($a_function, $a_param, $b_expr) {
253 Ok(x) => x,
254 Err(err) => panic!("{}\n{}", format_args!($($message)+), err),
255 }
256 }};
257
258 //// Arity 0
259
260 ($a_function:path, $b_expr:expr $(,)?) => {{
261 match $crate::assert_fn_eq_x_as_result!($a_function, $b_expr) {
262 Ok(x) => x,
263 Err(err) => panic!("{}", err),
264 }
265 }};
266
267 ($a_function:path, $b_expr:expr, $($message:tt)+) => {{
268 match $crate::assert_fn_eq_x_as_result!($a_function, $a_param, $b_expr) {
269 Ok(x) => x,
270 Err(err) => panic!("{}\n{}", format_args!($($message)+), err),
271 }
272 }};
273
274}
275
276#[cfg(test)]
277mod test_assert_fn_eq_x {
278 use std::panic;
279
280 mod arity_1 {
281 use super::*;
282
283 fn f(i: i8) -> i8 {
284 return i;
285 }
286
287 #[test]
288 fn eq() {
289 let a: i8 = 1;
290 let b: i8 = 1;
291 let actual = assert_fn_eq_x!(f, a, b);
292 assert_eq!(actual, 1);
293 }
294
295 #[test]
296 fn failure() {
297 let result = panic::catch_unwind(|| {
298 let a: i8 = 1;
299 let b: i8 = 2;
300 let _actual = assert_fn_eq_x!(f, a, b);
301 });
302 let message = concat!(
303 "assertion failed: `assert_fn_eq_x!(a_function, a_param, b_expr)`\n",
304 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html\n",
305 " a_function label: `f`,\n",
306 " a_param label: `a`,\n",
307 " a_param debug: `1`,\n",
308 " b_expr label: `b`,\n",
309 " b_expr debug: `2`,\n",
310 " a: `1`,\n",
311 " b: `2`"
312 );
313 assert_eq!(
314 result
315 .unwrap_err()
316 .downcast::<String>()
317 .unwrap()
318 .to_string(),
319 message
320 );
321 }
322 }
323
324 mod arity_0 {
325 use super::*;
326
327 fn f() -> i8 {
328 return 1;
329 }
330
331 #[test]
332 fn eq() {
333 let b: i8 = 1;
334 let actual = assert_fn_eq_x!(f, b);
335 assert_eq!(actual, 1);
336 }
337
338 #[test]
339 fn ne() {
340 let result = panic::catch_unwind(|| {
341 let b: i8 = 2;
342 let _actual = assert_fn_eq_x!(f, b);
343 });
344 let message = concat!(
345 "assertion failed: `assert_fn_eq_x!(a_function, b_expr)`\n",
346 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_fn_eq_x.html\n",
347 " a_function label: `f`,\n",
348 " b_expr label: `b`,\n",
349 " b_expr debug: `2`,\n",
350 " a: `1`,\n",
351 " b: `2`"
352 );
353 assert_eq!(
354 result
355 .unwrap_err()
356 .downcast::<String>()
357 .unwrap()
358 .to_string(),
359 message
360 );
361 }
362 }
363}
364
365/// Assert a function output is equal to an expression.
366///
367/// Pseudocode:<br>
368/// function(a) = b
369///
370/// This macro provides the same statements as [`assert_fn_eq_x`](macro.assert_fn_eq_x.html),
371/// except this macro's statements are only enabled in non-optimized
372/// builds by default. An optimized build will not execute this macro's
373/// statements unless `-C debug-assertions` is passed to the compiler.
374///
375/// This macro is useful for checks that are too expensive to be present
376/// in a release build but may be helpful during development.
377///
378/// The result of expanding this macro is always type checked.
379///
380/// An unchecked assertion allows a program in an inconsistent state to
381/// keep running, which might have unexpected consequences but does not
382/// introduce unsafety as long as this only happens in safe code. The
383/// performance cost of assertions, however, is not measurable in general.
384/// Replacing `assert*!` with `debug_assert*!` is thus only encouraged
385/// after thorough profiling, and more importantly, only in safe code!
386///
387/// This macro is intended to work in a similar way to
388/// [`::std::debug_assert`](https://doc.rust-lang.org/std/macro.debug_assert.html).
389///
390/// # Module macros
391///
392/// * [`assert_fn_eq_x`](macro@crate::assert_fn_eq_x)
393/// * [`assert_fn_eq_x`](macro@crate::assert_fn_eq_x)
394/// * [`debug_assert_fn_eq_x`](macro@crate::debug_assert_fn_eq_x)
395///
396#[macro_export]
397macro_rules! debug_assert_fn_eq_x {
398 ($($arg:tt)*) => {
399 if $crate::cfg!(debug_assertions) {
400 $crate::assert_fn_eq_x!($($arg)*);
401 }
402 };
403}