miniextendr_api/from_r/

strings.rs

//! String conversions — STRSXP requires special handling via `STRING_ELT`.
//!
//! R stores strings as STRSXP (vector of CHARSXP). Each element requires
//! `STRING_ELT` + `R_CHAR` to extract, unlike numeric vectors which expose
//! a contiguous data pointer.
//!
//! Covers: `&str`, `String`, `char`, `Option<&str>`, `Option<String>`,
//! `Vec<String>`, `Vec<&str>`, `Box<[String]>`.
//!
//! # Tradeoff
//!
//! Prefer borrowed `&str` / `Vec<&str>` over owned `String` / `Vec<String>`
//! when the data only needs to live for the `.Call` — borrowed strings point
//! straight into R's CHARSXP pool with no allocation. Use `Option<String>`
//! / `Vec<Option<String>>` when callers may pass `NA_character_`; the plain
//! `String` / `Vec<String>` impls map NA to `""`, which is lossy. The optional
//! forms preserve the distinction as `None`.
//!
//! UTF-8 validity is guaranteed by `miniextendr_assert_utf8_locale()` at
//! package init — these impls skip per-string validation. Outbound
//! counterparts: `String` / `&str` impls in [`crate::into_r`].

use crate::from_r::{
    SexpError, TryFromSexp, charsxp_to_str, charsxp_to_str_unchecked, scalar_charsxp,
    scalar_charsxp_unchecked,
};
use crate::{SEXP, SEXPTYPE, SexpExt};

/// Convert R character vector (STRSXP) to Rust &str.
///
/// Extracts the first element of the character vector and returns it as a UTF-8 string.
/// The Rust type uses a static lifetime for API convenience, but the borrow is
/// only valid while the source CHARSXP remains reachable.
///
/// # NA Handling
///
/// **Warning:** `NA_character_` is converted to empty string `""`. This is lossy!
/// If you need to distinguish between NA and empty strings, use `Option<String>` instead:
///
/// ```ignore
/// let maybe_str: Option<String> = sexp.try_into()?;
/// ```
///
/// # Safety
/// The returned &str is only valid as long as R doesn't garbage collect the CHARSXP.
/// For ALTSTRING inputs, rooting the source alone may not retain its elements.
/// Use `TryFromRoot` to retain uncached elements for the call's scope.
impl TryFromSexp for &'static str {
    type Error = SexpError;
    const CHARACTER_ONLY: bool = true;

    #[inline]
    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
        let charsxp = scalar_charsxp(sexp)?;

        // Check for NA_STRING or R_BlankString
        if charsxp == SEXP::na_string() {
            return Ok("");
        }
        if charsxp == SEXP::blank_string() {
            return Ok("");
        }

        // Use LENGTH-based conversion (O(1)) instead of CStr::from_ptr (O(n) strlen)
        Ok(unsafe { charsxp_to_str(charsxp) })
    }

    unsafe fn __mx_try_from_rooted(root: crate::Root<'_>) -> Result<Self, Self::Error> {
        let charsxp = scalar_charsxp(root.get())?;
        if charsxp == SEXP::na_string() || charsxp == SEXP::blank_string() {
            return Ok("");
        }
        let charsxp = unsafe { root.protect_child(charsxp) }.get();
        Ok(unsafe { charsxp_to_str(charsxp) })
    }

    #[inline]
    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
        let charsxp = unsafe { scalar_charsxp_unchecked(sexp)? };

        // Check for NA_STRING or R_BlankString
        if charsxp == SEXP::na_string() {
            return Ok("");
        }
        if charsxp == SEXP::blank_string() {
            return Ok("");
        }

        // Use LENGTH-based conversion (O(1)) instead of CStr::from_ptr (O(n) strlen)
        Ok(unsafe { charsxp_to_str_unchecked(charsxp) })
    }
}

impl TryFromSexp for Option<&'static str> {
    type Error = SexpError;
    const CHARACTER_ONLY: bool = true;

    #[inline]
    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
        if sexp.type_of() == SEXPTYPE::NILSXP {
            return Ok(None);
        }

        let charsxp = scalar_charsxp(sexp)?;
        if charsxp == SEXP::na_string() {
            return Ok(None);
        }
        if charsxp == SEXP::blank_string() {
            return Ok(Some(""));
        }

        Ok(Some(unsafe { charsxp_to_str(charsxp) }))
    }

    unsafe fn __mx_try_from_rooted(root: crate::Root<'_>) -> Result<Self, Self::Error> {
        if root.get().type_of() == SEXPTYPE::NILSXP {
            return Ok(None);
        }
        let charsxp = scalar_charsxp(root.get())?;
        if charsxp == SEXP::na_string() {
            return Ok(None);
        }
        if charsxp == SEXP::blank_string() {
            return Ok(Some(""));
        }
        let charsxp = unsafe { root.protect_child(charsxp) }.get();
        Ok(Some(unsafe { charsxp_to_str(charsxp) }))
    }

    #[inline]
    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
        if sexp.type_of() == SEXPTYPE::NILSXP {
            return Ok(None);
        }

        let charsxp = unsafe { scalar_charsxp_unchecked(sexp)? };
        if charsxp == SEXP::na_string() {
            return Ok(None);
        }
        if charsxp == SEXP::blank_string() {
            return Ok(Some(""));
        }

        Ok(Some(unsafe { charsxp_to_str_unchecked(charsxp) }))
    }
}

