[#MRDOCS_TRY_BIND]
= MRDOCS_TRY_BIND
:mrdocs:

Evaluate an expected‐like expression into a structured binding.

== Synopsis

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

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

----

== Description

Works like the two‐argument form of `MRDOCS_TRY`, but unpacks the value into a structured binding. The expression is evaluated once. If it failed, the enclosing function returns `Unexpected` with its error. Otherwise the value is moved into `auto [names...]`. The enclosing function must return an xref:mrdocs/Expected.adoc[`mrdocs::Expected`]. See `MRDOCS_TRY` for what counts as failed.

Wrap the binding names in parentheses, so the commas between them aren't taken as macro‐argument separators:

[,cpp]
----
Expected<std::pair<std::string, int>>
splitKeyValue(std::string_view line);

Expected<Option>
parseOption(std::string_view line)
{
    MRDOCS_TRY_BIND((key, value), splitKeyValue(line));
    return Option{std::move(key), value};
}
----
The body of `parseOption` expands to roughly this&colon;

[,cpp]
----
// Simplified: the hidden local is really named
// expected_result_<line>, and failed/error are
// ::mrdocs::detail::failed and ::mrdocs::detail::error.

// MRDOCS_TRY_BIND((key, value), splitKeyValue(line));
auto tmp = splitKeyValue(line);
if (failed(tmp)) {
    return Unexpected(error(tmp));
}
auto [key, value] = *std::move(tmp);

return Option{std::move(key), value};
----
Any type that supports structured bindings works, with as many names as it has elements&colon;

[,cpp]
----
Expected<std::tuple<std::string, int, int>>
parseLocation(std::string_view text);

Expected<int>
lineOf(std::string_view text)
{
    MRDOCS_TRY_BIND((file, line, column), parseLocation(text));
    return line;
}
----
Things to keep in mind&colon;

* The binding is always `auto &lsqb;&period;&period;&period;&rsqb;`&colon; you can&apos;t make it `const` or a reference&period; The names bind to a fresh object moved out of the result&period;
* There&apos;s no custom&hyphen;message form&period; If you need one, use `MRDOCS&lowbar;TRY(auto v, expr, msg)` and bind `v` yourself&period;
* Like `MRDOCS&lowbar;TRY`, it expands to several statements, needs a trailing semicolon, can&apos;t appear twice on the same line, and needs braces when it&apos;s the body of an `if`, `else`, or loop&period;

== Parameters

[cols="1,4"]
|===
| Name| Description
| *names*
| The parenthesized list of binding names&period;
| *expr*
| The expected&hyphen;like expression to evaluate&period;
|===


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