Struct StrVec 

pub struct StrVec<'a>(SEXP, PhantomData<&'a str>);

Borrowed view over an R character vector (STRSXP).

The 'a lifetime leashes every &str this view hands out to the window in which the underlying STRSXP stays GC-reachable. At a #[miniextendr] boundary, write StrVec<'_>: R protects .Call arguments for the call’s duration, so the elided lifetime is bounded by the call and the borrows cannot escape into an ExternalPtr, a global, or another thread — doing so is a compile error (the &str would have to outlive 'a). Callers that own the rooting obligation reach for the unsafe *_static family instead.

Copy and cheap (a single SEXP); covariant in 'a.

Tuple Fields

0: SEXP

1: PhantomData<&'a str>

Implementations

impl<'a> StrVec<'a>

pub const unsafe fn from_raw(sexp: SEXP) -> Self

Wrap an existing STRSXP without additional checks.

Safety

Caller must ensure sexp is a valid character vector (STRSXP) that stays GC-reachable for the inferred lifetime 'a.

pub const fn as_sexp(self) -> SEXP

Get the underlying SEXP.

pub fn len(self) -> isize

Length of the character vector (number of elements).

pub fn is_empty(self) -> bool

Returns true if the vector is empty.

pub fn get_charsxp(self, idx: isize) -> Option<SEXP>

Get the CHARSXP at the given index.

Returns None if out of bounds.

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

Get the string at the given index (zero-copy), leashed to 'a.

Returns None if out of bounds or if the element is NA_character_. Panics if the CHARSXP is not valid UTF-8 (should not happen in a UTF-8 locale).

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

Get the string at the given index as Cow<str> (encoding-safe), leashed to 'a.

Returns Cow::Borrowed for UTF-8 strings (zero-copy), Cow::Owned for non-UTF-8 strings (translated via Rf_translateCharUTF8). Returns None if out of bounds or NA_character_.

pub unsafe fn get_str_static(self, idx: isize) -> Option<&'static str>

Get the string at the given index as &'static str — the courageous escape.

Unlike get_str, the returned reference is not leashed to 'a, so it can be stored in an ExternalPtr, a global, or sent across threads. The string data lives in R’s CHARSXP; it is only valid while that STRSXP stays GC-reachable.

Safety

The caller takes on the rooting obligation: the underlying STRSXP must be kept reachable by R (e.g. via the prot slot of the ExternalPtr it is stored in, or R_PreserveObject) for as long as the returned &'static str is used. Letting R GC the source is use-after-free.

pub unsafe fn get_cow_static(self, idx: isize) -> Option<Cow<'static, str>>

Get the string at the given index as Cow<'static, str> — the courageous escape.

Cow analogue of get_str_static; same rooting obligation for the borrowed (Cow::Borrowed) case.

Safety

See get_str_static.

pub fn iter(self) -> StrVecIter<'a>

Iterate over elements as Option<&str> (leashed to 'a).

NA_character_ elements yield None, valid strings yield Some(&str). Zero-copy — each &str borrows directly from R’s CHARSXP.

pub fn iter_cow(self) -> StrVecCowIter<'a>

Iterate over elements as Option<Cow<str>> (encoding-safe, leashed to 'a).

Like iter but handles non-UTF-8 CHARSXPs gracefully.

pub unsafe fn set_charsxp(self, idx: isize, charsxp: SEXP)

Set a CHARSXP at the given index, protecting it during insertion.

This is the safe way to insert a freshly allocated CHARSXP into a string vector.

Safety

• Must be called from the R main thread
• charsxp must be a valid CHARSXP (from Rf_mkChar* or STRING_ELT)
• self must be a valid, protected STRSXP

Panics

Panics if idx is out of bounds.

pub unsafe fn set_charsxp_unchecked(self, idx: isize, charsxp: SEXP)

Set a CHARSXP without protecting it.

Safety

In addition to the safety requirements of set_charsxp:

• The caller must ensure charsxp is already protected or from the global CHARSXP cache.

pub unsafe fn set_str(self, idx: isize, s: &str)

Set an element from a Rust string.

Creates a CHARSXP from the string and inserts it safely.

Safety

• Must be called from the R main thread
• self must be a valid, protected STRSXP

Panics

Panics if idx is out of bounds.

pub unsafe fn set_na(self, idx: isize)

Set an element to NA_character_.

Safety

• Must be called from the R main thread
• self must be a valid, protected STRSXP

Panics

Panics if idx is out of bounds.

pub unsafe fn set_opt_str(self, idx: isize, s: Option<&str>)

Set an element from an optional string.

None becomes NA_character_.

Safety

• Must be called from the R main thread
• self must be a valid, protected STRSXP

Panics

Panics if idx is out of bounds.

Trait Implementations

impl<'a> Clone for StrVec<'a>

fn clone(&self) -> StrVec<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for StrVec<'a>

impl<'a> Debug for StrVec<'a>

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

Formats the value using the given formatter.

impl<'a> IntoIterator for StrVec<'a>

type Item = Option<&'a str>

The type of the elements being iterated over.

type IntoIter = StrVecIter<'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 StrVec<'_>

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<'a> TrivialClone for StrVec<'a>

impl<'a> TryFromSexp for StrVec<'a>

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.

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: 8 bytes