[#MRDOCS_UNREACHABLE]
= MRDOCS_UNREACHABLE
:mrdocs:

Mark a code path that can never run.

== Synopsis

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

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

----

== Description

Use it as a statement, with a trailing semicolon, after code that handles every possible case, such as a `switch` over all enumerators. It also stops "control reaches end of non‐void function" warnings, since the compiler knows the path doesn't return:

[,cpp]
----
namespace mrdocs {

enum class Access { Public, Protected, Private };

char const*
toString(Access a)
{
    switch (a)
    {
    case Access::Public:    return "public";
    case Access::Protected: return "protected";
    case Access::Private:   return "private";
    }
    MRDOCS_UNREACHABLE();
}

} // mrdocs
----
The last line of `toString` expands to:

[,cpp]
----
// MRDOCS_UNREACHABLE();

// Debug builds: trap at once, so a bug that reaches this
// line stops the program where it happened. No message
// is printed.
static_cast<void>(__builtin_trap(), __builtin_unreachable());
// MSVC: static_cast<void>(__debugbreak(), __assume(false));

// Release builds (NDEBUG): only an optimizer hint.
static_cast<void>(__builtin_unreachable());
// MSVC: static_cast<void>(__assume(false));
----
In release builds, actually reaching the call is undefined behavior, so don&apos;t use it for paths that bad input can reach&period; Return an error or throw there instead&period; The macro takes no arguments, but the empty parentheses are required&period; Unlike `MRDOCS&lowbar;ASSERT`, it works in any namespace&period;

When to use it&colon;

* In the `default&colon;` of a `switch` over a closed kind enum, when every enumerator is already handled, as in the `AccessKind` and `AttributeKind` switches in `ASTVisitor&period;cpp`&period;
* At the end of an exhaustive dispatch, such as the `asX()` casts generated from the `&period;inc` kind lists or the final `else` of the kind&hyphen;id chain in `Visitor&period;hpp`&period;

Use it when the location itself is the bug and there&apos;s no condition to test&period; When you can state the condition that must hold, such as `t&hyphen;&gt;Kind &equals;&equals; T&colon;&colon;kind&lowbar;id` before a cast, use xref:MRDOCS_ASSERT.adoc[`MRDOCS&lowbar;ASSERT`] instead, so a debug build reports the failed expression&period; Neither macro is for input a user can control&colon; return an error with `MRDOCS&lowbar;CHECK` or `MRDOCS&lowbar;CHECK&lowbar;OR` there&period;

== See Also

xref:MRDOCS_ASSERT.adoc[`MRDOCS&lowbar;ASSERT`]


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