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