Struct StrVec 

pub struct StrVec<'a>(SEXP, Option<&'a ChildRoots>);

Borrowed view over an R character vector (STRSXP).

Strings returned by the view carry 'a. Constructors must tie that lifetime to a root that keeps the source reachable. ProtectedStrVec::as_strvec does so through a borrow of its owner.

try_from_root borrows a lifetime-carrying root. Generated wrappers use this path for StrVec<'_> parameters. Raw TryFromSexp is unavailable: a copyable SEXP cannot constrain the view’s lifetime. Use ProtectedStrVec when the result must own its root.

Copy and cheap (a SEXP and a retention reference); covariant in 'a. Uncached ALTREP elements read through a rooted view stay alive for 'a.

Tuple Fields

0: SEXP

1: Option<&'a ChildRoots>

Implementations

impl<'a> StrVec<'a>

#[doc(hidden)]

pub const NATIVE_BORROW: Option<NativeBorrow> = None

Strings do not retain a pointer to a native numeric vector.

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. An ALTREP class must also retain every CHARSXP read through this raw view for 'a; otherwise use try_from_root or ProtectedStrVec.

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; the CHARSXP must remain reachable. For an uncached ALTREP element, retain this view’s protection scope or ProtectedStrVec owner as well as the source vector.

Safety

The caller must keep the returned CHARSXP reachable for as long as the reference is used. Rooting an ordinary source STRSXP suffices; an ALTREP source may need this view’s scope/owner or a separate root for the child. Letting R collect that child 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.

impl<'a> StrVec<'a>

pub fn try_from_root(root: Root<'a>) -> Result<Self, SexpError>

Borrow a character vector for the lifetime of its root.

The result cannot acquire a lifetime longer than the supplied root. Raw TryFromSexp is intentionally unavailable for this borrowed view.

use miniextendr_api::{Root, StrVec};
fn escape<'a>(root: Root<'a>) -> StrVec<'static> {
    StrVec::try_from_root(root).unwrap()
}

Trait Implementations

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

fn clone(&self) -> Self

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 Debug for StrVec<'_>

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

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

type Error = SexpError

The error reported when the R representation is not accepted.

fn try_from_root(root: Root<'a>) -> Result<Self, Self::Error>

Convert without allowing an R-backed borrow to outlive root.

#[doc(hidden)]

const NATIVE_BORROW: Option<NativeBorrow> = None

Native storage borrowed by this conversion, for wrapper alias 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: 16 bytes