miniextendr_api/

adapter_traits.rs

//! Built-in adapter traits for common Rust standard library traits.
//!
//! These traits provide blanket implementations that allow any Rust type
//! implementing standard traits to be exposed to R without boilerplate.
//!
//! # Example
//!
//! ```rust,ignore
//! use miniextendr_api::prelude::*;
//!
//! #[derive(Debug, ExternalPtr)]
//! struct MyData {
//!     values: Vec<i32>,
//! }
//!
//! // RDebug is automatically available for any Debug type
//! #[miniextendr]
//! impl miniextendr_api::adapter_traits::RDebug for MyData {}
//! ```
//!
//! In R:
//! ```r
//! data <- MyData$new(...)
//! data$RDebug$debug_str()        # "MyData { values: [1, 2, 3] }"
//! data$RDebug$debug_str_pretty() # Pretty-printed with newlines
//! ```
//!
//! # Rust method names
//!
//! A method whose name a std trait or a covered type already uses gets an
//! `r_` prefix in Rust and keeps the std name in R through
//! `#[miniextendr(r_name = "...")]`: `RClone::r_clone` is `clone()` in R.
//! The blanket impls cover every `Clone`, `Default`, `Hash`, `Ord`,
//! `PartialOrd` and `FromStr` type, and `RToVec` every array and boxed slice,
//! so with the std names an import of these traits would make the importing
//! module's own `v.clone()` or `a.cmp(&b)` ambiguous (E0034), and its
//! `[T; N]::len()` an `i64`.
//!
//! Both empty and populated `#[miniextendr] impl` blocks inherit the trait's
//! R names and skipped methods. This includes generic `RToVec<T>` and
//! `RExtend<T>` and the associated-type `RIterator`. An explicit impl-level
//! `r_name` overrides the declaration's name for that implementation.

use crate::Nullable;
use crate::miniextendr;
use std::collections::hash_map::DefaultHasher;
use std::fmt::{Debug, Display};
use std::hash::{Hash, Hasher};
use std::str::FromStr;

/// Adapter trait for [`std::fmt::Debug`].
///
/// Provides string representations for debugging and inspection in R.
/// Automatically implemented for any type that implements `Debug`.
///
/// # Methods
///
/// - `debug_str()` - Returns compact debug string (`:?` format)
/// - `debug_str_pretty()` - Returns pretty-printed debug string (`:#?` format)
///
/// # Example
///
/// ```rust,ignore
/// #[derive(Debug, ExternalPtr)]
/// struct Config { name: String, value: i32 }
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RDebug for Config {}
/// ```
#[miniextendr]
pub trait RDebug {
    /// Get a compact debug string representation.
    fn debug_str(&self) -> String;

    /// Get a pretty-printed debug string with indentation.
    fn debug_str_pretty(&self) -> String;
}

impl<T: Debug> RDebug for T {
    fn debug_str(&self) -> String {
        format!("{:?}", self)
    }

    fn debug_str_pretty(&self) -> String {
        format!("{:#?}", self)
    }
}

/// Adapter trait for [`std::fmt::Display`].
///
/// Provides user-friendly string conversion for R.
/// Automatically implemented for any type that implements `Display`.
///
/// # Methods
///
/// - `as_r_string()` - Returns the Display representation
///
/// # Example
///
/// ```rust,ignore
/// struct Version(u32, u32, u32);
///
/// impl Display for Version {
///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
///         write!(f, "{}.{}.{}", self.0, self.1, self.2)
///     }
/// }
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RDisplay for Version {}
/// ```
#[miniextendr]
pub trait RDisplay {
    /// Convert to a user-friendly string.
    fn as_r_string(&self) -> String;
}

impl<T: Display> RDisplay for T {
    fn as_r_string(&self) -> String {
        self.to_string()
    }
}

/// Adapter trait for [`std::hash::Hash`].
///
/// Provides hashing for deduplication and environment keys in R.
/// Automatically implemented for any type that implements `Hash`.
///
/// # Methods
///
/// - `r_hash()` (`hash()` in R) - Returns the 64-bit hash as a 16-character
///   hex string
///
/// # Note
///
/// Hash values are deterministic within a single R session but may vary
/// between sessions due to Rust's hasher implementation.
///
/// The hash is returned as a hex `String` (e.g. `"a1b2c3d4e5f60718"`), not a
/// number. R has no faithful 64-bit integer type, so returning the `u64` as a
/// numeric would round away its low bits above `2^53` — distinct Rust values
/// would collide in R — and surface half the range as negative. A hex string
/// preserves all 64 bits, is directly usable as an R environment key, and
/// works with `duplicated()` / `match()` for deduplication.
///
/// # Example
///
/// ```rust,ignore
/// #[derive(Hash, ExternalPtr)]
/// struct Record { id: String, value: i64 }
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RHash for Record {}
/// ```
#[miniextendr]
pub trait RHash {
    /// Compute a hash of this value.
    ///
    /// Returns the [`DefaultHasher`] `u64` output as a 16-character lowercase
    /// hex string. See the trait-level docs for why a string rather than a
    /// number.
    #[miniextendr(r_name = "hash")]
    fn r_hash(&self) -> String;
}

impl<T: Hash> RHash for T {
    fn r_hash(&self) -> String {
        let mut hasher = DefaultHasher::new();
        Hash::hash(self, &mut hasher);
        // R has no faithful 64-bit integer; hex-encode the full u64 so every
        // bit survives the trip to R (a numeric would round above 2^53).
        format!("{:016x}", hasher.finish())
    }
}

