miniextendr_api/into_r/

result.rs

//! `Result<T, E>` conversions to R.
//!
//! Used by `#[miniextendr(unwrap_in_r)]` to pass Results to R as values
//! (`Err` becomes `list(error = ...)`), instead of unwrapping in Rust.
//! Also provides `NullOnErr` for `Result<T, ()>` → NULL-on-error semantics.
//!
//! # Tradeoff
//!
//! The two impls in this module have different gating conditions:
//!
//! - `IntoR for Result<T, E: Display>` (the `list(error = ...)` shape) fires
//!   **only** under `#[miniextendr(unwrap_in_r)]` (Result-as-value). Without
//!   that attribute, a `Result<T, E>` return acts as an **error boundary**:
//!   `Err(e)` panics with `Debug`-formatted `e`, the framework's
//!   tagged-condition transport carries it to R, and the wrapper raises a
//!   classed `rust_*` condition. Failure mode of opting into `unwrap_in_r`
//!   without telling R callers: they suddenly need to check `$error` on every
//!   return value instead of using `tryCatch`.
//! - `IntoR for Result<T, NullOnErr>` fires whenever the error type is `()`,
//!   **independent of `unwrap_in_r`**: the macro rewrites `Result<T, ()>` to
//!   `Result<T, NullOnErr>` before the `unwrap_in_r` check, so `Err(())`
//!   returns `NULL` to R in both modes. A unit error is a deliberate
//!   "no value" sentinel, not a Rust failure — it never raises an R error.

use std::collections::HashMap;

use crate::into_r::IntoR;

/// Convert `Result<T, E>` to R (value-style, for `#[miniextendr(unwrap_in_r)]`).
///
/// # Behavior
///
/// - `Ok(value)` → returns the converted value directly
/// - `Err(msg)` → returns `list(error = "<msg>")` (value-style error)
///
/// # When This Is Used
///
/// This impl is **only used** when `#[miniextendr(unwrap_in_r)]` is specified.
/// Without that attribute, `#[miniextendr]` functions returning `Result<T, E>`
/// will unwrap in Rust and raise an R error on `Err` (error boundary semantics).
///
/// # Error Handling Summary
///
/// | Mode | On `Err(e)` | Bound Required |
/// |------|-------------|----------------|
/// | Default | R error via panic | `E: Debug` |
/// | `unwrap_in_r` | `list(error = ...)` | `E: Display` |
///
/// **Default** (without `unwrap_in_r`): `Result<T, E>` acts as an error boundary:
/// - `Ok(v)` → `v` converted to R
/// - `Err(e)` → R error with Debug-formatted message (requires `E: Debug`)
///
/// **With `unwrap_in_r`**: `Result<T, E>` is passed through to R:
/// - `Ok(v)` → `v` converted to R
/// - `Err(e)` → `list(error = e.to_string())` (requires `E: Display`)
///
/// **Exception**: `Result<T, ()>` never reaches this impl in either mode —
/// the macro rewrites it to `Result<T, NullOnErr>` before the `unwrap_in_r`
/// check, and `Err(())` returns `NULL`. See [`NullOnErr`].
///
/// # Example
///
/// ```ignore
/// // Default: error boundary - Err becomes R stop()
/// #[miniextendr]
/// fn divide(x: f64, y: f64) -> Result<f64, String> {
///     if y == 0.0 { Err("division by zero".into()) }
///     else { Ok(x / y) }
/// }
/// // In R: tryCatch(divide(1, 0), error = ...) catches the error
///
/// // Value-style: Err becomes list(error = ...)
/// #[miniextendr(unwrap_in_r)]
/// fn divide_safe(x: f64, y: f64) -> Result<f64, String> {
///     if y == 0.0 { Err("division by zero".into()) }
///     else { Ok(x / y) }
/// }
/// // In R: result <- divide_safe(1, 0)
/// //       if (!is.null(result$error)) { handle error }
/// ```
impl<T, E> IntoR for Result<T, E>
where
    T: IntoR,
    E: std::fmt::Display,
{
    type Error = std::convert::Infallible;
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        self.try_into_sexp()
    }
    fn into_sexp(self) -> crate::SEXP {
        match self {
            Ok(value) => value.into_sexp(),
            Err(msg) => {
                // Create list(error = msg) for R-side error handling
                let mut map = HashMap::with_capacity(1);
                map.insert("error".to_string(), msg.to_string());
                map.into_sexp()
            }
        }
    }
}

/// Marker type for `Result<T, ()>` that converts `Err(())` to NULL.
///
/// This type is used internally by the `#[miniextendr]` macro when handling
/// `Result<T, ()>` return types. When the error type is `()`, there's no
/// error message to report, so we return NULL instead of raising an error.
///
/// # Usage
///
/// You typically don't use this directly. When you write:
///
/// ```ignore
/// #[miniextendr]
/// fn maybe_value(x: i32) -> Result<i32, ()> {
///     if x > 0 { Ok(x) } else { Err(()) }
/// }
/// ```
///
/// The macro generates code that converts `Err(())` to `Err(NullOnErr)` and
/// returns `NULL` in R. This rewrite fires whenever the error type is `()`,
/// **whether or not** `#[miniextendr(unwrap_in_r)]` is set — the unit-error
/// check runs before the `unwrap_in_r` check.
///
/// # Note
///
/// `NullOnErr` intentionally does NOT implement `Display` to avoid conflicting
/// with the generic `IntoR for Result<T, E: Display>` impl. It has its own
/// specialized `IntoR` impl that returns NULL on error.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct NullOnErr;

/// Convert `Result<T, NullOnErr>` to R, returning NULL on error.
///
/// This is a special case for `Result<T, ()>` types where the error
/// carries no information. Instead of raising an R error, we return NULL.
/// Fires whenever the error type is `()`, independent of
/// `#[miniextendr(unwrap_in_r)]`.
impl<T: IntoR> IntoR for Result<T, NullOnErr> {
    type Error = std::convert::Infallible;
    fn try_into_sexp(self) -> Result<crate::SEXP, Self::Error> {
        Ok(self.into_sexp())
    }
    unsafe fn try_into_sexp_unchecked(self) -> Result<crate::SEXP, Self::Error> {
        self.try_into_sexp()
    }
    fn into_sexp(self) -> crate::SEXP {
        match self {
            Ok(value) => value.into_sexp(),
            Err(NullOnErr) => crate::SEXP::nil(),
        }
    }
}