Skip to content

Update docs #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
WiSaGaN merged 1 commit into from
Oct 3, 2025
Merged

Update docs #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 15 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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")))
}
```

Expand Down Expand Up @@ -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.
73 changes: 35 additions & 38 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
//!
Expand All @@ -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");
Expand All @@ -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`
Expand All @@ -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));
Expand All @@ -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());
Expand Down Expand Up @@ -123,16 +123,16 @@ pub type SimpleResult<T> = Result<T, SimpleError>;

/// 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<SimpleError>`
/// (e.g. `SimpleError` or `Box<dyn Error>`).
///
///
/// # 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))
Expand Down Expand Up @@ -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<SimpleError>`
/// (e.g. `SimpleError` or `Box<dyn Error>`).
///
///
/// # 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))
Expand Down Expand Up @@ -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<SimpleError>`
/// (e.g. `SimpleError` or `Box<dyn Error>`).
///
/// # 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);
Expand Down Expand Up @@ -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<SimpleError>`
///
/// struct ErrorSeed;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading