try_create/

lib.rs

#![deny(rustdoc::broken_intra_doc_links)]


// Re-export IntoInner for convenience, as it's a supertrait of TryNew.
pub use into_inner::IntoInner;

/// A trait for creating new instances of a type with fallible validation.
///
/// This trait provides a standardized way to create new instances of a type from an
/// "inner" value, where the construction process might fail (e.g., due to validation rules).
/// Implementors must also implement [`IntoInner`], which defines the `InnerType` used
/// for construction.
///
/// # Associated Types
///
/// - `InnerType`: (From the [`IntoInner`] supertrait) The type of the input value used to
///   attempt creation of a new instance of `Self`.
/// - `Error`: The error type that is returned if `try_new` fails. This error type
///   must implement `std::error::Error` if the `std` feature is enabled.
///   If the `std` feature is not enabled, it must implement `core::fmt::Debug`.
///
/// # Examples
///
/// ```rust
/// use try_create::{TryNew, IntoInner};
/// # #[cfg(feature = "std")]
/// # use std::error::Error;
/// # #[cfg(feature = "std")]
/// # use core::fmt;
///
/// // Define a custom error type
/// #[derive(Debug, PartialEq)]
/// struct NotPositiveError;
///
/// // Implement Display and Error for the custom error (required if using std::error::Error)
/// # #[cfg(feature = "std")]
/// impl fmt::Display for NotPositiveError {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "Value must be positive")
///     }
/// }
/// # #[cfg(feature = "std")]
/// impl Error for NotPositiveError {}
/// # #[cfg(not(feature = "std"))]
/// # trait Error: core::fmt::Debug {} // Minimal Error trait for no_std
/// # #[cfg(not(feature = "std"))]
/// # impl Error for NotPositiveError {}
///
///
/// // A struct that wraps an i32, ensuring it's positive.
/// #[derive(Debug, PartialEq)]
/// struct PositiveInteger {
///     value: i32,
/// }
///
/// // Implement IntoInner to define what `InnerType` is.
/// impl IntoInner for PositiveInteger {
///     type InnerType = i32;
///
///     fn into_inner(self) -> Self::InnerType {
///         self.value
///     }
/// }
///
/// // Implement TryNew for PositiveInteger.
/// impl TryNew for PositiveInteger {
///     type Error = NotPositiveError;
///     // `InnerType` is `i32`, inherited from `IntoInner`.
///
///     fn try_new(value: Self::InnerType) -> Result<Self, Self::Error> {
///         if value > 0 {
///             Ok(PositiveInteger { value })
///         } else {
///             Err(NotPositiveError)
///         }
///     }
/// }
///
/// // Usage
/// assert_eq!(PositiveInteger::try_new(10), Ok(PositiveInteger { value: 10 }));
/// assert_eq!(PositiveInteger::try_new(0), Err(NotPositiveError));
/// assert_eq!(PositiveInteger::try_new(-5), Err(NotPositiveError));
///
/// let positive_num = PositiveInteger::try_new(42).unwrap();
/// assert_eq!(positive_num.into_inner(), 42);
/// ```
pub trait TryNew: Sized + IntoInner {
    /// The error type that can be returned by the `try_new` method.
    #[cfg(feature = "std")]
    type Error: std::error::Error;
#[cfg(not(feature = "std"))]
    type Error: core::fmt::Debug; // Added for no_std consistency


    /// Attempts to create a new instance of `Self` from `value`.
    ///
    /// # Parameters
    ///
    /// - `value`: The `InnerType` value from which to create the instance.
    ///
    /// # Returns
    ///
    /// - `Ok(Self)` if the instance is created successfully.
    /// - `Err(Self::Error)` if creation fails (e.g., due to invalid input).
    fn try_new(value: Self::InnerType) -> Result<Self, Self::Error>;
}


