Expand description
For panicking with formatting in const contexts.
This library exists because the panic macro was stabilized for use in const contexts in Rust 1.57.0, without formatting support.
All of the types that implement the PanicFmt
trait can be formatted in panics.
§Examples
§Basic
use const_panic::concat_assert;
const FOO: u32 = 10;
const BAR: u32 = 0;
const _: () = assert_non_zero(FOO, BAR);
#[track_caller]
const fn assert_non_zero(foo: u32, bar: u32) {
concat_assert!{
foo != 0 && bar != 0,
"\nneither foo nor bar can be zero!\nfoo: ", foo, "\nbar: ", bar
}
}
The above code fails to compile with this error:
error[E0080]: evaluation of constant value failed
--> src/lib.rs:20:15
|
8 | const _: () = assert_non_zero(FOO, BAR);
| ^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at '
neither foo nor bar can be zero!
foo: 10
bar: 0', src/lib.rs:8:15
When called at runtime
use const_panic::concat_assert;
assert_non_zero(10, 0);
#[track_caller]
const fn assert_non_zero(foo: u32, bar: u32) {
concat_assert!{
foo != 0 && bar != 0,
"\nneither foo nor bar can be zero!\nfoo: ", foo, "\nbar: ", bar
}
}
it prints this:
thread 'main' panicked at '
neither foo nor bar can be zero!
foo: 10
bar: 0', src/lib.rs:6:1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
§Custom types
Panic formatting for custom types can be done in these ways (in increasing order of verbosity):
- Using the
PanicFmt
derive macro (requires the opt-in"derive"
feature) - Using the
impl_panicfmt
macro (requires the default-enabled"non_basic"
feature) - Using the
flatten_panicvals
macro (requires the default-enabled"non_basic"
feature) - Manually implementing the
PanicFmt
trait as described in its docs.
This example uses the PanicFmt
derive approach.
use const_panic::{PanicFmt, concat_panic};
const LAST: u8 = {
Foo{
x: &[],
y: Bar(false, true),
z: Qux::Left(23),
}.pop().1
};
impl Foo<'_> {
/// Pops the last element
///
/// # Panics
///
/// Panics if `self.x` is empty
#[track_caller]
const fn pop(mut self) -> (Self, u8) {
if let [rem @ .., last] = self.x {
self.x = rem;
(self, *last)
} else {
concat_panic!(
"\nexpected a non-empty Foo, found: \n",
// uses alternative Debug formatting for `self`,
// otherwise this would use regular Debug formatting.
alt_debug: self
)
}
}
}
#[derive(PanicFmt)]
struct Foo<'a> {
x: &'a [u8],
y: Bar,
z: Qux,
}
#[derive(PanicFmt)]
struct Bar(bool, bool);
#[derive(PanicFmt)]
enum Qux {
Up,
Down { x: u32, y: u32 },
Left(u64),
}
The above code fails to compile with this error:
error[E0080]: evaluation of constant value failed
--> src/lib.rs:57:5
|
7 | / Foo{
8 | | x: &[],
9 | | y: Bar(false, true),
10 | | z: Qux::Left(23),
11 | | }.pop().1
| |___________^ the evaluated program panicked at '
expected a non-empty Foo, found:
Foo {
x: [],
y: Bar(
false,
true,
),
z: Left(
23,
),
}', src/lib.rs:11:7
§Limitations
Arguments to the formatting/panicking macros must have a fully inferred concrete type,
because const_panic
macros use duck typing to call methods on those arguments.
One effect of that limitation is that you will have to pass suffixed
integer literals (eg: 100u8
) when those integers aren’t inferred to be a concrete type.
§Panic message length
The panic message can only be up to MAX_PANIC_MSG_LEN
long,
after which it is truncated.
§Cargo features
-
"non_basic"
(enabled by default): Enables support for formatting structs, enums, and arrays.
Without this feature, you can effectively only format primitive types (custom types can manually implement formatting with more difficulty). -
"rust_1_64"
(disabled by default): Enables formatting of additional items that require Rust 1.64.0 to do so. -
"derive"
(disabled by default): Enables thePanicFmt
derive macro.
§Plans
None for now
§No-std support
const_panic
is #![no_std]
, it can be used anywhere Rust can be used.
§Minimum Supported Rust Version
This requires Rust 1.57.0, because it uses the panic
macro in a const context.
Re-exports§
pub use crate::fmt::FmtArg;
pub use crate::fmt::IsCustomType;
pub use crate::fmt::PanicFmt;
pub use crate::fmt::ComputePvCount;
pub use crate::fmt::TypeDelim;
Modules§
- Formatting-related items
- Utility functions
Macros§
- Coerces
$reff
to a type that has ato_panicvals
method, which is expected to return a[PanicVal<'_>; LEN]
. - concat_
non_basic
ConcatenatesPanicFmt
constants into a&'static str
- Asserts that
$condition
is true. - Panics with the concanenation of the arguments.
- flatten_
panicvals non_basic
Formats multiple values into an array ofPanicVal
s. - impl_
panicfmt non_basic
Implements thePanicFmt
trait and theto_panicvals
method it requires. - inline_
macro non_basic
Helper macro for defining and using amacro_rules!
macro inline. - Gets the value in the
Err
variant. - Gets the value in the
Ok
variant. - Gets the value in the
Some
variant.
Structs§
- For precomputing a panic message.
- An opaque enum of the values that this crate knows how to format, along with some formatting metadata.
- A wrapper type used to define methods for std types.
Constants§
- The maximum length of panic messages (in bytes), after which the message is truncated.
Functions§
- Panics by concatenating the argument slice.