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. Panics the current thread.
This allows a program to terminate immediately and provide feedback This allows a program to terminate immediately and provide feedback
to the caller of the program. `panic!` should be used when a program reaches to the caller of the program.
an unrecoverable state.
This macro is the perfect way to assert conditions in example code and in 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 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. 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. 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. 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 [ounwrap]: Option::unwrap
[runwrap]: Result::unwrap [runwrap]: Result::unwrap
[`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html [`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 [`Any`]: crate::any::Any
[`format!`]: ../std/macro.format.html [`format!`]: ../std/macro.format.html
[book]: ../book/ch09-00-error-handling.html [book]: ../book/ch09-00-error-handling.html
[`std::result`]: ../std/result/index.html
# Current implementation # Current implementation