Struct ProtectedStrVec 

pub struct ProtectedStrVec {
    inner: StrVec,
    len: isize,
    _protect: Option<OwnedProtect>,
}

GC-protected view over an R character vector (STRSXP).

Unlike StrVec (which is Copy and trusts the caller for GC protection), ProtectedStrVec owns an OwnedProtect guard that keeps the STRSXP alive. All borrowed data (&str, iterators) has its lifetime tied to &self, not 'static — preventing use-after-GC bugs at compile time.

When to use

• StrVec: for SEXP arguments to .Call (R protects them), or when you manage protection yourself. Lightweight, Copy.
• ProtectedStrVec: when you allocate or receive an STRSXP and need to keep it alive beyond the immediate scope. Not Copy.

Example

#[miniextendr]
pub fn count_unique(strings: ProtectedStrVec) -> i32 {
    let unique: HashSet<&str> = strings.iter()
        .filter_map(|s| s)
        .collect();
    unique.len() as i32
}

Fields

inner: StrVec

len: isize

_protect: Option<OwnedProtect>

Implementations

impl ProtectedStrVec

pub unsafe fn new(sexp: SEXP) -> Self

Create a protected view over an STRSXP.

Calls Rf_protect on the SEXP. Use from_sexp_trusted when the SEXP is already protected (e.g., .Call arguments) to avoid double-protecting.

Safety

• sexp must be a valid STRSXP.
• Must be called from the R main thread.

pub unsafe fn from_sexp_trusted(sexp: SEXP) -> Self

Create a view without adding GC protection.

Use this when the SEXP is already protected by R (e.g., a .Call argument, or in a ProtectScope). Avoids the redundant Rf_protect/Rf_unprotect pair.

The lifetime-bound &str borrows are still enforced — this only skips the protect stack push, not the safety guarantees.

Safety

• sexp must be a valid STRSXP.
• sexp must remain GC-protected for the lifetime of this struct.
• Must be called from the R main thread.

pub fn len(&self) -> isize

Number of elements.

pub fn is_empty(&self) -> bool

Whether the vector is empty.

pub fn get_str(&self, idx: isize) -> Option<&str>

Get the string at index (zero-copy, lifetime tied to &self).

Returns None for out-of-bounds or NA_character_.

pub fn get_cow(&self, idx: isize) -> Option<Cow<'_, str>>

Get the string at index as Cow<str> (encoding-safe, lifetime tied to &self).

pub fn iter(&self) -> ProtectedStrVecIter<'_>

Iterate over elements as Option<&str> (lifetime tied to &self).

pub fn iter_cow(&self) -> ProtectedStrVecCowIter<'_>

Iterate over elements as Option<Cow<str>> (encoding-safe).

pub fn as_sexp(&self) -> SEXP

Get the underlying SEXP (still protected by this handle).

pub fn as_strvec(&self) -> StrVec

Get the inner StrVec (unprotected copy — caller assumes protection responsibility).

Trait Implementations

impl Debug for ProtectedStrVec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> IntoIterator for &'a ProtectedStrVec

type Item = Option<&'a str>

The type of the elements being iterated over.

type IntoIter = ProtectedStrVecIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoR for ProtectedStrVec

type Error = Infallible

The error type for fallible conversions.

fn try_into_sexp(self) -> Result<SEXP, Self::Error>

Try to convert this value to an R SEXP.

unsafe fn try_into_sexp_unchecked(self) -> Result<SEXP, Self::Error>

Try to convert to SEXP without thread safety checks.

fn into_sexp(self) -> SEXP

Convert this value to an R SEXP, panicking on error.

unsafe fn into_sexp_unchecked(self) -> SEXP

where Self: Sized,

Convert to SEXP without thread safety checks, panicking on error.

impl TryFromSexp for ProtectedStrVec

type Error = SexpError

The error type returned when conversion fails.

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.