/// Adapter trait for [`std::cmp::Ord`].
///
/// Provides total ordering comparison for R sorting operations.
/// Automatically implemented for any type that implements `Ord`.
///
/// # Methods
///
/// - `r_cmp(&self, other: &Self)` (`cmp()` in R) - Returns -1, 0, or 1
///
/// # Example
///
/// ```rust,ignore
/// #[derive(Ord, PartialOrd, Eq, PartialEq, ExternalPtr)]
/// struct Priority(u32);
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::ROrd for Priority {}
/// ```
#[miniextendr]
pub trait ROrd {
    /// Compare with another value.
    ///
    /// Returns:
    /// - `-1` if `self < other`
    /// - `0` if `self == other`
    /// - `1` if `self > other`
    #[miniextendr(r_name = "cmp")]
    fn r_cmp(&self, other: &Self) -> i32;
}

impl<T: Ord> ROrd for T {
    fn r_cmp(&self, other: &Self) -> i32 {
        match Ord::cmp(self, other) {
            std::cmp::Ordering::Less => -1,
            std::cmp::Ordering::Equal => 0,
            std::cmp::Ordering::Greater => 1,
        }
    }
}

/// Adapter trait for [`std::cmp::PartialOrd`].
///
/// Provides partial ordering comparison for R, handling incomparable values.
/// Automatically implemented for any type that implements `PartialOrd`.
///
/// # Methods
///
/// - `r_partial_cmp(&self, other: &Self)` (`partial_cmp()` in R) - Returns
///   Some(-1/0/1) or None
///
/// # Example
///
/// ```rust,ignore
/// // f64 has partial ordering (NaN is not comparable)
/// #[derive(PartialOrd, PartialEq, ExternalPtr)]
/// struct MyFloat(f64);
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RPartialOrd for MyFloat {}
/// ```
#[miniextendr]
pub trait RPartialOrd {
    /// Compare with another value, returning None if incomparable.
    ///
    /// Returns:
    /// - `Some(-1)` if `self < other`
    /// - `Some(0)` if `self == other`
    /// - `Some(1)` if `self > other`
    /// - `None` if values are incomparable (in R, `NA`)
    #[miniextendr(r_name = "partial_cmp")]
    fn r_partial_cmp(&self, other: &Self) -> Option<i32>;
}

impl<T: PartialOrd> RPartialOrd for T {
    fn r_partial_cmp(&self, other: &Self) -> Option<i32> {
        PartialOrd::partial_cmp(self, other).map(|ord| match ord {
            std::cmp::Ordering::Less => -1,
            std::cmp::Ordering::Equal => 0,
            std::cmp::Ordering::Greater => 1,
        })
    }
}

/// Adapter trait for [`std::error::Error`].
///
/// Provides error message extraction and error chain walking for R.
/// Automatically implemented for any type that implements `Error`.
///
/// # Methods
///
/// - `error_message()` - Returns the error's display message
/// - `error_chain()` - Returns all messages in the error chain
///
/// # Example
///
/// ```rust,ignore
/// use std::error::Error;
/// use std::fmt;
///
/// #[derive(Debug)]
/// struct MyError { msg: String, source: Option<Box<dyn Error + Send + Sync>> }
///
/// impl fmt::Display for MyError {
///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
///         write!(f, "{}", self.msg)
///     }
/// }
///
/// impl Error for MyError {
///     fn source(&self) -> Option<&(dyn Error + 'static)> {
///         self.source.as_ref().map(|e| e.as_ref() as _)
///     }
/// }
///
/// // Wrap in ExternalPtr for R access
/// #[derive(ExternalPtr)]
/// struct MyErrorWrapper(MyError);
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RError for MyErrorWrapper {}
/// ```
#[miniextendr]
pub trait RError {
    /// Get the error message (Display representation).
    fn error_message(&self) -> String;

    /// Get all error messages in the chain, from outermost to innermost.
    fn error_chain(&self) -> Vec<String>;

    /// Get the number of errors in the chain.
    fn error_chain_length(&self) -> i32;
}

impl<T: std::error::Error> RError for T {
    fn error_message(&self) -> String {
        self.to_string()
    }

    fn error_chain(&self) -> Vec<String> {
        let mut chain = vec![self.to_string()];
        let mut current: &dyn std::error::Error = self;
        while let Some(source) = current.source() {
            chain.push(source.to_string());
            current = source;
        }
        chain
    }

    fn error_chain_length(&self) -> i32 {
        let mut count = 1i32;
        let mut current: &dyn std::error::Error = self;
        while let Some(source) = current.source() {
            count += 1;
            current = source;
        }
        count
    }
}

/// Adapter trait for [`std::str::FromStr`].
///
/// Provides string parsing for R, allowing R strings to be parsed into Rust types.
/// Automatically implemented for any type that implements `FromStr`.
///
/// # Methods
///
/// - `r_from_str(s: &str)` (`from_str()` in R) - Parse a string into this
///   type, returning None on failure
///
/// # Example
///
/// ```rust,ignore
/// use std::net::IpAddr;
///
/// // IpAddr implements FromStr
/// #[derive(ExternalPtr)]
/// struct IpAddress(IpAddr);
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RFromStr for IpAddress {}
/// ```
///
/// In R:
/// ```r
/// ip <- IpAddress$RFromStr$from_str("192.168.1.1")
/// ```
#[miniextendr]
pub trait RFromStr: Sized {
    /// Parse a string into this type.
    ///
    /// Returns `Some(value)` on success, `None` on parse failure, which R
    /// receives as `NULL`.
    #[miniextendr(r_name = "from_str")]
    fn r_from_str(s: &str) -> Option<Self>;
}

impl<T: FromStr> RFromStr for T {
    fn r_from_str(s: &str) -> Option<Self> {
        s.parse().ok()
    }
}