/// Convert R character vector (STRSXP) to Rust char.
///
/// Extracts the first character of the first element of the character vector.
/// Returns an error if the string is empty, NA, or has more than one character.
impl TryFromSexp for char {
    type Error = SexpError;
    const CHARACTER_ONLY: bool = true;

    #[inline]
    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
        let s: &str = TryFromSexp::try_from_sexp(sexp)?;
        let mut chars = s.chars();
        match (chars.next(), chars.next()) {
            (Some(c), None) => Ok(c),
            (None, _) => Err(SexpError::InvalidValue(
                "empty string cannot be converted to char".to_string(),
            )),
            (Some(_), Some(_)) => Err(SexpError::InvalidValue(
                "string has more than one character".to_string(),
            )),
        }
    }

    #[inline]
    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
        let s: &str = unsafe { TryFromSexp::try_from_sexp_unchecked(sexp)? };
        let mut chars = s.chars();
        match (chars.next(), chars.next()) {
            (Some(c), None) => Ok(c),
            (None, _) => Err(SexpError::InvalidValue(
                "empty string cannot be converted to char".to_string(),
            )),
            (Some(_), Some(_)) => Err(SexpError::InvalidValue(
                "string has more than one character".to_string(),
            )),
        }
    }
}

/// Convert R character vector (STRSXP) to owned Rust String.
///
/// Extracts the first element and creates an owned copy.
///
/// # NA Handling
///
/// **Warning:** `NA_character_` is converted to empty string `""`. This is lossy!
/// If you need to distinguish between NA and empty strings, use `Option<String>` instead:
///
/// ```ignore
/// let maybe_str: Option<String> = sexp.try_into()?;
/// ```
impl TryFromSexp for String {
    type Error = SexpError;
    const CHARACTER_ONLY: bool = true;

    #[inline]
    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
        let charsxp = scalar_charsxp(sexp)?;

        if charsxp == SEXP::na_string() {
            return Ok(String::new());
        }

        Ok(unsafe { charsxp_to_str(charsxp) }.to_owned())
    }

    #[inline]
    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
        let charsxp = unsafe { scalar_charsxp_unchecked(sexp)? };

        if charsxp == SEXP::na_string() {
            return Ok(String::new());
        }

        Ok(unsafe { charsxp_to_str_unchecked(charsxp) }.to_owned())
    }
}

/// NA-aware string conversion: returns `None` for `NA_character_`.
///
/// Use this when you need to distinguish between NA and empty strings:
/// ```ignore
/// let maybe_str: Option<String> = sexp.try_into()?;
/// match maybe_str {
///     Some(s) => println!("Got string: {}", s),
///     None => println!("Got NA"),
/// }
/// ```
impl TryFromSexp for Option<String> {
    type Error = SexpError;
    const CHARACTER_ONLY: bool = true;

    #[inline]
    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
        // NULL -> None
        if sexp.type_of() == SEXPTYPE::NILSXP {
            return Ok(None);
        }

        let charsxp = scalar_charsxp(sexp)?;

        // Return None for NA_STRING
        if charsxp == SEXP::na_string() {
            return Ok(None);
        }

        Ok(Some(unsafe { charsxp_to_str(charsxp) }.to_owned()))
    }

    #[inline]
    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
        // For Option<String>, unchecked is same as checked (NA check is semantic, not safety)
        Self::try_from_sexp(sexp)
    }
}
// endregion

// region: Owned unsized strings
//
// Preserve String's scalar/NA semantics and vector diagnostics. Each string is
// owned before returning, so no CHARSXP borrow escapes in an Rc/Arc/Box.
macro_rules! impl_owned_str_from_r {
    ($owner:ident) => {
        impl TryFromSexp for $owner<str> {
            type Error = SexpError;
            const CHARACTER_ONLY: bool = true;
            fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
                String::try_from_sexp(sexp).map(Self::from)
            }
            unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
                unsafe { String::try_from_sexp_unchecked(sexp) }.map(Self::from)
            }
        }
        impl TryFromSexp for Option<$owner<str>> {
            type Error = SexpError;
            const CHARACTER_ONLY: bool = true;
            fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
                Option::<String>::try_from_sexp(sexp).map(|v| v.map($owner::from))
            }
            unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
                unsafe { Option::<String>::try_from_sexp_unchecked(sexp) }
                    .map(|v| v.map($owner::from))
            }
        }
        impl TryFromSexp for Vec<$owner<str>> {
            type Error = SexpError;
            const CHARACTER_ONLY: bool = true;
            fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
                Vec::<String>::try_from_sexp(sexp)
                    .map(|v| v.into_iter().map($owner::from).collect())
            }
            unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
                unsafe { Vec::<String>::try_from_sexp_unchecked(sexp) }
                    .map(|v| v.into_iter().map($owner::from).collect())
            }
        }
        impl TryFromSexp for Vec<Option<$owner<str>>> {
            type Error = SexpError;
            const CHARACTER_ONLY: bool = true;
            fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
                Vec::<Option<String>>::try_from_sexp(sexp)
                    .map(|v| v.into_iter().map(|s| s.map($owner::from)).collect())
            }
            unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> {
                unsafe { Vec::<Option<String>>::try_from_sexp_unchecked(sexp) }
                    .map(|v| v.into_iter().map(|s| s.map($owner::from)).collect())
            }
        }
    };
}
use std::rc::Rc;
use std::sync::Arc;
impl_owned_str_from_r!(Box);
impl_owned_str_from_r!(Rc);
impl_owned_str_from_r!(Arc);
// endregion