unwrap_unreachable 0.1.1

Provides `Option::unreachable()` and `Result::unreachable()` methods
Documentation
  • Coverage
  • 100%
    4 out of 4 items documented0 out of 2 items with examples
  • Size
  • Source code size: 13.73 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 640.23 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 13s Average build duration of successful builds.
  • all releases: 13s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • dupgit/unwrap_unreachable
    0 0 0
  • crates.io
  • Dependencies
    • —
  • Versions
  • Owners
  • dupgit

Unwrap Unreachable

Provides Option::unreachable() and Result::unreachable() methods by providing an UnwrapUnreachable extension trait. Completely copied from unwrap_todo crate. This crate exists because I think it may value to test Zk proposal in real crates. It may be useful to you or not ?

Usage

Add the crate to your dependencies:

[dependencies]
unwrap_unreachable = "0.1.1"

Then use .unreachable() in lieu of .unwrap() to indicate that error handling is not needed by design.

// Make sure you import the trait. Otherwise, these functions will not be available.
use unwrap_unreachable::UnwrapUnreachable;

// This regex is known to compile at compile time… so it will not panic
// at execution
static H5AI_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"powered by h5ai (v\d+.\d+.\d+)").unreachable());

// unreachable() here is ok since we know this should not return anything
// else than Ok(httpdir) if it does it should panic as the test fail.
let httpdir = prepare_httpdir().filter_by_name("debian").unreachable();

Why?

Because of this article and that this crate did not exist already whereas the unwrap_todo did and that I have some pieces of code where .unwrap() is used for its .unreachable() meaning (type 2 in the article).

A good example of this would be static Regex construction:

static REGEX: LazyCell<Regex> = LazyCell::new(|| Regex::new("^[a-f]{3}$").unwrap());

which cannot be elegantly done without an unwrap. This unwrap is 100% intentional, and is not a placeholder (TODO) for proper error handling.

As such, this crate provides Option::unreachable() and Result::unreachable() methods that perform identically to unwrap(), but give a different error message ("internal error: entered unreachable code") and are visually distinct function calls in your codebase.

This makes it quite easy to see intentional unwrap() use, and then know where you need to focus on your code (left .unwrap() or .todo()) to clean up before publishing.

This is - in a sense - very similar to the difference between the panic!() and unreachable!() macros.

I'm having issues.

Make sure you use unwrap_unreachable::UnwrapUnreachable trait.