/// Adapter trait for [`std::clone::Clone`].
///
/// Provides explicit deep copying for R. This is useful when R users need
/// to create independent copies of Rust objects (which normally use reference
/// semantics via `ExternalPtr`).
///
/// # Methods
///
/// - `r_clone()` (`clone()` in R) - Create a deep copy of this value
///
/// # Example
///
/// ```rust,ignore
/// #[derive(Clone, ExternalPtr)]
/// struct Buffer { data: Vec<u8> }
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RClone for Buffer {}
/// ```
///
/// In R:
/// ```r
/// buf1 <- Buffer$new(...)
/// buf2 <- buf1$RClone$clone()  # Independent copy
/// ```
#[miniextendr]
pub trait RClone {
    /// Create a deep copy of this value.
    #[miniextendr(r_name = "clone")]
    fn r_clone(&self) -> Self;
}

impl<T: Clone> RClone for T {
    fn r_clone(&self) -> Self {
        Clone::clone(self)
    }
}

/// Adapter trait for [`std::default::Default`].
///
/// Provides default value construction for R. This allows R users to create
/// instances with default values without needing to specify all parameters.
///
/// # Methods
///
/// - `r_default()` (`default()` in R) - Create a new instance with default
///   values
///
/// # Example
///
/// ```rust,ignore
/// #[derive(Default, ExternalPtr)]
/// struct Config {
///     timeout: u32,     // defaults to 0
///     retries: u32,     // defaults to 0
///     verbose: bool,    // defaults to false
/// }
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RDefault for Config {}
/// ```
///
/// In R:
/// ```r
/// config <- Config$RDefault$default()  # All fields have default values
/// ```
#[miniextendr]
pub trait RDefault {
    /// Create a new instance with default values.
    #[miniextendr(r_name = "default")]
    fn r_default() -> Self;
}

impl<T: Default> RDefault for T {
    fn r_default() -> Self {
        <T as Default>::default()
    }
}

/// Adapter trait for [`std::marker::Copy`].
///
/// Indicates that a type can be cheaply copied (bitwise copy, no heap allocation).
/// This is useful for R users to know that copying is O(1) and doesn't involve
/// deep cloning of heap data.
///
/// # Methods
///
/// - `copy()` - Create a bitwise copy of this value
/// - `is_copy()` - Returns true (useful for runtime type checking in R)
///
/// # Difference from RClone
///
/// Both `RCopy` and `RClone` create copies, but:
/// - `RCopy`: Only for types where copying is cheap (stack-only, no heap)
/// - `RClone`: For any clonable type (may involve heap allocation)
///
/// If a type implements both, prefer `copy()` when you know copies are frequent.
///
/// # Example
///
/// ```rust,ignore
/// #[derive(Copy, Clone, ExternalPtr)]
/// struct Point { x: f64, y: f64 }
///
/// #[miniextendr]
/// impl miniextendr_api::adapter_traits::RCopy for Point {}
/// ```
///
/// In R:
/// ```r
/// p1 <- Point$new(1.0, 2.0)
/// p2 <- p1$RCopy$copy()  # Cheap bitwise copy
/// p1$RCopy$is_copy()       # TRUE
/// ```
#[miniextendr]
pub trait RCopy {
    /// Create a bitwise copy of this value.
    ///
    /// For Copy types, this is always cheap (O(1), no heap allocation).
    fn copy(&self) -> Self;

    /// Check if this type implements Copy.
    ///
    /// Always returns true for types implementing this trait.
    /// Useful for runtime type checking in R.
    fn is_copy(&self) -> bool;
}

impl<T: Copy> RCopy for T {
    fn copy(&self) -> Self {
        *self
    }

    fn is_copy(&self) -> bool {
        true
    }
}

/// Adapter trait for [`std::iter::Iterator`].
///
/// Provides iterator operations for R, allowing Rust iterators to be consumed
/// element-by-element from R code. Since iterators are stateful, the wrapper
/// type should use interior mutability (e.g., `RefCell`).
///
/// # Methods
///
/// - `next()` (`next_item()` in R) - Get the next element, or None if exhausted
/// - `size_hint()` - Get estimated remaining elements as `list(lower, upper)`
/// - `count()` - Consume and count remaining elements
/// - `collect_n(n)` - Collect up to n elements into a vector
/// - `skip(n)` - Skip n elements
/// - `nth(n)` - Get the nth element (0-indexed)
///
/// # Example
///
/// ```rust,ignore
/// use miniextendr_api::Nullable;
/// use miniextendr_api::adapter_traits::RIterator;
/// use std::cell::RefCell;
///
/// #[derive(ExternalPtr)]
/// struct MyIter(RefCell<std::vec::IntoIter<i32>>);
///
/// #[miniextendr(env)]
/// impl MyIter {
///     fn new(data: Vec<i32>) -> Self {
///         Self(RefCell::new(data.into_iter()))
///     }
/// }
///
/// // An impl with a body inherits the trait's R names; each method here
/// // forwards to the cell.
/// #[miniextendr(env)]
/// impl miniextendr_api::adapter_traits::RIterator for MyIter {
///     type Item = i32;
///
///     fn next(&self) -> Nullable<i32> {
///         self.0.next()
///     }
///
///     fn size_hint(&self) -> (i64, Option<i64>) {
///         self.0.size_hint()
///     }
///
///     fn count(&self) -> i64 {
///         self.0.count()
///     }
///
///     fn collect_n(&self, n: i32) -> Vec<i32> {
///         self.0.collect_n(n)
///     }
///
///     fn skip(&self, n: i32) -> i32 {
///         self.0.skip(n)
///     }
///
///     fn nth(&self, n: i32) -> Nullable<i32> {
///         self.0.nth(n)
///     }
/// }
/// ```
///
/// In R (`next` is a reserved word, so the method is `next_item`):
/// ```r
/// it <- MyIter$new(c(1L, 2L, 3L))
/// it$RIterator$next_item()   # 1L
/// it$RIterator$next_item()   # 2L
/// it$RIterator$size_hint()   # list(1L, 1L) - one element remaining
/// it$RIterator$collect_n(5L) # 3L
/// it$RIterator$next_item()   # NULL (exhausted)
/// ```
///
/// # Design Note
///
/// Every `RefCell<I>` with `I: Iterator` implements this trait. The cell
/// supplies mutable access without erasing the iterator or restricting its item
/// type. A concrete ExternalPtr class can delegate to its cell. This also covers
/// standard-library adapters, `itertools` adapters and distribution iterators.
///
/// The blanket implementation forwards `nth` to the iterator, retaining its
/// specialized implementation. It follows the source's
/// exhaustion behavior; use `Iterator::fuse` when `None` must be permanent.
#[miniextendr]
pub trait RIterator {
    /// The type of elements yielded by this iterator.
    type Item;

