Struct ProtectedStrVec 

pub struct ProtectedStrVec {
    sexp: SEXP,
    _root: Option<Preserved>,
    children: ChildRoots,
    len: isize,
}

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

Unlike StrVec (which is Copy and trusts the caller for GC protection), ProtectedStrVec holds a Preserved root on the STRSXP for its Rust lifetime. It can outlive a .Call frame and be dropped in any order relative to other handles. Borrowed strings and iterators are tied to &self. It is !Send + !Sync: reading and releasing the R object must happen on R’s main thread.

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

sexp: SEXP

_root: Option<Preserved>

None for from_sexp_trusted, whose caller roots sexp. The field also makes the handle !Send + !Sync.

children: ChildRoots

len: isize

Implementations

impl ProtectedStrVec

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

Create a protected view over an STRSXP.

Roots the SEXP with a Preserved handle, released on drop, independently of R’s protection stack. Use from_sexp_trusted only when another owner guarantees reachability for this handle’s entire lifetime.

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) for the handle’s entire lifetime. Avoids an additional preserved root.

The lifetime-bound &str borrows are still enforced — this only skips acquiring a root; the unsafe caller must supply it.

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 view, leashed to &self (the protect guard).

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 = !

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

const CHARACTER_ONLY: bool = true

Whether this conversion accepts only character input: every value it converts, other than NULL, is a character vector or a factor.

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.

const NATIVE_BORROW: Option<NativeBorrow> = None

Native vector storage retained by this conversion, if any.

#[doc(hidden)]

const __MX_EXPECTATION: Option<&'static str> = None

What an argument of this type must be, in R terms, when #[miniextendr] cannot tell from the type as written: the <expected> of a failed conversion’s '<p>' must be <expected>: ....

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

Convert from SEXP without thread safety checks.

#[doc(hidden)]

unsafe fn __mx_try_from_rooted(root: Root<'_>) -> Result<Self, Self::Error>

Convert with a scope able to retain uncached ALTREP elements. Custom reference converters keep their existing behavior by default.

#[doc(hidden)]

fn __mx_has_na(&self) -> bool

Whether the converted argument holds a value #[miniextendr(no_na)] refuses after the conversion.

#[doc(hidden)]

fn __mx_input_has_na(&self, input: SEXP) -> bool

Whether #[miniextendr(no_na)] refuses this converted argument, read from input (the R value it converted from), when no R guard ran.

#[doc(hidden)]

fn __mx_try_from_sexp_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>

where Self::Error: Into<SexpError>,

Convert, running check, an element type’s TryFromSexpElement::check_sexp, on the R value that carries an element’s class (#1837).

#[doc(hidden)]

unsafe fn __mx_try_from_sexp_unchecked_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>

where Self::Error: Into<SexpError>,

__mx_try_from_sexp_with_check through try_from_sexp_unchecked. Not public API.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 48 bytes