mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Centralize panic macro documentation

Browse Source
This commit is contained in:
Chris Gregory 2019-06-03 22:25:20 -07:00 committed by Jonas Platte
parent ded5ee0013
commit 6fc18a9964
No known key found for this signature in database
GPG Key ID: 7D261D771D915378
3 changed files with 49 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/libcore/macros.rs → src/libcore/macros/mod.rs
View File

@ -1,6 +1,4 @@
/// Panics the current thread.
///
/// For details, see `std::macros`.
#[doc(include = "panic.md")]
#[macro_export]
#[allow_internal_unstable(core_panic,
// FIXME(anp, eddyb) `core_intrinsics` is used here to allow calling

47
src/libcore/macros/panic.md Normal file
View File

@ -0,0 +1,47 @@
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.
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 [`Option`]
and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set
to None or Err variants.
This macro is used to inject panic into a Rust thread, causing the thread to
panic entirely. Each thread's panic can be reaped as the `Box<Any>` type,
and the single-argument form of the `panic!` macro will be the value which
is transmitted.
[`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].
The multi-argument form of this macro panics with a string and has the
[`format!`] syntax for building a string.
See also the macro [`compile_error!`], for raising errors during compilation.
[runwrap]: ../std/result/enum.Result.html#method.unwrap
[`Option`]: ../std/option/enum.Option.html#method.unwrap
[`Result`]: ../std/result/enum.Result.html
[`format!`]: ../std/macro.format.html
[`compile_error!`]: ../std/macro.compile_error.html
[book]: ../book/ch09-00-error-handling.html
# Current implementation
If the main thread panics it will terminate all your threads and end your
program with code `101`.
# Examples
```should_panic
# #![allow(unreachable_code)]
panic!();
panic!("this is a terrible mistake!");
panic!(4); // panic with the value of 4 to be collected elsewhere
panic!("this is a {} {message}", "fancy", message = "message");
```

48
src/libstd/macros.rs
View File

@ -4,53 +4,7 @@
//! library. Each macro is available for use when linking against the standard
//! library.
/// 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.
///
/// 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 [`Option`]
/// and [`Result`][runwrap] enums. Both implementations call `panic!` when they are set
/// to None or Err variants.
///
/// This macro is used to inject panic into a Rust thread, causing the thread to
/// panic entirely. Each thread's panic can be reaped as the `Box<Any>` type,
/// and the single-argument form of the `panic!` macro will be the value which
/// is transmitted.
///
/// [`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].
///
/// The multi-argument form of this macro panics with a string and has the
/// [`format!`] syntax for building a string.
///
/// See also the macro [`compile_error!`], for raising errors during compilation.
///
/// [runwrap]: ../std/result/enum.Result.html#method.unwrap
/// [`Option`]: ../std/option/enum.Option.html#method.unwrap
/// [`Result`]: ../std/result/enum.Result.html
/// [`format!`]: ../std/macro.format.html
/// [`compile_error!`]: ../std/macro.compile_error.html
/// [book]: ../book/ch09-00-error-handling.html
///
/// # Current implementation
///
/// If the main thread panics it will terminate all your threads and end your
/// program with code `101`.
///
/// # Examples
///
/// ```should_panic
/// # #![allow(unreachable_code)]
/// panic!();
/// panic!("this is a terrible mistake!");
/// panic!(4); // panic with the value of 4 to be collected elsewhere
/// panic!("this is a {} {message}", "fancy", message = "message");
/// ```
#[doc(include = "../libcore/macros/panic.md")]
#[macro_export]
#[stable(feature = "rust1", since = "1.0.0")]
#[allow_internal_unstable(libstd_sys_internals)]