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