    /// Get the next element from the iterator.
    ///
    /// Returns `Nullable(Some(item))` while there are elements, and
    /// `Nullable(None)` once exhausted, which R receives as `NULL` whatever
    /// the item type: an `NA` could be an item, `NULL` never is.
    #[miniextendr(r_name = "next_item")]
    fn next(&self) -> Nullable<Self::Item>;

    /// Get the estimated number of remaining elements.
    ///
    /// Returns `(lower_bound, upper_bound)` where upper_bound is None if unknown.
    /// In R, this becomes `list(lower, upper)` where upper is NA if unknown.
    fn size_hint(&self) -> (i64, Option<i64>);

    /// Consume the iterator and count remaining elements.
    ///
    /// **Warning:** This exhausts the iterator.
    fn count(&self) -> i64 {
        let mut count = 0i64;
        while self.next().0.is_some() {
            count += 1;
        }
        count
    }

    /// Collect up to `n` elements into a vector.
    ///
    /// Returns fewer than `n` elements if the iterator is exhausted first.
    fn collect_n(&self, n: i32) -> Vec<Self::Item> {
        let mut result = Vec::with_capacity(n.max(0) as usize);
        for _ in 0..n {
            match self.next().0 {
                Some(item) => result.push(item),
                None => break,
            }
        }
        result
    }

    /// Skip `n` elements from the iterator.
    ///
    /// Returns the number of elements actually skipped (may be less than `n`
    /// if the iterator is exhausted).
    fn skip(&self, n: i32) -> i32 {
        let mut skipped = 0i32;
        for _ in 0..n {
            if self.next().0.is_none() {
                break;
            }
            skipped += 1;
        }
        skipped
    }

    /// Get the `n`th element (0-indexed), consuming elements up to and including it.
    ///
    /// Returns `Nullable(None)` (`NULL` in R) if `n` is negative or the
    /// iterator has fewer than `n + 1` elements.
    fn nth(&self, n: i32) -> Nullable<Self::Item> {
        if n < 0 {
            return Nullable(None);
        }
        for _ in 0..n {
            if self.next().0.is_none() {
                return Nullable(None);
            }
        }
        self.next()
    }
}

impl<I: Iterator> RIterator for std::cell::RefCell<I> {
    type Item = I::Item;

    fn next(&self) -> Nullable<Self::Item> {
        Nullable(self.borrow_mut().next())
    }

    fn size_hint(&self) -> (i64, Option<i64>) {
        let (lower, upper) = self.borrow().size_hint();
        // An unbounded iterator may report usize::MAX as its lower bound.
        // Saturating the lower bound and omitting an unrepresentable upper
        // bound keeps both valid in this trait's signed representation.
        (
            i64::try_from(lower).unwrap_or(i64::MAX),
            upper.and_then(|value| i64::try_from(value).ok()),
        )
    }

    fn count(&self) -> i64 {
        i64::try_from(self.borrow_mut().by_ref().count()).expect("iterator count exceeds i64::MAX")
    }

    fn collect_n(&self, n: i32) -> Vec<Self::Item> {
        let n = usize::try_from(n.max(0)).expect("nonnegative i32 fits usize");
        self.borrow_mut().by_ref().take(n).collect()
    }

    fn skip(&self, n: i32) -> i32 {
        let n = usize::try_from(n.max(0)).expect("nonnegative i32 fits usize");
        i32::try_from(self.borrow_mut().by_ref().take(n).count())
            .expect("skipped count is bounded by n")
    }

    fn nth(&self, n: i32) -> Nullable<Self::Item> {
        Nullable(
            usize::try_from(n)
                .ok()
                .and_then(|n| self.borrow_mut().nth(n)),
        )
    }
}

/// Adapter trait for [`std::iter::Extend`].
///
/// Provides collection extension operations for R, allowing Rust collections
/// to be extended with R vectors. Since extension requires mutation, the
/// wrapper type should use interior mutability (e.g., `RefCell`).
///
/// # Methods
///
/// - `extend_from_vec(items)` - Extend the collection with items from a vector
/// - `extend_from_slice(items)` - Extend from a slice (for Clone items)
/// - `r_len()` (`len()` in R) - Get the current length, or -1 if unknown
/// - `r_is_empty()` (`is_empty()` in R) - Check if the collection is empty
///
/// # Example
///
/// ```rust,ignore
/// use std::cell::RefCell;
///
/// #[derive(ExternalPtr)]
/// struct MyVec(RefCell<Vec<i32>>);
///
/// #[miniextendr(env)]
/// impl MyVec {
///     fn new() -> Self {
///         Self(RefCell::new(Vec::new()))
///     }
/// }
///
/// // The trait is generic, so the impl spells out each exported method and
/// // repeats the R names of the renamed ones.
/// #[miniextendr(env)]
/// impl miniextendr_api::adapter_traits::RExtend<i32> for MyVec {
///     fn extend_from_vec(&self, items: Vec<i32>) {
///         self.0.borrow_mut().extend(items);
///     }
///
///     fn r_len(&self) -> i64 {
///         i64::try_from(self.0.borrow().len()).expect("length fits i64")
///     }
///
///     fn r_is_empty(&self) -> bool {
///         self.0.borrow().is_empty()
///     }
/// }
/// ```
///
/// In R:
/// ```r
/// v <- MyVec$new()
/// v$RExtend$extend_from_vec(c(1L, 2L, 3L))  # Add items
/// v$RExtend$extend_from_vec(c(4L, 5L))      # Add more items
/// v$RExtend$len()                           # 5
/// ```
///
/// # Design Note
///
/// Like `RIterator`, `RExtend` does NOT have a blanket impl because `Extend::extend()`
/// requires `&mut self`, but R's ExternalPtr pattern provides `&self`. Users must
/// implement this trait manually using interior mutability (RefCell, Mutex, etc.).
#[miniextendr]
pub trait RExtend<T> {
    /// Extend the collection with items from a vector.
    ///
    /// The items are moved into the collection.
    fn extend_from_vec(&self, items: Vec<T>);

