diff --git a/Documentation/Patterns.md b/Documentation/Patterns.md index 6b9323e332a..488b8508d58 100644 --- a/Documentation/Patterns.md +++ b/Documentation/Patterns.md @@ -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 -#include +#include ... snip ... -void log_that_can_not_fail(StringView fmtstr, TypeErasedFormatParams& params) +ErrorOr insert_one_to_onehundred(Vector& 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 {}; } ```