Documentation: Note that MUST does not replace error propagation

This commit is contained in:
Tim Schumacher 2023-01-26 17:35:02 +01:00 committed by Linus Groh
parent 6607336b38
commit 03c3d7edbc
Notes: sideshowbarker 2024-07-17 01:11:06 +09:00

View file

@ -63,19 +63,28 @@ Note: Our `TRY(...)` macro functions similarly to the `?` [operator in rust](htt
The `MUST(...)` macro is similar to `TRY(...)` except the macro enforces that
the code run inside the macro must succeed, otherwise we assert.
Note that `MUST(...)` should not be used as a replacement for `TRY(...)` in cases where error propagation is not (currently) possible.
Instead, the `release_value_but_fixme_should_propagate_errors()` method of `ErrorOr<>` should be used to retrieve the value
and to mark the location for future improvement. `MUST(...)` is reserved for cases where we determine through other circumstances that it
should not be possible for the code inside the macro to fail or if a failure is serious enough that the program _needs_ to crash.
### Example:
```cpp
#include <AK/Try.h>
#include <AK/String.h>
#include <AK/Vector.h>
... snip ...
void log_that_can_not_fail(StringView fmtstr, TypeErasedFormatParams& params)
ErrorOr<void> insert_one_to_onehundred(Vector<int>& vector)
{
StringBuilder builder;
MUST(vformat(builder, fmtstr, params));
return builder.to_deprecated_string();
TRY(vector.try_ensure_capacity(vector.size() + 100));
for (int i = 1; i <= 100; i++) {
// We previously made sure that we allocated enough space, so the append operation shouldn't ever fail.
MUST(vector.try_append(i));
}
return {};
}
```