    /// Extend the collection with cloned items from a slice.
    ///
    /// Default implementation clones items into a Vec and calls `extend_from_vec`.
    ///
    /// Skipped from trait ABI because `&[T]` doesn't have TryFromSexp.
    #[miniextendr(skip)]
    fn extend_from_slice(&self, items: &[T])
    where
        T: Clone,
    {
        self.extend_from_vec(items.to_vec());
    }

    /// Get the current length of the collection.
    ///
    /// Optional - returns -1 if not implemented.
    #[miniextendr(r_name = "len")]
    fn r_len(&self) -> i64 {
        -1 // Indicates "unknown" - implementers can override
    }

    /// Check if the collection is empty.
    ///
    /// Returns false when length is unknown.
    #[miniextendr(r_name = "is_empty")]
    fn r_is_empty(&self) -> bool {
        self.r_len() == 0
    }
}

// Note: No blanket impl because Extend::extend() requires &mut self,
// but ExternalPtr methods receive &self. Users must use interior mutability.

/// Adapter trait for [`std::iter::FromIterator`].
///
/// Provides collection construction from iterators/vectors for R.
/// Unlike `RExtend`, this creates a new collection from items.
///
/// # Methods
///
/// - `from_vec(items)` - Create a new collection from a vector
///
/// # Example
///
/// ```rust,ignore
/// #[derive(ExternalPtr)]
/// struct MySet(std::collections::HashSet<i32>);
///
/// #[miniextendr(env)]
/// impl miniextendr_api::adapter_traits::RFromIter<i32> for MySet {
///     fn from_vec(items: Vec<i32>) -> Self {
///         Self(items.into_iter().collect())
///     }
/// }
/// ```
///
/// In R:
/// ```r
/// set <- MySet$RFromIter$from_vec(c(1L, 2L, 2L, 3L))  # Creates {1, 2, 3}
/// ```
#[miniextendr]
pub trait RFromIter<T>: Sized {
    /// Create a new collection from a vector of items.
    fn from_vec(items: Vec<T>) -> Self;
}

impl<C, T> RFromIter<T> for C
where
    C: FromIterator<T>,
{
    fn from_vec(items: Vec<T>) -> Self {
        items.into_iter().collect()
    }
}

/// Adapter trait for collections that can be converted to vectors.
///
/// This is the complement to [`RFromIter`]: while `RFromIter` creates collections
/// from vectors, `RToVec` extracts vectors from collections.
///
/// # Methods
///
/// - `r_to_vec()` (`to_vec()` in R) - Collect all elements into a vector
///   (cloning elements)
/// - `r_len()` (`len()` in R) - Get the number of elements
/// - `r_is_empty()` (`is_empty()` in R) - Check if the collection is empty
///
/// # Design Note
///
/// Unlike Rust's `IntoIterator::into_iter()` which consumes the collection,
/// this trait borrows the collection and clones elements. This is necessary
/// because R's `ExternalPtr` pattern provides `&self`, not owned `self`.
///
/// For consuming iteration, use [`RIterator`] with interior mutability.
///
/// # Example
///
/// ```rust,ignore
/// use miniextendr_api::adapter_traits::RToVec;
/// use std::collections::HashSet;
///
/// #[derive(ExternalPtr)]
/// struct MySet(HashSet<i32>);
///
/// // `&MySet` doesn't iterate, so the blanket impl doesn't cover the wrapper:
/// // the impl forwards to the set, which it does cover. The trait is generic,
/// // so the impl spells out each method; R names come from the trait.
/// #[miniextendr(env)]
/// impl miniextendr_api::adapter_traits::RToVec<i32> for MySet {
///     fn r_to_vec(&self) -> Vec<i32> {
///         self.0.r_to_vec()
///     }
///
///     fn r_len(&self) -> i64 {
///         self.0.r_len()
///     }
///
///     fn r_is_empty(&self) -> bool {
///         self.0.is_empty()
///     }
/// }
/// ```
///
/// In R:
/// ```r
/// set <- MySet$new(...)
/// vec <- set$RToVec$to_vec()    # Get all elements as vector
/// set$RToVec$len()              # Number of elements
/// set$RToVec$is_empty()         # Check if empty
/// ```
#[miniextendr]
pub trait RToVec<T> {
    /// Collect all elements into a vector.
    ///
    /// Elements are cloned from the collection.
    #[miniextendr(r_name = "to_vec")]
    fn r_to_vec(&self) -> Vec<T>;

    /// Get the number of elements in the collection.
    #[miniextendr(r_name = "len")]
    fn r_len(&self) -> i64;

    /// Check if the collection is empty.
    #[miniextendr(r_name = "is_empty")]
    fn r_is_empty(&self) -> bool {
        self.r_len() == 0
    }
}