/// A trait for creating new instances of a type infallibly.
///
/// This trait provides a method for creating new instances of a type from `Self::InnerType`
/// (defined by the `IntoInner` supertrait).
///
/// Implementors should ensure that the [`New`] method cannot fail in a way that would
/// typically return a `Result`. If invalid input could lead to an unrecoverable state
/// or violate invariants, [`New`] should panic. For fallible construction that returns
/// a `Result`, use the [[`TryNew`]] trait.
///
/// # Examples
///
/// ```rust
/// use try_create::{New, IntoInner, TryNew}; // Assuming TryNew is used for context or comparison
/// # #[cfg(feature = "std")]
/// # use std::error::Error;
/// # #[cfg(feature = "std")]
/// # use std::fmt;
///
/// // Example struct
/// #[derive(Debug, PartialEq)]
/// struct MyType(i32);
///
/// // Define a custom error for MyType for the TryNew example
/// #[derive(Debug, PartialEq)]
/// struct MyTypeError(String);
///
/// // Implement Display and Error for MyTypeError
/// # #[cfg(feature = "std")]
/// impl fmt::Display for MyTypeError {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "MyTypeError: {}", self.0)
///     }
/// }
///
/// # #[cfg(feature = "std")]
/// impl Error for MyTypeError {}
/// // For no_std, MyTypeError already derives Debug, which is sufficient.
///
/// impl IntoInner for MyType {
///     type InnerType = i32;
///     fn into_inner(self) -> Self::InnerType { self.0 }
/// }
///
/// // Example TryNew (optional here, but good for context)
/// impl TryNew for MyType {
///     type Error = MyTypeError; // Use the custom error type
///     fn try_new(value: i32) -> Result<Self, Self::Error> {
///         if value < 0 { Err(MyTypeError("Value cannot be negative".to_string())) }
///         else { Ok(MyType(value)) }
///     }
/// }
///
/// impl New for MyType {
///     fn new(value: i32) -> Self {
///         if value < 0 {
///             panic!("MyType::new: Value cannot be negative");
///         }
///         MyType(value)
///     }
/// }
///
/// assert_eq!(MyType::new(10), MyType(10));
/// // The following would panic:
/// // MyType::new(-5);
/// ```
pub trait New: Sized + IntoInner {
/// Creates a new instance of `Self` from `value`.
    ///
    /// This method is expected to be infallible in terms of returning a `Result`.
    /// If the provided `value` cannot produce a valid instance of `Self`
    /// according to the type's invariants, this method should panic.
    ///
    /// # Parameters
    ///
    /// - `value`: The `Self::InnerType` value from which to create the instance.
    fn new(value: Self::InnerType) -> Self;
}


// It's necessary to import Debug for the bound on TryNew's error type.
// This is implicitly handled if `std::error::Error` is used (as it requires Debug)
// or if `core::fmt::Debug` is directly used for no_std.
// For clarity, if you were in a module that didn't automatically have `std::fmt::Debug`
// or `core::fmt::Debug` in scope, you might need:
// use core::fmt::Debug; // or std::fmt::Debug if std is assumed

/// A trait for conditionally creating objects.
///
/// In debug mode, it uses `Self::try_new().expect()` to create an instance,
/// panicking if `try_new` returns an error.
/// In release mode, it uses `Self::new()` to create an instance.
///
/// This trait requires the type to also implement [`TryNew`] and [`New`].
/// The error associated with [`TryNew`] (`<Self as TryNew>::Error`) must implement [`Debug`].
/// 
/// # Example
/// ```rust
/// use try_create::{ConditionallyCreate, TryNew, New, IntoInner};
/// # // Copied from TryNew example for self-containment, adjust if shared
/// # #[cfg(feature = "std")]
/// # use std::error::Error;
/// # #[cfg(feature = "std")]
/// # use std::fmt;
///
/// #[derive(Debug, PartialEq)]
/// struct NotPositiveError;
///
/// # #[cfg(feature = "std")]
/// impl fmt::Display for NotPositiveError {
///     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
///         write!(f, "Value must be positive")
///     }
/// }
/// # #[cfg(feature = "std")]
/// impl Error for NotPositiveError {}
/// # #[cfg(not(feature = "std"))]
/// # trait Error: core::fmt::Debug {} // Minimal Error trait for no_std
/// # #[cfg(not(feature = "std"))]
/// # impl Error for NotPositiveError {}
///
///
/// #[derive(Debug, PartialEq)]
/// struct PositiveInteger { value: i32 }
///
/// impl IntoInner for PositiveInteger {
///     type InnerType = i32;
///     fn into_inner(self) -> Self::InnerType { self.value }
/// }
///
/// impl TryNew for PositiveInteger {
///     type Error = NotPositiveError;
///     fn try_new(value: Self::InnerType) -> Result<Self, Self::Error> {
///         if value > 0 { Ok(PositiveInteger { value }) }
///         else { Err(NotPositiveError) }
///     }
/// }
///
/// // To use ConditionallyCreate, PositiveInteger must also implement New.
/// impl New for PositiveInteger {
///     fn new(value: Self::InnerType) -> Self {
///         match Self::try_new(value) {
///             Ok(instance) => instance,
///             Err(e) => panic!("PositiveInteger::new failed for a non-positive value. Error: {:?}", e),
///         }
///     }
/// }
///
/// // Now you can call:
/// # fn example_usage() { // Encapsulate in a function for the doctest
/// let val_ok = 10;
/// let _p1 = PositiveInteger::create_conditionally(val_ok);
/// assert_eq!(_p1, PositiveInteger { value: 10 });
///
/// // In debug, this would panic (difficult to test directly in doctest without specific harness):
/// // let val_err = -5;
/// // let _p2 = PositiveInteger::create_conditionally(val_err);
/// # }
/// # example_usage();
/// ``` 
pub trait ConditionallyCreate: Sized + TryNew + New
where
    <Self as TryNew>::Error: core::fmt::Debug, // Necessary for .expect() in debug
{
    /// Conditionally creates an instance of `Self`.
    ///
    /// # Parameters
    ///
    /// - `value`: The `Self::InnerType` value (defined by `IntoInner`)
    ///   from which to create the instance.
    ///
    /// # Panics
    ///
    /// In debug mode, this method will panic if `Self::try_new(value)`
    /// returns `Err`. The panic message will include the error's description.
    /// In release mode, the panic behavior depends on the implementation
    /// of `Self::new(value)`.
    fn create_conditionally(value: Self::InnerType) -> Self {
        #[cfg(debug_assertions)]
        {
            // In debug mode, use try_new and panic on error.
            Self::try_new(value)
                .expect("ConditionallyCreate: try_new() failed in debug mode")
        }
        #[cfg(not(debug_assertions))]
        {
            // In release mode, use new (which is assumed to be infallible
            // or to handle failure internally, e.g., by panicking).
            Self::new(value)
        }
    }
}

