multi-trait 1.0.1

// SPDX-License-Identifier: Apache-2.0

#[cfg(not(feature = "std"))]
use alloc::string::String;

/// Errors generated by the numeric type impls
///
/// This error type follows Rust error handling best practices:
/// - Uses `#[non_exhaustive]` to allow adding new variants without breaking changes
/// - Provides structured error variants with context information
/// - Implements proper error source chains via `#[source]` attribute
/// - Uses `thiserror` for ergonomic error handling
///
/// # Error Source Chains
///
/// Errors that wrap other errors (like `UnsignedVarintDecode`) properly implement
/// the `Error::source()` method, allowing error chains to be inspected for debugging.
///
/// # Examples
///
/// ```
/// use multi_trait::{TryDecodeFrom, Error};
///
/// // Attempting to decode from empty slice returns an error
/// let result = u8::try_decode_from(&[]);
/// assert!(result.is_err());
///
/// // The error provides context about what went wrong
/// if let Err(e) = result {
///     eprintln!("Decode failed: {}", e);
///     // In production code with std, you can access the error source:
///     // if let Some(source) = std::error::Error::source(&e) {
///     //     eprintln!("Caused by: {}", source);
///     // }
/// }
/// ```
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// Failed to decode unsigned varint data
    ///
    /// This error occurs when the underlying unsigned-varint decoder fails.
    /// Common causes include:
    /// - Truncated varint data (incomplete bytes)
    /// - Invalid varint encoding
    /// - Buffer underflow
    ///
    /// The source error provides additional details about the specific failure.
    #[cfg(feature = "std")]
    #[error("failed to decode unsigned varint")]
    UnsignedVarintDecode {
        /// The underlying decode error from unsigned-varint crate
        #[source]
        source: unsigned_varint::decode::Error,
    },

    /// Failed to decode unsigned varint data (no_std variant)
    ///
    /// This error occurs when the underlying unsigned-varint decoder fails.
    /// Common causes include:
    /// - Truncated varint data (incomplete bytes)
    /// - Invalid varint encoding
    /// - Buffer underflow
    #[cfg(not(feature = "std"))]
    #[error("failed to decode unsigned varint: {message}")]
    UnsignedVarintDecode {
        /// Error message from the underlying decoder
        message: String,
    },

    /// Insufficient data to decode value
    ///
    /// This error occurs when the input slice doesn't contain enough bytes
    /// to decode the requested type. This typically happens with truncated data.
    ///
    /// # Examples
    ///
    /// ```
    /// use multi_trait::{TryDecodeFrom, Error};
    ///
    /// // Empty slice cannot decode any value
    /// let result = u16::try_decode_from(&[]);
    /// match result {
    ///     Err(Error::UnsignedVarintDecode { .. }) => {
    ///         // Expected behavior for empty input
    ///     }
    ///     _ => panic!("Unexpected result"),
    /// }
    /// ```
    #[error("insufficient data: expected at least {expected} bytes, found {actual}")]
    InsufficientData {
        /// Expected number of bytes needed
        expected: usize,
        /// Actual number of bytes available in the input
        actual: usize,
    },

    /// Invalid encoding encountered
    ///
    /// This error occurs when the data is structurally invalid beyond just
    /// varint decoding issues. For example, if a value is out of range for
    /// the target type or violates format-specific constraints.
    ///
    /// This variant is provided for future extensibility and custom
    /// validation logic.
    #[error("invalid encoding: {reason}")]
    InvalidEncoding {
        /// Human-readable description of why the encoding is invalid
        reason: String,
    },
}