bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Update panic docs to make it clearer when to use panic vs Result

Browse source
This commit is contained in:
Jane Lusby 2022-04-04 16:09:49 -07:00
parent 297a8018b5
commit ccb704c73d
1 changed files with 19 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

26
library/core/src/macros/panic.md
View file

@ -1,8 +1,7 @@
Panics the current thread.
This allows a program to terminate immediately and provide feedback
to the caller of the program. `panic!` should be used when a program reaches
an unrecoverable state.
to the caller of the program.
This macro is the perfect way to assert conditions in example code and in
tests. `panic!` is closely tied with the `unwrap` method of both
@ -21,13 +20,25 @@ Inside the hook a panic can be accessed as a `&dyn Any + Send`,
which contains either a `&str` or `String` for regular `panic!()` invocations.
To panic with a value of another other type, [`panic_any`] can be used.
[`Result`] enum is often a better solution for recovering from errors than
using the `panic!` macro. This macro should be used to avoid proceeding using
incorrect values, such as from external sources. Detailed information about
error handling is found in the [book].
See also the macro [`compile_error!`], for raising errors during compilation.
# When to use `panic!` vs `Result`
The Rust model of error handling groups errors into two major categories:
recoverable and unrecoverable errors. For a recoverable error, such as a file
not found error, it’s reasonable to report the problem to the user and retry
the operation. Unrecoverable errors are always symptoms of bugs, like trying to
access a location beyond the end of an array.
The Rust language and standard library provides `Result` and `panic!` as parts
of two complementary systems for representing, reporting, propagating, reacting
to, and discarding errors for in these two categories.
The `panic!` macro is provided to represent unrecoverable errors, whereas the
`Result` enum is provided to represent recoverable errors. For more detailed
information about error handling check out the [book] or the [`std::result`]
module docs.
[ounwrap]: Option::unwrap
[runwrap]: Result::unwrap
[`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html
@ -36,6 +47,7 @@ See also the macro [`compile_error!`], for raising errors during compilation.
[`Any`]: crate::any::Any
[`format!`]: ../std/macro.format.html
[book]: ../book/ch09-00-error-handling.html
[`std::result`]: ../std/result/index.html
# Current implementation