// Blanket impl for any collection where:
// - &C can be iterated over (yielding &T references)
// - T: Clone (so we can clone elements into the Vec)
// - The iterator knows its exact size
//
// Note: Using HRTB (higher-ranked trait bounds) to express that &C
// can be iterated for any lifetime.
impl<C, T> RToVec<T> for C
where
    T: Clone,
    for<'a> &'a C: IntoIterator<Item = &'a T>,
    for<'a> <&'a C as IntoIterator>::IntoIter: ExactSizeIterator,
{
    fn r_to_vec(&self) -> Vec<T> {
        self.into_iter().cloned().collect()
    }

    fn r_len(&self) -> i64 {
        i64::try_from(self.into_iter().len()).expect("collection length exceeds i64::MAX")
    }
}

/// Adapter trait for creating iterator wrappers from collections.
///
/// This trait provides a way to create an [`RIterator`] wrapper from a collection.
/// Since `ExternalPtr` methods receive `&self`, this trait clones the underlying
/// data to create an independent iterator.
///
/// # Type Parameters
///
/// - `T`: The element type yielded by the iterator
/// - `I`: The iterator type returned (must implement [`RIterator`])
///
/// # Design Note
///
/// The returned iterator is independent from the source collection. Modifications
/// to the original collection after calling `make_iter()` won't affect the
/// iterator's output.
///
/// # Example
///
/// ```rust,ignore
/// use std::cell::RefCell;
///
/// #[derive(ExternalPtr)]
/// struct MyVec(Vec<i32>);
///
/// #[derive(ExternalPtr)]
/// struct MyVecIter(RefCell<std::vec::IntoIter<i32>>);
///
/// // `MyVecIter` implements `RIterator` as in the `RIterator` example.
///
/// #[miniextendr(env)]
/// impl miniextendr_api::adapter_traits::RMakeIter<i32, MyVecIter> for MyVec {
///     fn make_iter(&self) -> MyVecIter {
///         MyVecIter(RefCell::new(self.0.clone().into_iter()))
///     }
/// }
/// ```
///
/// In R (`next` is a reserved word, so the method is `next_item`):
/// ```r
/// v <- MyVec$new(c(1L, 2L, 3L))
/// it <- v$RMakeIter$make_iter()   # Create iterator
/// it$RIterator$next_item()        # 1L
/// it$RIterator$next_item()        # 2L
/// ```
#[miniextendr]
pub trait RMakeIter<T, I>
where
    I: RIterator<Item = T>,
{
    /// Create a new iterator wrapper.
    ///
    /// The iterator is independent from this collection (typically by cloning
    /// the underlying data).
    fn make_iter(&self) -> I;
}

