[#MRDOCS_DESCRIBE_ENUM_UNDEFINED]
= MRDOCS_DESCRIBE_ENUM_UNDEFINED
:mrdocs:

Mark one enumerator as the enum's undefined (empty) state.

== Synopsis

Declared in `<mrdocs/Support/Reflection/Describe.hpp>`

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

----

== Description

Some enums have a value that means "not set", like `None`. Marking it makes the string helpers treat it as empty, and makes generators treat a field holding it as absent (an empty optional) instead of printing it. Place it at namespace scope, in the namespace of the enum, after the enum's `MRDOCS_DESCRIBE_ENUM`:

[,cpp]
----
namespace shapes {

enum class Fill { None, Solid, Hatched };

MRDOCS_DESCRIBE_ENUM(Fill, None, Solid, Hatched)
MRDOCS_DESCRIBE_ENUM_UNDEFINED(Fill, None)

} // namespace shapes
----
It expands to a small function that ADL finds from the enum type:

[,cpp]
----
// MRDOCS_DESCRIBE_ENUM_UNDEFINED(Fill, None)
[[maybe_unused]]
inline constexpr Fill
mrdocs_undefined_descriptor_fn(Fill**) noexcept { return Fill::None; }
----
Afterwards:

[,cpp]
----
namespace describe = mrdocs::describe;
using shapes::Fill;

static_assert(describe::has_undefined_enumerator<Fill>);
static_assert(describe::undefined_enumerator<Fill> == Fill::None);

// The undefined state renders as the empty string
static_assert(mrdocs::toString(Fill::None).empty());
static_assert(describe::enum_to_string(Fill::None).empty());
static_assert(mrdocs::toString(Fill::Solid) == "solid");

void
demo()
{
    // and the empty string parses back to it
    Fill f = Fill::Solid;
    describe::enum_from_string("", f); // returns true, f == Fill::None
}
----
Things to keep in mind&colon;

* Use it at most once per enum&semi; a second use is a redefinition error&period;
* Like `MRDOCS&lowbar;DESCRIBE&lowbar;ENUM`, it must be in the namespace of the enum and not inside a class, or lookup won&apos;t find it&period;
* The function is `inline`, so it&apos;s safe in headers&period;
* It ends with a closing brace, so don&apos;t add a semicolon&period;

== Parameters

[cols="1,4"]
|===
| Name| Description
| *E*
| The enum type&period;
| *U*
| The enumerator that represents the undefined state, written without the `E&colon;&colon;` prefix&period;
|===


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