assertables/assert_fn_err/assert_fn_err_lt_x.rs
1//! Assert a function Err(…) is less than an expression.
2//!
3//! Pseudocode:<br>
4//! (function(param) ⇒ Err(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 = 10;
18//! let b = String::from("20 is out of range");
19//! assert_fn_err_lt_x!(f, a, b);
20//! ```
21//!
22//! # Module macros
23//!
24//! * [`assert_fn_err_lt_x`](macro@crate::assert_fn_err_lt_x)
25//! * [`assert_fn_err_lt_x_as_result`](macro@crate::assert_fn_err_lt_x_as_result)
26//! * [`debug_assert_fn_err_lt_x`](macro@crate::debug_assert_fn_err_lt_x)
27
28/// Assert a function error is less than an expression.
29///
30/// Pseudocode:<br>
31/// (function(param) ⇒ Err(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_err_lt_x`](macro@crate::assert_fn_err_lt_x)
43/// * [`assert_fn_err_lt_x_as_result`](macro@crate::assert_fn_err_lt_x_as_result)
44/// * [`debug_assert_fn_err_lt_x`](macro@crate::debug_assert_fn_err_lt_x)
45///
46#[macro_export]
47macro_rules! assert_fn_err_lt_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 Err(a) => {
56 if a < $b_expr {
57 Ok(a)
58 } else {
59 Err(
60 format!(
61 concat!(
62 "assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`\n",
63 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_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 a => {
84 Err(
85 format!(
86 concat!(
87 "assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`\n",
88 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_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: `{:?}`",
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 Err(a) => {
117 if a < $b_expr {
118 Ok(a)
119 } else {
120 Err(
121 format!(
122 concat!(
123 "assertion failed: `assert_fn_err_lt_x!(a_function, b_expr)`\n",
124 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_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_err_lt_x!(a_function, b_expr)`\n",
145 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_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
165#[cfg(test)]
166mod test_assert_fn_err_lt_x_as_result {
167 // use std::sync::Once;
168
169 mod arity_1 {
170
171 fn f(i: i8) -> Result<i8, i8> {
172 Err(i)
173 }
174
175 #[test]
176 fn lt() {
177 let a: i8 = 1;
178 let b: i8 = 2;
179 for _ in 0..1 {
180 let actual = assert_fn_err_lt_x_as_result!(f, a, b);
181 assert_eq!(actual.unwrap(), 1);
182 }
183 }
184
185 #[test]
186 fn eq() {
187 let a: i8 = 1;
188 let b: i8 = 1;
189 let actual = assert_fn_err_lt_x_as_result!(f, a, b);
190 let message = concat!(
191 "assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`\n",
192 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
193 " a_function label: `f`,\n",
194 " a_param label: `a`,\n",
195 " a_param debug: `1`,\n",
196 " b_expr label: `b`,\n",
197 " b_expr debug: `1`,\n",
198 " a: `1`,\n",
199 " b: `1`"
200 );
201 assert_eq!(actual.unwrap_err(), message);
202 }
203
204 #[test]
205 fn gt() {
206 let a: i8 = 1;
207 let b: i8 = 0;
208 let actual = assert_fn_err_lt_x_as_result!(f, a, b);
209 let message = concat!(
210 "assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`\n",
211 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
212 " a_function label: `f`,\n",
213 " a_param label: `a`,\n",
214 " a_param debug: `1`,\n",
215 " b_expr label: `b`,\n",
216 " b_expr debug: `0`,\n",
217 " a: `1`,\n",
218 " b: `0`"
219 );
220 assert_eq!(actual.unwrap_err(), message);
221 }
222 }
223
224 mod arity_0 {
225
226 fn f() -> Result<i8, i8> {
227 Err(1)
228 }
229
230 #[test]
231 fn lt() {
232 let b: i8 = 2;
233 for _ in 0..1 {
234 let actual = assert_fn_err_lt_x_as_result!(f, b);
235 assert_eq!(actual.unwrap(), 1);
236 }
237 }
238
239 #[test]
240 fn eq() {
241 let b: i8 = 1;
242 let actual = assert_fn_err_lt_x_as_result!(f, b);
243 let message = concat!(
244 "assertion failed: `assert_fn_err_lt_x!(a_function, b_expr)`\n",
245 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
246 " a_function label: `f`,\n",
247 " b_expr label: `b`,\n",
248 " b_expr debug: `1`,\n",
249 " a: `1`,\n",
250 " b: `1`"
251 );
252 assert_eq!(actual.unwrap_err(), message);
253 }
254
255 #[test]
256 fn gt() {
257 let b: i8 = 0;
258 let actual = assert_fn_err_lt_x_as_result!(f, b);
259 let message = concat!(
260 "assertion failed: `assert_fn_err_lt_x!(a_function, b_expr)`\n",
261 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
262 " a_function label: `f`,\n",
263 " b_expr label: `b`,\n",
264 " b_expr debug: `0`,\n",
265 " a: `1`,\n",
266 " b: `0`"
267 );
268 assert_eq!(actual.unwrap_err(), message);
269 }
270 }
271}
272
273/// Assert a function error is less than an expression.
274///
275/// Pseudocode:<br>
276/// (function(param) ⇒ Err(a) ⇒ a) < expr
277///
278/// * If true, return `a`.
279///
280/// * Otherwise, call [`panic!`] with a message and the values of the
281/// expressions with their debug representations.
282///
283/// # Examples
284///
285/// ```rust
286/// use assertables::*;
287/// # use std::panic;
288/// fn f(i: i8) -> Result<String, String> {
289/// match i {
290/// 0..=9 => Ok(format!("{}", i)),
291/// _ => Err(format!("{:?} is out of range", i)),
292/// }
293/// }
294///
295/// # fn main() {
296/// let a: i8 = 10;
297/// let b = String::from("20 is out of range");
298/// assert_fn_err_lt_x!(f, a, b);
299///
300/// # let result = panic::catch_unwind(|| {
301/// // This will panic
302/// let a: i8 = 20;
303/// let b = String::from("10 is out of range");
304/// assert_fn_err_lt_x!(f, a, b);
305/// # });
306/// // assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`
307/// // https://docs.rs/assertables/…/assertables/macro.assert_fn_err_lt_x.html
308/// // a_function label: `f`,
309/// // a_param label: `a`,
310/// // a_param debug: `20`,
311/// // b_expr label: `b`,
312/// // b_expr debug: `\"10 is out of range\"`,
313/// // a: `\"20 is out of range\"`,
314/// // b: `\"10 is out of range\"`
315/// # let actual = result.unwrap_err().downcast::<String>().unwrap().to_string();
316/// # let message = concat!(
317/// # "assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`\n",
318/// # "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
319/// # " a_function label: `f`,\n",
320/// # " a_param label: `a`,\n",
321/// # " a_param debug: `20`,\n",
322/// # " b_expr label: `b`,\n",
323/// # " b_expr debug: `\"10 is out of range\"`,\n",
324/// # " a: `\"20 is out of range\"`,\n",
325/// # " b: `\"10 is out of range\"`"
326/// # );
327/// # assert_eq!(actual, message);
328/// # }
329/// ```
330///
331/// # Module macros
332///
333/// * [`assert_fn_err_lt_x`](macro@crate::assert_fn_err_lt_x)
334/// * [`assert_fn_err_lt_x_as_result`](macro@crate::assert_fn_err_lt_x_as_result)
335/// * [`debug_assert_fn_err_lt_x`](macro@crate::debug_assert_fn_err_lt_x)
336///
337#[macro_export]
338macro_rules! assert_fn_err_lt_x {
339
340 //// Arity 1
341
342 ($a_function:path, $a_param:expr, $b_expr:expr $(,)?) => {
343 match $crate::assert_fn_err_lt_x_as_result!($a_function, $a_param, $b_expr) {
344 Ok(x) => x,
345 Err(err) => panic!("{}", err),
346 }
347 };
348
349 ($a_function:path, $a_param:expr, $b_expr:expr, $($message:tt)+) => {
350 match $crate::assert_fn_err_lt_x_as_result!($a_function, $a_param, $b_expr) {
351 Ok(x) => x,
352 Err(err) => panic!("{}\n{}", format_args!($($message)+), err),
353 }
354 };
355
356 //// Arity 0
357
358 ($a_function:path, $b_expr:expr $(,)?) => {
359 match $crate::assert_fn_err_lt_x_as_result!($a_function, $b_expr) {
360 Ok(x) => x,
361 Err(err) => panic!("{}", err),
362 }
363 };
364
365 ($a_function:path, $b_expr:expr, $($message:tt)+) => {
366 match $crate::assert_fn_err_lt_x_as_result!($a_function, $b_expr) {
367 Ok(x) => x,
368 Err(err) => panic!("{}\n{}", format_args!($($message)+), err),
369 }
370 };
371}
372
373#[cfg(test)]
374mod test_assert_fn_err_lt_x {
375 use std::panic;
376
377 mod arity_1 {
378 use super::*;
379
380 fn f(i: i8) -> Result<i8, i8> {
381 Err(i)
382 }
383
384 #[test]
385 fn lt() {
386 let a: i8 = 1;
387 let b: i8 = 2;
388 for _ in 0..1 {
389 let actual = assert_fn_err_lt_x!(f, a, b);
390 assert_eq!(actual, 1);
391 }
392 }
393
394 #[test]
395 fn eq() {
396 let result = panic::catch_unwind(|| {
397 let a: i8 = 1;
398 let b: i8 = 1;
399 let _actual = assert_fn_err_lt_x!(f, a, b);
400 });
401 let message = concat!(
402 "assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`\n",
403 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
404 " a_function label: `f`,\n",
405 " a_param label: `a`,\n",
406 " a_param debug: `1`,\n",
407 " b_expr label: `b`,\n",
408 " b_expr debug: `1`,\n",
409 " a: `1`,\n",
410 " b: `1`"
411 );
412 assert_eq!(
413 result
414 .unwrap_err()
415 .downcast::<String>()
416 .unwrap()
417 .to_string(),
418 message
419 );
420 }
421
422 #[test]
423 fn gt() {
424 let result = panic::catch_unwind(|| {
425 let a: i8 = 1;
426 let b: i8 = 0;
427 let _actual = assert_fn_err_lt_x!(f, a, b);
428 });
429 let message = concat!(
430 "assertion failed: `assert_fn_err_lt_x!(a_function, a_param, b_expr)`\n",
431 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
432 " a_function label: `f`,\n",
433 " a_param label: `a`,\n",
434 " a_param debug: `1`,\n",
435 " b_expr label: `b`,\n",
436 " b_expr debug: `0`,\n",
437 " a: `1`,\n",
438 " b: `0`"
439 );
440 assert_eq!(
441 result
442 .unwrap_err()
443 .downcast::<String>()
444 .unwrap()
445 .to_string(),
446 message
447 );
448 }
449 }
450
451 mod arity_0 {
452 use super::*;
453
454 fn f() -> Result<i8, i8> {
455 Err(1)
456 }
457
458 #[test]
459 fn lt() {
460 let b: i8 = 2;
461 for _ in 0..1 {
462 let actual = assert_fn_err_lt_x!(f, b);
463 assert_eq!(actual, 1);
464 }
465 }
466
467 #[test]
468 fn eq() {
469 let result = panic::catch_unwind(|| {
470 let b: i8 = 1;
471 let _actual = assert_fn_err_lt_x!(f, b);
472 });
473 let message = concat!(
474 "assertion failed: `assert_fn_err_lt_x!(a_function, b_expr)`\n",
475 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
476 " a_function label: `f`,\n",
477 " b_expr label: `b`,\n",
478 " b_expr debug: `1`,\n",
479 " a: `1`,\n",
480 " b: `1`"
481 );
482 assert_eq!(
483 result
484 .unwrap_err()
485 .downcast::<String>()
486 .unwrap()
487 .to_string(),
488 message
489 );
490 }
491
492 #[test]
493 fn gt() {
494 let result = panic::catch_unwind(|| {
495 let b: i8 = 0;
496 let _actual = assert_fn_err_lt_x!(f, b);
497 });
498 let message = concat!(
499 "assertion failed: `assert_fn_err_lt_x!(a_function, b_expr)`\n",
500 "https://docs.rs/assertables/9.8.5/assertables/macro.assert_fn_err_lt_x.html\n",
501 " a_function label: `f`,\n",
502 " b_expr label: `b`,\n",
503 " b_expr debug: `0`,\n",
504 " a: `1`,\n",
505 " b: `0`"
506 );
507 assert_eq!(
508 result
509 .unwrap_err()
510 .downcast::<String>()
511 .unwrap()
512 .to_string(),
513 message
514 );
515 }
516 }
517}
518
519/// Assert a function error is less than an expression.
520///
521/// Pseudocode:<br>
522/// (function(param) ⇒ Err(a) ⇒ a) < expr
523///
524/// This macro provides the same statements as [`assert_fn_err_lt_x`](macro.assert_fn_err_lt_x.html),
525/// except this macro's statements are only enabled in non-optimized
526/// builds by default. An optimized build will not execute this macro's
527/// statements unless `-C debug-assertions` is passed to the compiler.
528///
529/// This macro is useful for checks that are too expensive to be present
530/// in a release build but may be helpful during development.
531///
532/// The result of expanding this macro is always type checked.
533///
534/// An unchecked assertion allows a program in an inconsistent state to
535/// keep running, which might have unexpected consequences but does not
536/// introduce unsafety as long as this only happens in safe code. The
537/// performance cost of assertions, however, is not measurable in general.
538/// Replacing `assert*!` with `debug_assert*!` is thus only encouraged
539/// after thorough profiling, and more importantly, only in safe code!
540///
541/// This macro is intended to work in a similar way to
542/// [`::std::debug_assert`](https://doc.rust-lang.org/std/macro.debug_assert.html).
543///
544/// # Module macros
545///
546/// * [`assert_fn_err_lt_x`](macro@crate::assert_fn_err_lt_x)
547/// * [`assert_fn_err_lt_x`](macro@crate::assert_fn_err_lt_x)
548/// * [`debug_assert_fn_err_lt_x`](macro@crate::debug_assert_fn_err_lt_x)
549///
550#[macro_export]
551macro_rules! debug_assert_fn_err_lt_x {
552 ($($arg:tt)*) => {
553 if cfg!(debug_assertions) {
554 $crate::assert_fn_err_lt_x!($($arg)*);
555 }
556 };
557}