// Note: No blanket impl because:
// 1. The iterator type I must be a concrete type that implements RIterator
// 2. RIterator requires interior mutability (RefCell/Mutex)
// 3. Users must define their own iterator wrapper type

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_rdebug() {
        let v = vec![1, 2, 3];
        assert_eq!(v.debug_str(), "[1, 2, 3]");
        assert!(v.debug_str_pretty().contains('\n') || v.debug_str_pretty() == "[1, 2, 3]");
    }

    #[test]
    fn test_rdisplay() {
        let s = "hello";
        assert_eq!(s.as_r_string(), "hello");

        let n = 42i32;
        assert_eq!(n.as_r_string(), "42");
    }

    #[test]
    fn test_rhash() {
        let a = "test";
        let b = "test";
        let c = "other";

        assert_eq!(a.r_hash(), b.r_hash());
        assert_ne!(a.r_hash(), c.r_hash());
    }

    #[test]
    fn test_rord() {
        assert_eq!(1i32.r_cmp(&2), -1);
        assert_eq!(2i32.r_cmp(&2), 0);
        assert_eq!(3i32.r_cmp(&2), 1);
    }

    #[test]
    fn test_rpartialord() {
        assert_eq!(1.0f64.r_partial_cmp(&2.0), Some(-1));
        assert_eq!(2.0f64.r_partial_cmp(&2.0), Some(0));
        assert_eq!(3.0f64.r_partial_cmp(&2.0), Some(1));
        assert_eq!(f64::NAN.r_partial_cmp(&1.0), None);
    }

    #[test]
    fn test_rerror_simple() {
        use std::io;
        let err = io::Error::new(io::ErrorKind::NotFound, "file not found");
        assert_eq!(err.error_message(), "file not found");
        assert_eq!(err.error_chain().len(), 1);
        assert_eq!(err.error_chain_length(), 1);
    }

    #[test]
    fn test_rerror_chain() {
        use std::fmt;

        #[derive(Debug)]
        struct OuterError {
            msg: &'static str,
            source: InnerError,
        }

        #[derive(Debug)]
        struct InnerError {
            msg: &'static str,
        }

        impl fmt::Display for OuterError {
            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
                write!(f, "{}", self.msg)
            }
        }

        impl fmt::Display for InnerError {
            fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
                write!(f, "{}", self.msg)
            }
        }

        impl std::error::Error for InnerError {}

        impl std::error::Error for OuterError {
            fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
                Some(&self.source)
            }
        }

        let err = OuterError {
            msg: "outer error",
            source: InnerError { msg: "inner error" },
        };

        assert_eq!(err.error_message(), "outer error");
        let chain = err.error_chain();
        assert_eq!(chain.len(), 2);
        assert_eq!(chain[0], "outer error");
        assert_eq!(chain[1], "inner error");
        assert_eq!(err.error_chain_length(), 2);
    }

    #[test]
    fn test_rfromstr_success() {
        assert_eq!(i32::r_from_str("42"), Some(42));
        assert_eq!(
            f64::r_from_str("3.141592653589793"),
            Some(std::f64::consts::PI)
        );
        assert_eq!(bool::r_from_str("true"), Some(true));
    }

    #[test]
    fn test_rfromstr_failure() {
        assert_eq!(i32::r_from_str("not a number"), None);
        assert_eq!(f64::r_from_str("abc"), None);
    }

    #[test]
    fn test_rclone() {
        let v = vec![1, 2, 3];
        let cloned = v.r_clone();
        assert_eq!(v, cloned);

        // Verify it's a deep copy
        let s = String::from("hello");
        let cloned_s = s.r_clone();
        assert_eq!(s, cloned_s);
    }

    #[test]
    fn test_rdefault() {
        assert_eq!(i32::r_default(), 0);
        assert!(Vec::<i32>::r_default().is_empty());
        assert_eq!(String::r_default(), "");
        assert!(!bool::r_default());
    }

    #[test]
    fn test_rcopy() {
        // Primitives are Copy
        let x = 42i32;
        let y = RCopy::copy(&x);
        assert_eq!(x, y);
        assert!(x.is_copy());

        // Tuples of Copy types are Copy
        let point = (1.0f64, 2.0f64);
        let point2 = RCopy::copy(&point);
        assert_eq!(point, point2);
        assert!(point.is_copy());

        // Arrays of Copy types are Copy
        let arr = [1, 2, 3];
        let arr2 = RCopy::copy(&arr);
        assert_eq!(arr, arr2);
    }

    // Tests for RIterator
    use std::cell::RefCell;

    /// Test iterator wrapper using RefCell for interior mutability.
    struct TestIter(RefCell<std::vec::IntoIter<i32>>);

    impl TestIter {
        fn new(data: Vec<i32>) -> Self {
            Self(RefCell::new(data.into_iter()))
        }
    }

    impl RIterator for TestIter {
        type Item = i32;

        fn next(&self) -> Nullable<Self::Item> {
            Nullable(self.0.borrow_mut().next())
        }

        fn size_hint(&self) -> (i64, Option<i64>) {
            let (lo, hi) = self.0.borrow().size_hint();
            (lo as i64, hi.map(|h| h as i64))
        }
    }

    #[test]
    fn test_riterator_next() {
        let it = TestIter::new(vec![1, 2, 3]);
        assert_eq!(it.next().0, Some(1));
        assert_eq!(it.next().0, Some(2));
        assert_eq!(it.next().0, Some(3));
        assert_eq!(it.next().0, None);
        assert_eq!(it.next().0, None); // Stays exhausted
    }

    #[test]
    fn test_riterator_size_hint() {
        let it = TestIter::new(vec![1, 2, 3, 4, 5]);
        assert_eq!(it.size_hint(), (5, Some(5)));
        it.next();
        assert_eq!(it.size_hint(), (4, Some(4)));
        it.next();
        it.next();
        assert_eq!(it.size_hint(), (2, Some(2)));
    }

    #[test]
    fn test_riterator_count() {
        let it = TestIter::new(vec![1, 2, 3, 4, 5]);
        assert_eq!(it.count(), 5);
        // Iterator is now exhausted
        assert_eq!(it.next().0, None);
    }

    #[test]
    fn test_riterator_collect_n() {
        let it = TestIter::new(vec![1, 2, 3, 4, 5]);
        let first_three = it.collect_n(3);
        assert_eq!(first_three, vec![1, 2, 3]);
        let remaining = it.collect_n(10); // Ask for more than available
        assert_eq!(remaining, vec![4, 5]);
    }

    #[test]
    fn test_riterator_skip() {
        let it = TestIter::new(vec![1, 2, 3, 4, 5]);
        let skipped = it.skip(2);
        assert_eq!(skipped, 2);
        assert_eq!(it.next().0, Some(3));

        // Skip more than remaining
        let skipped = it.skip(10);
        assert_eq!(skipped, 2); // Only 2 elements were left
    }

    #[test]
    fn test_riterator_nth() {
        let it = TestIter::new(vec![10, 20, 30, 40, 50]);
        // Get element at index 2 (third element)
        assert_eq!(it.nth(2).0, Some(30));
        // Iterator has consumed 0, 1, 2 - next is index 3
        assert_eq!(it.next().0, Some(40));

        // Negative index returns None
        let it2 = TestIter::new(vec![1, 2, 3]);
        assert_eq!(it2.nth(-1).0, None);
    }

    #[test]
    fn test_riterator_empty() {
        let it = TestIter::new(vec![]);
        assert_eq!(it.next().0, None);
        assert_eq!(it.size_hint(), (0, Some(0)));
        assert_eq!(it.count(), 0);
        assert_eq!(it.collect_n(5), Vec::<i32>::new());
        assert_eq!(it.skip(5), 0);
        assert_eq!(it.nth(0).0, None);
    }

    // Tests for RExtend
    struct TestExtendVec(RefCell<Vec<i32>>);

    impl TestExtendVec {
        fn new() -> Self {
            Self(RefCell::new(Vec::new()))
        }

        fn get(&self) -> Vec<i32> {
            Clone::clone(&*self.0.borrow())
        }
    }

    impl RExtend<i32> for TestExtendVec {
        fn extend_from_vec(&self, items: Vec<i32>) {
            self.0.borrow_mut().extend(items);
        }

        fn r_len(&self) -> i64 {
            i64::try_from(self.0.borrow().len()).expect("length fits i64")
        }
    }

    #[test]
    fn test_rextend_basic() {
        let v = TestExtendVec::new();
        assert_eq!(v.get(), Vec::<i32>::new());
        assert_eq!(v.r_len(), 0);
        assert!(v.r_is_empty());

        v.extend_from_vec(vec![1, 2, 3]);
        assert_eq!(v.get(), vec![1, 2, 3]);
        assert_eq!(v.r_len(), 3);
        assert!(!v.r_is_empty());

        v.extend_from_vec(vec![4, 5]);
        assert_eq!(v.get(), vec![1, 2, 3, 4, 5]);
        assert_eq!(v.r_len(), 5);
    }

    #[test]
    fn test_rextend_empty() {
        let v = TestExtendVec::new();
        v.extend_from_vec(vec![]);
        assert_eq!(v.get(), Vec::<i32>::new());
        assert_eq!(v.r_len(), 0);
    }

    /// The default `r_len` reports an unknown length, which isn't empty.
    #[test]
    fn test_rextend_unknown_len() {
        struct Sink;
        impl RExtend<i32> for Sink {
            fn extend_from_vec(&self, _items: Vec<i32>) {}
        }
        assert_eq!(Sink.r_len(), -1);
        assert!(!Sink.r_is_empty());
    }

    #[test]
    fn test_rextend_from_slice() {
        let v = TestExtendVec::new();
        let data = [1, 2, 3];
        v.extend_from_slice(&data);
        assert_eq!(v.get(), vec![1, 2, 3]);
    }

    // Tests for RFromIter
    #[test]
    fn test_rfromiter_vec() {
        let v: Vec<i32> = RFromIter::from_vec(vec![1, 2, 3]);
        assert_eq!(v, vec![1, 2, 3]);
    }

    #[test]
    fn test_rfromiter_hashset() {
        use std::collections::HashSet;
        let set: HashSet<i32> = RFromIter::from_vec(vec![1, 2, 2, 3, 3, 3]);
        assert_eq!(set.len(), 3);
        assert!(set.contains(&1));
        assert!(set.contains(&2));
        assert!(set.contains(&3));
    }

    #[test]
    fn test_rfromiter_string() {
        let s: String = RFromIter::from_vec(vec!['h', 'e', 'l', 'l', 'o']);
        assert_eq!(s, "hello");
    }

    #[test]
    fn test_rfromiter_empty() {
        let v: Vec<i32> = RFromIter::from_vec(vec![]);
        assert!(v.is_empty());
    }

    // Tests for RToVec
    #[test]
    fn test_rtovec_vec() {
        let v = vec![1, 2, 3];
        assert_eq!(v.r_to_vec(), vec![1, 2, 3]);
        assert_eq!(v.r_len(), 3);
        assert!(!v.r_is_empty());
    }

    #[test]
    fn test_rtovec_empty() {
        let v: Vec<i32> = vec![];
        assert!(v.r_to_vec().is_empty());
        assert_eq!(v.r_len(), 0);
        assert!(v.r_is_empty());
    }

    #[test]
    fn test_rtovec_hashset() {
        use std::collections::HashSet;
        let mut set = HashSet::new();
        set.insert(1);
        set.insert(2);
        set.insert(3);

        let mut collected = set.r_to_vec();
        collected.sort();
        assert_eq!(collected, vec![1, 2, 3]);
        assert_eq!(set.r_len(), 3);
    }

    #[test]
    fn test_rtovec_slice() {
        let arr = [10, 20, 30];
        assert_eq!(arr.r_to_vec(), vec![10, 20, 30]);
        assert_eq!(arr.r_len(), 3);
    }

    /// With every adapter trait in scope (`use super::*`), the std methods of
    /// the types their blanket impls cover still resolve to std, with std's
    /// result types.
    #[test]
    fn test_std_methods_resolve_with_adapters_in_scope() {
        use std::hash::DefaultHasher;

        let v = vec![1, 2, 3];
        let cloned: Vec<i32> = v.clone();
        assert_eq!(cloned, v);
        assert_eq!(String::default(), "");
        assert_eq!(1.cmp(&2), std::cmp::Ordering::Less);
        assert_eq!(1.0f64.partial_cmp(&2.0), Some(std::cmp::Ordering::Less));
        let mut hasher = DefaultHasher::new();
        v.hash(&mut hasher);
        let _: u64 = hasher.finish();
        assert_eq!(i32::from_str("7"), Ok(7));

        let arr = [10, 20, 30];
        let len: usize = arr.len();
        assert_eq!(len, 3);
        assert!(!arr.is_empty());
        let boxed: Box<[i32]> = vec![1, 2].into_boxed_slice();
        let boxed_len: usize = boxed.len();
        assert_eq!(boxed_len, 2);
        assert_eq!(boxed.to_vec(), vec![1, 2]);
    }

    // Tests for RMakeIter
    struct TestCollection(Vec<i32>);

    struct TestCollectionIter(RefCell<std::vec::IntoIter<i32>>);

    impl RIterator for TestCollectionIter {
        type Item = i32;

        fn next(&self) -> Nullable<i32> {
            Nullable(self.0.borrow_mut().next())
        }

        fn size_hint(&self) -> (i64, Option<i64>) {
            let (lo, hi) = self.0.borrow().size_hint();
            (lo as i64, hi.map(|h| h as i64))
        }
    }

    impl RMakeIter<i32, TestCollectionIter> for TestCollection {
        fn make_iter(&self) -> TestCollectionIter {
            TestCollectionIter(RefCell::new(Clone::clone(&self.0).into_iter()))
        }
    }

    #[test]
    fn test_rmakeiter_basic() {
        let coll = TestCollection(vec![1, 2, 3]);
        let iter = coll.make_iter();

        assert_eq!(iter.next().0, Some(1));
        assert_eq!(iter.next().0, Some(2));
        assert_eq!(iter.next().0, Some(3));
        assert_eq!(iter.next().0, None);
    }

    #[test]
    fn test_rmakeiter_independent() {
        let coll = TestCollection(vec![1, 2, 3]);

        // Create two independent iterators
        let iter1 = coll.make_iter();
        let iter2 = coll.make_iter();

        // Consuming one doesn't affect the other
        assert_eq!(iter1.next().0, Some(1));
        assert_eq!(iter1.next().0, Some(2));

        assert_eq!(iter2.next().0, Some(1)); // iter2 starts fresh
        assert_eq!(iter2.size_hint(), (2, Some(2))); // 2 remaining in iter2
    }
}