universal_radix_sort 1.0.0

//! Error types for Radix Sort operations.
//!
//! This module defines the error handling infrastructure for the Radix Sort library,
//! providing detailed error information for debugging and recovery.

use thiserror::Error;

/// Result type alias for Radix Sort operations.
///
/// # Examples
///
/// ```rust
/// use universal_radix_sort::{RadixResult, RadixError};
///
/// fn sort_operation() -> RadixResult<()> {
///     // Operation that might fail
///     Ok(())
/// }
/// ```
pub type RadixResult<T> = Result<T, RadixError>;

/// Error codes identifying specific failures during sorting operations.
///
/// This enum provides detailed categorization of errors that can occur during
/// Radix Sort operations, enabling precise error handling and debugging.
///
/// # Variants
///
/// - `NullInput`: The input collection was empty or null
/// - `TypeMismatch`: The generic type does not match the configured RadixDataType
/// - `InvalidValue`: Contains invalid values (e.g., NaN in certain contexts)
/// - `MemoryAllocation`: Failed to allocate required memory
/// - `Overflow`: Integer overflow during transformation
///
/// # Examples
///
/// ```rust
/// use universal_radix_sort::RadixError;
///
/// let result: Result<(), RadixError> = Ok(());
/// match result {
///     Ok(_) => println!("Success"),
///     Err(RadixError::TypeMismatch { expected, got }) => {
///         println!("Type mismatch: expected {}, got {}", expected, got);
///     }
///     Err(e) => println!("Error: {}", e),
/// }
/// ```
#[derive(Error, Debug, Clone, PartialEq, Eq)]
pub enum RadixError {
    /// The input collection was empty or null.
    #[error("Input collection cannot be empty")]
    EmptyInput,

    /// The generic type does not match the configured RadixDataType.
    #[error("Type mismatch: expected {expected}, but got {got}")]
    TypeMismatch {
        /// The expected type name.
        expected: String,
        /// The actual type name received.
        got: String,
    },

    /// Contains invalid values that cannot be sorted.
    #[error("Invalid value encountered: {message}")]
    InvalidValue {
        /// Description of the invalid value.
        message: String,
    },

    /// Failed to allocate required memory for sorting buffers.
    #[error("Memory allocation failed: {message}")]
    MemoryAllocation {
        /// Details about the allocation failure.
        message: String,
    },

    /// Integer overflow during bit transformation.
    #[error("Integer overflow during transformation")]
    Overflow,

    /// Unsupported operation for the given data type.
    #[error("Unsupported operation: {message}")]
    UnsupportedOperation {
        /// Description of the unsupported operation.
        message: String,
    },
}

impl RadixError {
    /// Creates a new TypeMismatch error.
    ///
    /// # Arguments
    ///
    /// * `expected` - The expected type name
    /// * `got` - The actual type name received
    ///
    /// # Examples
    ///
    /// ```rust
    /// use universal_radix_sort::RadixError;
    ///
    /// let err = RadixError::type_mismatch("i64", "f64");
    /// assert!(matches!(err, RadixError::TypeMismatch { .. }));
    /// ```
    pub fn type_mismatch(expected: impl Into<String>, got: impl Into<String>) -> Self {
        RadixError::TypeMismatch {
            expected: expected.into(),
            got: got.into(),
        }
    }

    /// Creates a new InvalidValue error.
    ///
    /// # Arguments
    ///
    /// * `message` - Description of the invalid value
    ///
    /// # Examples
    ///
    /// ```rust
    /// use universal_radix_sort::RadixError;
    ///
    /// let err = RadixError::invalid_value("NaN not allowed in this context");
    /// ```
    pub fn invalid_value(message: impl Into<String>) -> Self {
        RadixError::InvalidValue {
            message: message.into(),
        }
    }

    /// Creates a new MemoryAllocation error.
    ///
    /// # Arguments
    ///
    /// * `message` - Details about the allocation failure
    pub fn memory_allocation(message: impl Into<String>) -> Self {
        RadixError::MemoryAllocation {
            message: message.into(),
        }
    }

    /// Creates a new UnsupportedOperation error.
    ///
    /// # Arguments
    ///
    /// * `message` - Description of the unsupported operation
    pub fn unsupported_operation(message: impl Into<String>) -> Self {
        RadixError::UnsupportedOperation {
            message: message.into(),
        }
    }

    /// Returns a human-readable error code for logging purposes.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use universal_radix_sort::RadixError;
    ///
    /// let err = RadixError::EmptyInput;
    /// assert_eq!(err.code(), "EMPTY_INPUT");
    /// ```
    pub fn code(&self) -> &'static str {
        match self {
            RadixError::EmptyInput => "EMPTY_INPUT",
            RadixError::TypeMismatch { .. } => "TYPE_MISMATCH",
            RadixError::InvalidValue { .. } => "INVALID_VALUE",
            RadixError::MemoryAllocation { .. } => "MEMORY_ALLOCATION",
            RadixError::Overflow => "OVERFLOW",
            RadixError::UnsupportedOperation { .. } => "UNSUPPORTED_OPERATION",
        }
    }
}