//! # SNAFU vs. Failure
//!
//! This comparison was made against the examples in [the guide for
//! failure 0.1.5][failure-guide].
//!
//! [failure-guide]: https://rust-lang-nursery.github.io/failure/guidance.html
//!
//! ## "Strings as errors"
//!
//! It's unclear what benefit Failure provides here. If you are using this
//! functionality, we recommend using the standard library's `Box<dyn
//! Error>`:
//!
//! ```rust
//! fn example() -> Result<(), Box<dyn std::error::Error>> {
//!     Err(format!("Something went bad: {}", 1 + 1))?;
//!     Ok(())
//! }
//! ```
//!
//! If you wanted to do something similar with SNAFU, you can create a
//! single-variant error enum with `String` data:
//!
//! ```rust
//! use snafu::Snafu;
//! use std::ops::Range;
//!
//! #[derive(Debug, Snafu)]
//! enum Error {
//!     Any { detail: String },
//! }
//!
//! fn check_range(x: usize, range: Range<usize>) -> Result<usize, Error> {
//!     if x < range.start {
//!         return Any { detail: format!("{} is below {}", x, range.start) }.fail();
//!     }
//!     if x >= range.end {
//!         return Any { detail: format!("{} is above {}", x, range.end) }.fail();
//!     }
//!     Ok(x)
//! }
//! ```
//!
//! This could be enhanced in a few ways:
//!
//! - create methods on your `Error` type
//! - create a custom macro
//! - add a [`Backtrace`][Backtrace] to the enum variant
//!
//! For example:
//!
//! ```rust
//! use snafu::{Backtrace, Snafu};
//! use std::ops::Range;
//!
//! #[derive(Debug, Snafu)]
//! enum Error {
//!     Any { detail: String, backtrace: Backtrace },
//! }
//!
//! macro_rules! format_err {
//!     ($($arg:tt)*) => { Any { detail: format!($($arg)*) }.fail() }
//! }
//!
//! fn check_range(x: usize, range: Range<usize>) -> Result<usize, Error> {
//!     if x < range.start {
//!         return format_err!("{} is below {}", x, range.start);
//!     }
//!     if x >= range.end {
//!         return format_err!("{} is above {}", x, range.end);
//!     }
//!     Ok(x)
//! }
//! ```
//!
//! Please see the next section for the recommended pattern for this error.
//!
//! [Backtrace]: crate::Backtrace
//!
//! ## "A Custom Fail type" and "Using the Error type"
//!
//! These two idioms from Failure are combined into one primary use case
//! in SNAFU. Additionally, SNAFU avoids the downsides listed in the
//! Failure guide.
//!
//! You can represent multiple types of errors, allocation is not
//! required, and you can include any extra information relevant to the
//! error:
//!
//! ```rust
//! use snafu::{ensure, Snafu};
//! use std::ops::Range;
//!
//! #[derive(Debug, Snafu)]
//! enum Error {
//!     #[snafu(display("{} is below {}", value, bound))]
//!     Below { value: usize, bound: usize },
//!
//!     #[snafu(display("{} is above {}", value, bound))]
//!     Above { value: usize, bound: usize },
//! }
//!
//! fn check_range(value: usize, range: Range<usize>) -> Result<usize, Error> {
//!     ensure!(value >= range.start, Below { value, bound: range.start });
//!     ensure!(value < range.end, Above { value, bound: range.end });
//!     Ok(value)
//! }
//! ```
//!
//! You do not have to have a one-to-one relationship between an
//! underlying error and an error variant:
//!
//! ```rust
//! use snafu::{Snafu, ResultExt};
//! use std::num::ParseIntError;
//!
//! #[derive(Debug, Snafu)]
//! enum Error {
//!     #[snafu(display(r#"Could not parse the area code from "{}": {}"#, value, source))]
//!     AreaCodeInvalid {
//!         value: String,
//!         source: ParseIntError,
//!     },
//!
//!     #[snafu(display(r#"Could not parse the phone exchange from "{}": {}"#, value, source))]
//!     PhoneExchangeInvalid {
//!         value: String,
//!         source: ParseIntError,
//!     },
//! }
//!
//! fn two_errors_from_same_underlying_error(area_code: &str, exchange: &str) -> Result<(i32, i32), Error> {
//!     let area_code: i32 = area_code
//!         .parse()
//!         .context(AreaCodeInvalid { value: area_code })?;
//!     let exchange: i32 = exchange
//!         .parse()
//!         .context(PhoneExchangeInvalid { value: exchange })?;
//!     Ok((area_code, exchange))
//! }
//! ```
//!
//! ## "An Error and ErrorKind pair"
//!
//! If you choose to make your error type [opaque][], you can implement
//! methods on the opaque type, allowing you to selectively choose what
//! your public API is.
//!
//! This includes the ability to return a different public enum that
//! users can match on without knowing the details of your error
//! implementation.
//!
//! ```rust
//! use snafu::Snafu;
//!
//! #[derive(Debug, Snafu)]
//! enum InnerError {
//!     MyError1 { username: String },
//!     MyError2 { username: String },
//!     MyError3 { address: String },
//! }
//!
//! #[derive(Debug, Snafu)]
//! pub struct Error(InnerError);
//!
//! #[derive(Debug, Copy, Clone, PartialEq, Eq)]
//! pub enum ErrorKind {
//!     Authorization,
//!     Network,
//! }
//!
//! impl Error {
//!     pub fn kind(&self) -> ErrorKind {
//!         use InnerError::*;
//!
//!         match self.0 {
//!             MyError1 { .. } | MyError2 { .. } => ErrorKind::Authorization,
//!             MyError3 { .. } => ErrorKind::Network,
//!         }
//!     }
//!
//!     pub fn username(&self) -> Option<&str> {
//!         use InnerError::*;
//!
//!         match &self.0 {
//!             MyError1 { username } | MyError2 { username } => Some(username),
//!             _ => None,
//!         }
//!     }
//! }
//!
//! # fn main() {}
//! ```
//!
//! [opaque]: crate::guide::opaque