// Blanket implementation of `ConditionallyCreate` for all types `T`
// that implement [`TryNew`] and [`New`], and whose `TryNew::Error` type
// implements `Debug`.
impl<T> ConditionallyCreate for T
where
    T: TryNew + New,
    <T as TryNew>::Error: core::fmt::Debug, // This bound is inherited from the trait definition
{
    // The `create_conditionally` method already has a default implementation in the trait,
    // so it doesn't need to be redefined here.
}


#[cfg(test)]
mod tests {
    use super::*; // Import traits from the parent module (your library)

    // --- Test setup for PositiveInteger ---
    #[derive(Debug, PartialEq)]
    struct TestNotPositiveError;

    // Implement Display and Error for TestNotPositiveError for std builds
    #[cfg(feature = "std")]
    impl std::fmt::Display for TestNotPositiveError {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            write!(f, "Value must be positive (Test Error)")
        }
    }

    #[cfg(feature = "std")]
    impl std::error::Error for TestNotPositiveError {}

    // For no_std, deriving Debug is sufficient as per TryNew's Error bound.

    #[derive(Debug, PartialEq)]
    struct TestPositiveInteger {
        value: i32,
    }

    impl IntoInner for TestPositiveInteger {
        type InnerType = i32;
        fn into_inner(self) -> Self::InnerType {
            self.value
        }
    }

    impl TryNew for TestPositiveInteger {
        type Error = TestNotPositiveError;
        fn try_new(value: Self::InnerType) -> Result<Self, Self::Error> {
            if value > 0 {
                Ok(TestPositiveInteger { value })
            } else {
                Err(TestNotPositiveError)
            }
        }
    }

    impl New for TestPositiveInteger {
        fn new(value: Self::InnerType) -> Self {
            // Consistent with the example: panic if try_new would fail
            match Self::try_new(value) {
                Ok(instance) => instance,
                Err(_) => panic!("TestPositiveInteger::new: Value must be positive."),
            }
        }
    }

    // --- Tests for PositiveInteger ---
    #[test]
    fn test_positive_integer_try_new_ok() {
        assert_eq!(
            TestPositiveInteger::try_new(10),
            Ok(TestPositiveInteger { value: 10 })
        );
    }

    #[test]
    fn test_positive_integer_try_new_err_zero() {
        assert_eq!(TestPositiveInteger::try_new(0), Err(TestNotPositiveError));
    }

    #[test]
    fn test_positive_integer_try_new_err_negative() {
        assert_eq!(TestPositiveInteger::try_new(-5), Err(TestNotPositiveError));
    }

    #[test]
    fn test_positive_integer_new_ok() {
        assert_eq!(TestPositiveInteger::new(10), TestPositiveInteger { value: 10 });
    }

    #[test]
    #[should_panic(expected = "TestPositiveInteger::new: Value must be positive.")]
    fn test_positive_integer_new_panic_zero() {
        TestPositiveInteger::new(0);
    }

    #[test]
    #[should_panic(expected = "TestPositiveInteger::new: Value must be positive.")]
    fn test_positive_integer_new_panic_negative() {
        TestPositiveInteger::new(-10);
    }

    #[test]
    fn test_positive_integer_into_inner() {
        let pi = TestPositiveInteger::new(42);
        assert_eq!(pi.into_inner(), 42);
    }

    #[test]
    #[cfg(debug_assertions)] // This test specifically targets the debug behavior
    fn test_positive_integer_conditionally_create_debug_ok() {
        assert_eq!(
            TestPositiveInteger::create_conditionally(10),
            TestPositiveInteger { value: 10 }
        );
    }

    #[test]
    #[cfg(debug_assertions)] // This test specifically targets the debug behavior
    #[should_panic(expected = "ConditionallyCreate: try_new() failed in debug mode")]
    fn test_positive_integer_conditionally_create_debug_panic() {
        TestPositiveInteger::create_conditionally(-5);
    }
    
    #[test]
    #[cfg(not(debug_assertions))] // This test specifically targets the release behavior
    fn test_positive_integer_conditionally_create_release_ok() {
        assert_eq!(
            TestPositiveInteger::create_conditionally(10),
            TestPositiveInteger { value: 10 }
        );
    }

    #[test]
    #[cfg(not(debug_assertions))] // This test specifically targets the release behavior
    #[should_panic(expected = "TestPositiveInteger::new: Value must be positive.")]
    fn test_positive_integer_conditionally_create_release_panic() {
        // In release, create_conditionally calls new(), which for TestPositiveInteger panics.
        TestPositiveInteger::create_conditionally(-5);
    }


    // --- Test setup for MyType (from New example) ---
    #[derive(Debug, PartialEq)]
    struct TestMyTypeError(String);

    #[cfg(feature = "std")]
    impl std::fmt::Display for TestMyTypeError {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            write!(f, "TestMyTypeError: {}", self.0)
        }
    }

    #[cfg(feature = "std")]
    impl std::error::Error for TestMyTypeError {}


    #[derive(Debug, PartialEq)]
    struct TestMyType(i32);

    impl IntoInner for TestMyType {
        type InnerType = i32;
        fn into_inner(self) -> Self::InnerType {
            self.0
        }
    }

    impl TryNew for TestMyType {
        type Error = TestMyTypeError;
        fn try_new(value: i32) -> Result<Self, Self::Error> {
            if value < 0 {
                Err(TestMyTypeError("Value cannot be negative".to_string()))
            } else {
                Ok(TestMyType(value))
            }
        }
    }
    
    impl New for TestMyType {
        fn new(value: i32) -> Self {
            if value < 0 {
                panic!("TestMyType::new: Value cannot be negative");
            }
            TestMyType(value)
        }
    }

    // --- Tests for MyType ---
    #[test]
    fn test_my_type_try_new_ok() {
        assert_eq!(TestMyType::try_new(5), Ok(TestMyType(5)));
    }

    #[test]
    fn test_my_type_try_new_err() {
        assert_eq!(
            TestMyType::try_new(-1),
            Err(TestMyTypeError("Value cannot be negative".to_string()))
        );
    }
    
    #[test]
    fn test_my_type_new_ok() {
        assert_eq!(TestMyType::new(100), TestMyType(100));
    }

    #[test]
    #[should_panic(expected = "TestMyType::new: Value cannot be negative")]
    fn test_my_type_new_panic() {
        TestMyType::new(-1);
    }

    #[test]
    fn test_my_type_into_inner() {
        let mt = TestMyType::new(7);
        assert_eq!(mt.into_inner(), 7);
    }

    #[test]
    #[cfg(debug_assertions)]
    fn test_my_type_conditionally_create_debug_ok() {
        assert_eq!(
            TestMyType::create_conditionally(20),
            TestMyType(20)
        );
    }

    #[test]
    #[cfg(debug_assertions)]
    #[should_panic(expected = "ConditionallyCreate: try_new() failed in debug mode")]
    fn test_my_type_conditionally_create_debug_panic() {
        TestMyType::create_conditionally(-3);
    }

    #[test]
    #[cfg(not(debug_assertions))]
    fn test_my_type_conditionally_create_release_ok() {
        assert_eq!(
            TestMyType::create_conditionally(20),
            TestMyType(20)
        );
    }

    #[test]
    #[cfg(not(debug_assertions))]
    #[should_panic(expected = "TestMyType::new: Value cannot be negative")]
    fn test_my_type_conditionally_create_release_panic() {
        TestMyType::create_conditionally(-3);
    }
}