Crate debug_unwraps
source · [−]Expand description
debug_unwraps
Adds debug only unwrap functionality to Option and Result types for Rust
Motivation
When writing a new high-level structure use of .unwrap()
and .expect()
can
be useful to ensure that internal invariants are upheld. This allows unit and
integration tests to quickly fail if a code-change violates some expected
structure.
On the other hand, in release mode it would be nice to strip such checks because it is expected that the API itself will enforce the invariant.
Consider the following example structure:
/// A silly dag structure which creates a heirachichal group of sets of numbers
struct NumTreeBuilder {
/// Stack of currently edited nodes
stack: Vec<usize>,
/// An adjacency list of children
nodes: Vec<Vec<usize>>,
/// List of numbers associated with each node
data: Vec<Vec<u32>>,
}
impl NumTreeBuilder {
/// Creates an empty `NumTreeBuilder`
///
/// Editing will start at the root
pub fn new() -> Self {
Self {
// Editing starts at the `0` node which is the root
stack: vec![0],
// Insert an empty list of children for node 0
nodes: vec![Vec::new()],
// Default name for the root
names: vec![Vec::new()],
}
}
/// Add a new number to the set of the currently edited node
pub fn add_num(&mut self, num: u32) {
if let Some(current) = self.stack.last() {
self.data.get_mut(*current)
.expect("A node ID was on the stack but didn't have associated data")
.push(num);
} else {
unreachable!("The stack should never be empty because the root cannot be popped");
}
}
/// Start a new child under the current node
pub fn start_child(&mut self) {
// Create a new child node
let child_id = self.nodes.len();
// INVARIANT: Children must have adjacency and data structures created
// before they can be edited
self.nodes.push(Vec::new());
self.data.push(Vec::new());
// Update the child list of the current node and push the new child
// onto the edit stack
if let Some(current) = self.stack.last() {
self.nodes.get_mut(*current)
.expect("A node ID was on the stack but didn't have associated data")
.push(child_id);
self.stack.push(child_id);
} else {
unreachable!("The stack should never be empty because the root cannot be popped");
}
}
/// Stop editing a child and return to its parent
pub fn finish_child(&mut self) {
if self.stack.len() > 1 {
self.stack.pop();
}
// INVARIANT: Don't pop if we are at the root
}
}
The API is designed to not allow invalid states such as an empty stack or
missing node data, but we are forced to always do run-time checks.
Currently the only way to get debug only checks is to use debug_assert!()
:
impl NumTreeBuilder {
/// Start a new child under the current node
pub fn start_child(&mut self) {
// Create a new child node
let child_id = self.nodes.len();
// INVARIANT: Children must have adjacency and data structures created
// before they can be edited
self.nodes.push(Vec::new());
self.data.push(Vec::new());
// Edit the parent adjacency list
debug_assert!(self.stack.last().is_some(), "The stack should never be empty because the root cannot be popped");
// SAFETY: this invariant should be upheld by the API because `finish_child()`
// only pops an item if the stack is greater than 1 item long
// In debug mode this will panic in the above debug_assert!
let current = unsafe {self.stack.last().unwrap_unchecked()};
debug_assert!(self.nodes.get_mut(*current).is_some(), "A node ID was on the stack but didn't have associated data");
// SAFETY: this invariatn is upheld above because all new child nodes
// have nodes and data items pushed by `start_child()`
// In debug mode this will panic in the above debug_assert!
unsafe { self.nodes.get_mut(*current).unwrap_uncheckd().push(child_id) };
// Start editing the new child
self.stack.push(child_id);
}
}
This has some disadvantages because it separates the error check from the location
that the error can be generated. Additionally if each operation is in its own
unsafe
block it increases the number of locations to audit when checking for
crate safety.
Solution
This crate provides extension traits for Option<T>
and Result<T,E>
which
conditionally enable debugging only when compiled with debug-assertions
.
impl NumTreeBuilder {
/// Start a new child under the current node
pub fn start_child(&mut self) {
// Use extension trait
use debug_unwraps::DebugUnwrapExt;
// Create a new child node
let child_id = self.nodes.len();
// INVARIANT: Children must have adjacency and data structures created
// before they can be edited
self.nodes.push(Vec::new());
self.data.push(Vec::new());
// SAFETY: The invariants that the stack is not empty and all nodes have
// an adjacency list are upheld by the rest of the API. In debug mode
// these invariants will be checked
unsafe {
let current = self.stack.last().debug_expect_unchecked("The stack should never be empty because the root cannot be popped");
self.nodes.get_mut(*current)
.debug_expect_unchecked("A node ID was on the stack but didn't have associated data")
.push(child_id);
}
// Start editing the new child
self.stack.push(child_id);
}
}
With this code, the error checking is once again inline and failures during refactorign can be caught during unit/integration tests. But in Release the code will not bother checking.
Traits
Extension trait providing debug only checking of error validity
Extension trait providing debug only checking of item validity