assertables/assert_len/
assert_len_eq_x.rs

1//! Assert a length is equal to an expression.
2//!
3//! Pseudocode:<br>
4//! a.len() = b
5//!
6//! # Example
7//!
8//! ```rust
9//! use assertables::*;
10//!
11//! let a = "x";
12//! let b = 1;
13//! assert_len_eq_x!(a, b);
14//! ```
15//!
16//! # Module macros
17//!
18//! * [`assert_len_eq_x`](macro@crate::assert_len_eq_x)
19//! * [`assert_len_eq_x_as_result`](macro@crate::assert_len_eq_x_as_result)
20//! * [`debug_assert_len_eq_x`](macro@crate::debug_assert_len_eq_x)
21
22/// Assert a length is equal to an expression.
23///
24/// Pseudocode:<br>
25/// a.len() = b
26///
27/// * If true, return Result `Ok((a.len(), b))`.
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_len_eq_x`](macro@crate::assert_len_eq_x)
37/// * [`assert_len_eq_x_as_result`](macro@crate::assert_len_eq_x_as_result)
38/// * [`debug_assert_len_eq_x`](macro@crate::debug_assert_len_eq_x)
39///
40#[macro_export]
41macro_rules! assert_len_eq_x_as_result {
42    ($a:expr, $b:expr $(,)?) => {
43        match ($a, $b) {
44            (a, b) => {
45                let a_len = a.len();
46                if a_len == b {
47                    Ok((a_len, b))
48                } else {
49                    Err(
50                        format!(
51                            concat!(
52                                "assertion failed: `assert_len_eq_x!(a, b)`\n",
53                                "https://docs.rs/assertables/9.6.0/assertables/macro.assert_len_eq_x.html\n",
54                                " a label: `{}`,\n",
55                                " a debug: `{:?}`,\n",
56                                " a.len(): `{:?}`,\n",
57                                " b label: `{}`,\n",
58                                " b debug: `{:?}`"
59                            ),
60                            stringify!($a),
61                            a,
62                            a_len,
63                            stringify!($b),
64                            b
65                        )
66                    )
67                }
68            }
69        }
70    };
71}
72
73#[cfg(test)]
74mod test_assert_len_eq_x_as_result {
75    use std::sync::Once;
76
77    #[test]
78    fn eq() {
79        let a = "x";
80        let b = 1;
81        let actual = assert_len_eq_x_as_result!(a, b);
82        assert_eq!(actual.unwrap(), (1, 1));
83    }
84
85    #[test]
86    fn eq_once() {
87
88        static A: Once = Once::new();
89        fn a() -> &'static str {
90            if A.is_completed() { panic!("A.is_completed()") } else { A.call_once(|| {}) }
91            "x"
92        }
93
94        static B: Once = Once::new();
95        fn b() -> usize {
96            if B.is_completed() { panic!("B.is_completed()") } else { B.call_once(|| {}) }
97            1
98        }
99
100        assert_eq!(A.is_completed(), false);
101        assert_eq!(B.is_completed(), false);
102        let result = assert_len_eq_x_as_result!(a(), b());
103        assert!(result.is_ok());
104        assert_eq!(A.is_completed(), true);
105        assert_eq!(B.is_completed(), true);
106
107    }
108
109    #[test]
110    fn lt() {
111        let a = "x";
112        let b = 2;
113        let actual = assert_len_eq_x_as_result!(a, b);
114        let message = concat!(
115            "assertion failed: `assert_len_eq_x!(a, b)`\n",
116            "https://docs.rs/assertables/9.6.0/assertables/macro.assert_len_eq_x.html\n",
117            " a label: `a`,\n",
118            " a debug: `\"x\"`,\n",
119            " a.len(): `1`,\n",
120            " b label: `b`,\n",
121            " b debug: `2`"
122        );
123        assert_eq!(actual.unwrap_err(), message);
124    }
125
126    #[test]
127    fn gt() {
128        let a = "xx";
129        let b = 1;
130        let actual = assert_len_eq_x_as_result!(a, b);
131        let message = concat!(
132            "assertion failed: `assert_len_eq_x!(a, b)`\n",
133            "https://docs.rs/assertables/9.6.0/assertables/macro.assert_len_eq_x.html\n",
134            " a label: `a`,\n",
135            " a debug: `\"xx\"`,\n",
136            " a.len(): `2`,\n",
137            " b label: `b`,\n",
138            " b debug: `1`"
139        );
140        assert_eq!(actual.unwrap_err(), message);
141    }
142
143}
144
145/// Assert a length is equal to an expression.
146///
147/// Pseudocode:<br>
148/// a.len() = b
149///
150/// * If true, return `(a.len(), b)`.
151///
152/// * Otherwise, call [`panic!`] with a message and the values of the
153///   expressions with their debug representations.
154///
155/// # Examples
156///
157/// ```rust
158/// use assertables::*;
159/// # use std::panic;
160///
161/// # fn main() {
162/// let a = "x";
163/// let b = 1;
164/// assert_len_eq_x!(a, b);
165///
166/// # let result = panic::catch_unwind(|| {
167/// // This will panic
168/// let a = "x";
169/// let b = 2;
170/// assert_len_eq_x!(a, b);
171/// # });
172/// // assertion failed: `assert_len_eq_x!(a, b)`
173/// // https://docs.rs/assertables/9.6.0/assertables/macro.assert_len_eq_x.html
174/// //  a label: `a`,
175/// //  a debug: `\"x\"`,
176/// //  a.len(): `1`",
177/// //  b label: `b`,
178/// //  b debug: `2`
179/// # let actual = result.unwrap_err().downcast::<String>().unwrap().to_string();
180/// # let message = concat!(
181/// #     "assertion failed: `assert_len_eq_x!(a, b)`\n",
182/// #     "https://docs.rs/assertables/9.6.0/assertables/macro.assert_len_eq_x.html\n",
183/// #     " a label: `a`,\n",
184/// #     " a debug: `\"x\"`,\n",
185/// #     " a.len(): `1`,\n",
186/// #     " b label: `b`,\n",
187/// #     " b debug: `2`"
188/// # );
189/// # assert_eq!(actual, message);
190/// # }
191/// ```
192///
193/// # Module macros
194///
195/// * [`assert_len_eq_x`](macro@crate::assert_len_eq_x)
196/// * [`assert_len_eq_x_as_result`](macro@crate::assert_len_eq_x_as_result)
197/// * [`debug_assert_len_eq_x`](macro@crate::debug_assert_len_eq_x)
198///
199#[macro_export]
200macro_rules! assert_len_eq_x {
201    ($a:expr, $b:expr $(,)?) => {
202        match $crate::assert_len_eq_x_as_result!($a, $b) {
203            Ok(x) => x,
204            Err(err) => panic!("{}", err),
205        }
206    };
207    ($a:expr, $b:expr, $($message:tt)+) => {
208        match $crate::assert_len_eq_x_as_result!($a, $b) {
209            Ok(x) => x,
210            Err(err) => panic!("{}\n{}", format_args!($($message)+), err),
211        }
212    };
213}
214
215#[cfg(test)]
216mod test_assert_len_eq_x {
217    use std::panic;
218
219    #[test]
220    fn eq() {
221        let a = "x";
222        let b = 1;
223        let actual = assert_len_eq_x!(a, b);
224        assert_eq!(actual, (1, 1));
225    }
226
227    #[test]
228    fn lt() {
229        let a = "x";
230        let b = 2;
231        let result = panic::catch_unwind(|| {
232            let _actual = assert_len_eq_x!(a, b);
233        });
234        let message = concat!(
235            "assertion failed: `assert_len_eq_x!(a, b)`\n",
236            "https://docs.rs/assertables/9.6.0/assertables/macro.assert_len_eq_x.html\n",
237            " a label: `a`,\n",
238            " a debug: `\"x\"`,\n",
239            " a.len(): `1`,\n",
240            " b label: `b`,\n",
241            " b debug: `2`"
242        );
243        assert_eq!(
244            result
245                .unwrap_err()
246                .downcast::<String>()
247                .unwrap()
248                .to_string(),
249            message
250        );
251    }
252
253    #[test]
254    fn gt() {
255        let a = "xx";
256        let b = 1;
257        let result = panic::catch_unwind(|| {
258            let _actual = assert_len_eq_x!(a, b);
259        });
260        let message = concat!(
261            "assertion failed: `assert_len_eq_x!(a, b)`\n",
262            "https://docs.rs/assertables/9.6.0/assertables/macro.assert_len_eq_x.html\n",
263            " a label: `a`,\n",
264            " a debug: `\"xx\"`,\n",
265            " a.len(): `2`,\n",
266            " b label: `b`,\n",
267            " b debug: `1`"
268        );
269        assert_eq!(
270            result
271                .unwrap_err()
272                .downcast::<String>()
273                .unwrap()
274                .to_string(),
275            message
276        );
277    }
278}
279
280/// Assert a length is equal to an expression.
281///
282/// Pseudocode:<br>
283/// a.len() = b
284///
285/// This macro provides the same statements as [`assert_len_eq_x`](macro.assert_len_eq_x.html),
286/// except this macro's statements are only enabled in non-optimized
287/// builds by default. An optimized build will not execute this macro's
288/// statements unless `-C debug-assertions` is passed to the compiler.
289///
290/// This macro is useful for checks that are too expensive to be present
291/// in a release build but may be helpful during development.
292///
293/// The result of expanding this macro is always type checked.
294///
295/// An unchecked assertion allows a program in an inconsistent state to
296/// keep running, which might have unexpected consequences but does not
297/// introduce unsafety as long as this only happens in safe code. The
298/// performance cost of assertions, however, is not measurable in general.
299/// Replacing `assert*!` with `debug_assert*!` is thus only encouraged
300/// after thorough profiling, and more importantly, only in safe code!
301///
302/// This macro is intended to work in a similar way to
303/// [`::std::debug_assert`](https://doc.rust-lang.org/std/macro.debug_assert.html).
304///
305/// # Module macros
306///
307/// * [`assert_len_eq_x`](macro@crate::assert_len_eq_x)
308/// * [`assert_len_eq_x`](macro@crate::assert_len_eq_x)
309/// * [`debug_assert_len_eq_x`](macro@crate::debug_assert_len_eq_x)
310///
311#[macro_export]
312macro_rules! debug_assert_len_eq_x {
313    ($($arg:tt)*) => {
314        if $crate::cfg!(debug_assertions) {
315            $crate::assert_len_eq_x!($($arg)*);
316        }
317    };
318}
assertables/assert_len/assert_len_eq_x.rs

assertables/assert_len/
assert_len_eq_x.rs
