Add debug_assert and debug_assert_eq macros

I also switched some `assert!` calls over to `debug_assert!`.

Closes #12049.

RFC: 0015-assert

1 files changed, 52 insertions, 0 deletions

diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index dbaef335804..58bf10d8c6a 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -130,6 +130,58 @@ macro_rules! assert_eq(
     })
 )
 
+/// Ensure that a boolean expression is `true` at runtime.
+///
+/// This will invoke the `fail!` macro if the provided expression cannot be
+/// evaluated to `true` at runtime.
+///
+/// Unlike `assert!`, `debug_assert!` statements can be disabled by passing
+/// `--cfg ndebug` to the compiler. This makes `debug_assert!` useful for
+/// checks that are too expensive to be present in a release build but may be
+/// helpful during development.
+///
+/// # Example
+///
+/// ```
+/// // the failure message for these assertions is the stringified value of the
+/// // expression given.
+/// debug_assert!(true);
+/// # fn some_expensive_computation() -> bool { true }
+/// debug_assert!(some_expensive_computation());
+///
+/// // assert with a custom message
+/// # let x = true;
+/// debug_assert!(x, "x wasn't true!");
+/// # let a = 3; let b = 27;
+/// debug_assert!(a + b == 30, "a = {}, b = {}", a, b);
+/// ```
+#[macro_export]
+macro_rules! debug_assert(
+    ($($arg:tt)*) => (if cfg!(not(ndebug)) { assert!($($arg)*); })
+)
+
+/// Asserts that two expressions are equal to each other, testing equality in
+/// both directions.
+///
+/// On failure, this macro will print the values of the expressions.
+///
+/// Unlike `assert_eq!`, `debug_assert_eq!` statements can be disabled by
+/// passing `--cfg ndebug` to the compiler. This makes `debug_assert_eq!`
+/// useful for checks that are too expensive to be present in a release build
+/// but may be helpful during development.
+///
+/// # Example
+///
+/// ```
+/// let a = 3;
+/// let b = 1 + 2;
+/// debug_assert_eq!(a, b);
+/// ```
+#[macro_export]
+macro_rules! debug_assert_eq(
+    ($($arg:tt)*) => (if cfg!(not(ndebug)) { assert_eq!($($arg)*); })
+)
+
 /// A utility macro for indicating unreachable code. It will fail if
 /// executed. This is occasionally useful to put after loops that never
 /// terminate normally, but instead directly return from a function.