From 7aacbdf4eca711b6d458894f00b7d3baaf64b8ba Mon Sep 17 00:00:00 2001 From: "Lu, Wangshan" Date: Fri, 3 Oct 2025 17:52:50 +0800 Subject: [PATCH] Update docs --- README.md | 23 +++++++++++------ src/lib.rs | 73 ++++++++++++++++++++++++++---------------------------- 2 files changed, 50 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 79bd40b..775bd68 100644 --- a/README.md +++ b/README.md @@ -19,17 +19,13 @@ To use `simple-error`, first add this to your `Cargo.toml`: simple-error = "0.3" ``` -Then add this to your crate root: +Then import what you use (Rust 2018/2021): ```rust -#[macro_use] -extern crate simple_error; - -use simple_error::SimpleError; +use simple_error::{SimpleError, try_with}; +// Add others as needed: require_with, ensure_with, bail, simple_error, map_err_with ``` -Or you can skip the `extern crate` and just import relevant items you use if you are on 2018 edition or beyond. - Now you can use `simple-error` in different ways: You can use it simply as a string error type: @@ -44,7 +40,7 @@ You can use it to replace all error types if you only care about a string descri ```rust fn do_bar() -> Result<(), SimpleError> { - Err(SimpleError::from(std::io::Error(io::ErrorKind::Other, "oh no"))) + Err(SimpleError::from(std::io::Error::new(std::io::ErrorKind::Other, "oh no"))) } ``` @@ -87,8 +83,19 @@ fn main() { You can also ensure a condition holds and early-return a `SimpleError` if it does not: ```rust +use simple_error::{SimpleError, ensure_with}; + fn check_config(is_valid: bool) -> Result<(), SimpleError> { ensure_with!(is_valid, "invalid config"); Ok(()) } ``` + +## Macros + +- `try_with!` — unwrap `Result`, else return `SimpleError::with`. +- `require_with!` — unwrap `Option`, else return `SimpleError::new`. +- `ensure_with!` — assert boolean, else return `SimpleError::new`. +- `bail!` — return early with a `SimpleError` (supports format/expr). +- `simple_error!` — construct a `SimpleError` (supports format/expr). +- `map_err_with!` — map a `Result`’s error with extra context. diff --git a/src/lib.rs b/src/lib.rs index df79544..c0e4845 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,11 +1,11 @@ #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png", html_favicon_url = "https://www.rust-lang.org/favicon.ico", - html_root_url = "https://wisagan.github.io/simple-error/simple_error/")] + html_root_url = "https://docs.rs/simple-error")] #![deny(missing_docs)] //! A simple error type backed by a string. //! -//! This crate provides a `SimpleError` type, which implements `std::error::Error`. The underlying -//! is a `String` as the error message. +//! This crate provides a `SimpleError` type, which implements `std::error::Error`. +//! The underlying type is a `String` used as the error message. //! //! It should be used when all you care about is an error string. //! @@ -29,7 +29,7 @@ impl SimpleError { /// # Examples /// /// ``` - /// use self::simple_error::SimpleError; + /// use simple_error::SimpleError; /// /// // errors can be created from `str` /// let err = SimpleError::new("an error from str"); @@ -50,7 +50,7 @@ impl SimpleError { /// # Examples /// /// ``` - /// use self::simple_error::SimpleError; + /// use simple_error::SimpleError; /// use std::io; /// /// // errors can be created from `io::Error` @@ -72,7 +72,7 @@ impl SimpleError { /// # Examples /// /// ``` - /// use self::simple_error::SimpleError; + /// use simple_error::SimpleError; /// /// let err = SimpleError::with("cannot turn on tv", SimpleError::new("remote not found")); /// assert_eq!("cannot turn on tv, remote not found", format!("{}", err)); @@ -87,7 +87,7 @@ impl SimpleError { /// # Examples /// /// ``` - /// use self::simple_error::SimpleError; + /// use simple_error::SimpleError; /// /// let s = SimpleError::new("critical error"); /// assert_eq!("critical error", s.as_str()); @@ -123,16 +123,16 @@ pub type SimpleResult = Result; /// Helper macro for unwrapping `Result` values while returning early with a /// newly constructed `SimpleError` if the value of the expression is `Err`. -/// Can only be used in functions that return `Result<_, SimpleError>`. +/// Can be used in functions that return `Result<_, E>` where `E: From` +/// (e.g. `SimpleError` or `Box`). /// /// /// # Examples /// -/// ``` -/// # #[macro_use] extern crate simple_error; -/// # fn main() { -/// use self::simple_error::SimpleError; -/// use std::error::Error; + /// ``` + /// # fn main() { + /// use simple_error::{SimpleError, try_with}; + /// use std::error::Error; /// /// fn try_block(result: Result<(), SimpleError>, s: &str) -> Result<(), SimpleError> { /// Ok(try_with!(result, s)) @@ -186,16 +186,16 @@ macro_rules! try_with { /// Helper macro for unwrapping `Option` values while returning early with a /// newly constructed `SimpleError` if the value of the expression is `None`. -/// Can only be used in functions that return `Result<_, SimpleError>`. +/// Can be used in functions that return `Result<_, E>` where `E: From` +/// (e.g. `SimpleError` or `Box`). /// /// /// # Examples /// -/// ``` -/// # #[macro_use] extern crate simple_error; -/// # fn main() { -/// use self::simple_error::SimpleError; -/// use std::error::Error; + /// ``` + /// # fn main() { + /// use simple_error::{SimpleError, require_with}; + /// use std::error::Error; /// /// fn require_block(maybe: Option<()>, s: &str) -> Result<(), SimpleError> { /// Ok(require_with!(maybe, s)) @@ -249,15 +249,15 @@ macro_rules! require_with { /// Helper macro for ensuring a boolean condition while returning early with a /// newly constructed `SimpleError` if the condition is `false`. -/// Can only be used in functions that return `Result<_, SimpleError>`. +/// Can be used in functions that return `Result<_, E>` where `E: From` +/// (e.g. `SimpleError` or `Box`). /// /// # Examples /// -/// ``` -/// # #[macro_use] extern crate simple_error; -/// # fn main() { -/// use self::simple_error::SimpleError; -/// use std::error::Error; + /// ``` + /// # fn main() { + /// use simple_error::{SimpleError, ensure_with}; + /// use std::error::Error; /// /// fn ensure_block(cond: bool, s: &str) -> Result<(), SimpleError> { /// ensure_with!(cond, s); @@ -310,11 +310,10 @@ macro_rules! ensure_with { /// /// # Examples /// -/// ``` -/// # #[macro_use] extern crate simple_error; -/// # fn main() { -/// use self::simple_error::SimpleError; -/// use std::error::Error; + /// ``` + /// # fn main() { + /// use simple_error::{SimpleError, bail}; + /// use std::error::Error; /// // Use with a `Into` /// /// struct ErrorSeed; @@ -364,10 +363,9 @@ macro_rules! bail { /// /// # Example /// -/// ``` -/// # #[macro_use] extern crate simple_error; -/// # fn main() { -/// use self::simple_error::SimpleResult; + /// ``` + /// # fn main() { + /// use simple_error::{SimpleResult, simple_error}; /// /// fn add_reason(r: Result<(), ()>) -> SimpleResult<()> { /// // Use with a string slice @@ -399,10 +397,9 @@ macro_rules! simple_error { /// /// # Example /// -/// ``` -/// # #[macro_use] extern crate simple_error; -/// # fn main() { -/// use self::simple_error::SimpleResult; + /// ``` + /// # fn main() { + /// use simple_error::{SimpleResult, map_err_with}; /// /// fn map_err_with_reason(r: Result<(), std::io::Error>) -> SimpleResult<()> { /// // Use with a string slice