Struct StrVec 

pub struct StrVec(SEXP);

Owned handle to an R character vector (STRSXP).

This wrapper provides safe methods for building character vectors element-by-element with proper GC protection.

Tuple Fields

0: SEXP

Implementations

impl StrVec

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) whose lifetime remains managed by R.

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<&'static str>

Get the string at the given index (zero-copy).

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<'static, str>>

Get the string at the given index as Cow<str> (encoding-safe).

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 fn iter(self) -> StrVecIter

Iterate over elements as Option<&str>.

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

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

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 Clone for StrVec

fn clone(&self) -> StrVec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StrVec

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

Formats the value using the given formatter.

impl IntoIterator for StrVec

type Item = Option<&'static str>

The type of the elements being iterated over.

type IntoIter = StrVecIter

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 TryFromSexp for StrVec

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.

impl Copy for StrVec