[#MRDOCS_ASSERT]
= MRDOCS_ASSERT
:mrdocs:

Assert that a condition holds.

== Synopsis

Declared in `<mrdocs/Support/Error/Assert.hpp>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
#define MRDOCS_ASSERT(x)

----

== Description

Use it as a statement, with a trailing semicolon, to check a precondition or invariant:

[,cpp]
----
namespace mrdocs {

int
elementAt(std::vector<int> const& v, std::size_t i)
{
    MRDOCS_ASSERT(i < v.size());
    return v[i];
}

} // mrdocs
----
In debug builds, the assertion roughly expands to&colon;

[,cpp]
----
// MRDOCS_ASSERT(i < v.size());
// The condition is evaluated once. If it's false,
// assert_failed prints "assertion failed: i < v.size()
// on line N in <file>" to stderr, and then the program
// traps (__builtin_trap on GCC/Clang, __debugbreak on
// MSVC).
static_cast<void>(!!(i < v.size()) ||
    (assert_failed("i < v.size()",
        __builtin_FILE(), __builtin_LINE()),
     static_cast<void>(__builtin_trap(),
         __builtin_unreachable()),
     true));
----
In release builds (`NDEBUG`), it expands to&colon;

[,cpp]
----
// MRDOCS_ASSERT(i < v.size());
// The condition is dropped by the preprocessor. It's
// never compiled or evaluated.
static_cast<void>(false);
----
Some consequences of this definition&colon;

* The condition must not have side effects the program depends on, such as `MRDOCS&lowbar;ASSERT(queue&period;pop())`, since release builds never run it&period; Variables used only inside assertions can trigger unused&hyphen;variable warnings there&period;
* The expansion calls `assert&lowbar;failed` unqualified, so in debug builds the macro only compiles where `mrdocs&colon;&colon;assert&lowbar;failed` is found by lookup&colon; inside `namespace mrdocs`, or after `using namespace mrdocs&semi;`&period;
* It&apos;s a `void` expression, not a full statement, so a trailing semicolon is needed&period;
* It&apos;s a single&hyphen;argument macro&period; Wrap a condition that has a top&hyphen;level comma in parentheses, as in `MRDOCS&lowbar;ASSERT((std&colon;&colon;is&lowbar;same&lowbar;v[))]`&period;

When to use it&colon;

* Preconditions of a function, such as a non&hyphen;null pointer from Clang (`MRDOCS&lowbar;ASSERT(D)`) or an index in range&period;
* Invariants of a type, such as `has&lowbar;value()` in an accessor, `!valueless&lowbar;after&lowbar;move()` on a `Polymorphic`, or `t&hyphen;&gt;Kind &equals;&equals; T&colon;&colon;kind&lowbar;id` before a cast to the derived type&period;
* Assumptions a later line depends on, such as a container being non&hyphen;empty before `front()`&period;

Use it when there&apos;s a condition you can state, so a debug build prints it when it fails&period; When there&apos;s no condition and the location itself is the bug, such as the `default&colon;` of a `switch` that handles every enumerator, use xref:MRDOCS_UNREACHABLE.adoc[`MRDOCS&lowbar;UNREACHABLE`] instead&period; Neither macro is for input a user can control, since release builds don&apos;t check it&colon; return an error with `MRDOCS&lowbar;CHECK` or `MRDOCS&lowbar;CHECK&lowbar;OR` there&period;

== Parameters

[cols="1,4"]
|===
| Name| Description
| *x*
| The condition to check&period;
|===

== See Also

xref:MRDOCS_UNREACHABLE.adoc[`MRDOCS&lowbar;UNREACHABLE`]


[.small]#Created with https://www.mrdocs.com[MrDocs]#