Trait SexpExt 

pub trait SexpExt {
    // Required methods
    fn type_of(&self) -> SEXPTYPE;
    fn is_null_or_nil(&self) -> bool;
    fn len(&self) -> usize;
    fn xlength(&self) -> R_xlen_t;
    unsafe fn len_unchecked(&self) -> usize;
    unsafe fn as_slice<T: RNativeType>(&self) -> &'static [T];
    unsafe fn as_slice_unchecked<T: RNativeType>(&self) -> &'static [T];
    unsafe fn as_mut_slice<T: RNativeType>(&self) -> &'static mut [T];
    fn is_integer(&self) -> bool;
    fn is_real(&self) -> bool;
    fn is_logical(&self) -> bool;
    fn is_character(&self) -> bool;
    fn is_raw(&self) -> bool;
    fn is_complex(&self) -> bool;
    fn is_list(&self) -> bool;
    fn is_external_ptr(&self) -> bool;
    fn is_environment(&self) -> bool;
    fn is_symbol(&self) -> bool;
    fn is_language(&self) -> bool;
    fn is_altrep(&self) -> bool;
    fn is_empty(&self) -> bool;
    fn is_nil(&self) -> bool;
    fn is_factor(&self) -> bool;
    fn is_pair_list(&self) -> bool;
    fn is_matrix(&self) -> bool;
    fn is_array(&self) -> bool;
    fn is_function(&self) -> bool;
    fn is_s4(&self) -> bool;
    fn is_data_frame(&self) -> bool;
    fn is_numeric(&self) -> bool;
    fn is_number(&self) -> bool;
    fn is_vector_atomic(&self) -> bool;
    fn is_vector_list(&self) -> bool;
    fn is_vector(&self) -> bool;
    fn is_object(&self) -> bool;
    fn coerce(&self, target: SEXPTYPE) -> SEXP;
    fn as_logical(&self) -> Option<bool>;
    fn as_integer(&self) -> Option<i32>;
    fn as_real(&self) -> Option<f64>;
    fn as_char(&self) -> SEXP;
    fn get_attr(&self, name: SEXP) -> SEXP;
    fn set_attr(&self, name: SEXP, val: SEXP);
    fn get_names(&self) -> SEXP;
    fn set_names(&self, names: SEXP);
    fn get_class(&self) -> SEXP;
    fn set_class(&self, class: SEXP);
    fn get_dim(&self) -> SEXP;
    fn set_dim(&self, dim: SEXP);
    fn get_dimnames(&self) -> SEXP;
    fn set_dimnames(&self, dimnames: SEXP);
    fn get_levels(&self) -> SEXP;
    fn set_levels(&self, levels: SEXP);
    fn get_row_names(&self) -> SEXP;
    fn set_row_names(&self, row_names: SEXP);
    fn inherits_class(&self, class: &CStr) -> bool;
    fn string_elt(&self, i: isize) -> SEXP;
    fn string_elt_str(&self, i: isize) -> Option<&str>;
    fn set_string_elt(&self, i: isize, charsxp: SEXP);
    fn is_na_string(&self) -> bool;
    fn vector_elt(&self, i: isize) -> SEXP;
    fn set_vector_elt(&self, i: isize, val: SEXP);
    fn integer_elt(&self, i: isize) -> i32;
    fn real_elt(&self, i: isize) -> f64;
    fn logical_elt(&self, i: isize) -> i32;
    fn complex_elt(&self, i: isize) -> Rcomplex;
    fn raw_elt(&self, i: isize) -> u8;
    fn set_integer_elt(&self, i: isize, v: i32);
    fn set_real_elt(&self, i: isize, v: f64);
    fn set_logical_elt(&self, i: isize, v: i32);
    fn set_complex_elt(&self, i: isize, v: Rcomplex);
    fn set_raw_elt(&self, i: isize, v: u8);
    fn printname(&self) -> SEXP;
    fn r_char(&self) -> *const c_char;
    fn r_char_str(&self) -> Option<&str>;
    fn resize(&self, newlen: R_xlen_t) -> SEXP;
    fn duplicate(&self) -> SEXP;
    fn shallow_duplicate(&self) -> SEXP;
    unsafe fn string_elt_unchecked(&self, i: isize) -> SEXP;
    unsafe fn set_string_elt_unchecked(&self, i: isize, charsxp: SEXP);
    unsafe fn vector_elt_unchecked(&self, i: isize) -> SEXP;
    unsafe fn set_vector_elt_unchecked(&self, i: isize, val: SEXP);
    unsafe fn get_attr_unchecked(&self, name: SEXP) -> SEXP;
    unsafe fn set_attr_unchecked(&self, name: SEXP, val: SEXP);
    unsafe fn r_char_unchecked(&self) -> *const c_char;

    // Provided method
    fn get_attr_opt(&self, name: SEXP) -> Option<SEXP> { ... }
}

Extension trait for SEXP providing safe(r) accessors and type checking.

This trait provides idiomatic Rust methods for working with SEXPs, equivalent to R’s inline macros and type checking functions.

Required Methods

fn type_of(&self) -> SEXPTYPE

Get the type of this SEXP.

Equivalent to TYPEOF(x) macro.

Safety

The SEXP must be valid (not null and not freed).

fn is_null_or_nil(&self) -> bool

Check if this SEXP is null or R_NilValue.

fn len(&self) -> usize

Get the length of this SEXP as usize.

Safety

The SEXP must be valid.

fn xlength(&self) -> R_xlen_t

Get the length as R_xlen_t.

Safety

The SEXP must be valid.

unsafe fn len_unchecked(&self) -> usize

Get the length without thread checks.

Safety

Must be called from R’s main thread. No debug assertions.

unsafe fn as_slice<T: RNativeType>(&self) -> &'static [T]

Get a slice view of this SEXP’s data.

Safety

• The SEXP must be valid and of the correct type for T
• The SEXP must be protected from R’s garbage collector for the entire duration the returned slice is used. This typically means the SEXP must be either:
  • An argument to a .Call function (protected by R’s calling convention)
  • Explicitly protected via PROTECT/UNPROTECT or R_PreserveObject
  • Part of a protected container (e.g., element of a protected list)
• The returned slice has 'static lifetime for API convenience, but this is a lie - the actual lifetime is tied to the SEXP’s protection status. Holding the slice after the SEXP is unprotected is undefined behavior.

unsafe fn as_slice_unchecked<T: RNativeType>(&self) -> &'static [T]

Get a slice view without thread checks.

Safety

• All safety requirements of as_slice apply
• Additionally, must be called from R’s main thread (no debug assertions)

unsafe fn as_mut_slice<T: RNativeType>(&self) -> &'static mut [T]

Get a mutable slice view of this SEXP’s data.

Safety

• All safety requirements of as_slice apply.
• The caller must ensure exclusive access: no other &[T] or &mut [T] slices derived from this SEXP may exist simultaneously. Multiple calls to as_mut_slice on the same SEXP without dropping the previous slice is UB.
• The SEXP must not be shared (ALTREP or NAMED > 0 objects may alias).

fn is_integer(&self) -> bool

Check if this SEXP is an integer vector (INTSXP).

fn is_real(&self) -> bool

Check if this SEXP is a real/numeric vector (REALSXP).

fn is_logical(&self) -> bool

Check if this SEXP is a logical vector (LGLSXP).

fn is_character(&self) -> bool

Check if this SEXP is a character/string vector (STRSXP).

fn is_raw(&self) -> bool

Check if this SEXP is a raw vector (RAWSXP).

fn is_complex(&self) -> bool

Check if this SEXP is a complex vector (CPLXSXP).

fn is_list(&self) -> bool

Check if this SEXP is a list/generic vector (VECSXP).

fn is_external_ptr(&self) -> bool

Check if this SEXP is an external pointer (EXTPTRSXP).

fn is_environment(&self) -> bool

Check if this SEXP is an environment (ENVSXP).

fn is_symbol(&self) -> bool

Check if this SEXP is a symbol (SYMSXP).

fn is_language(&self) -> bool

Check if this SEXP is a language object (LANGSXP).

fn is_altrep(&self) -> bool

Check if this SEXP is an ALTREP object.

Equivalent to R’s ALTREP(x) macro.

fn is_empty(&self) -> bool

Check if this SEXP contains any elements.

fn is_nil(&self) -> bool

Check if this SEXP is R’s NULL (NILSXP).

fn is_factor(&self) -> bool

Check if this SEXP is a factor.

Equivalent to R’s Rf_isFactor(x).

fn is_pair_list(&self) -> bool

Check if this SEXP is a pairlist (LISTSXP or NILSXP).

Equivalent to R’s Rf_isList(x).

fn is_matrix(&self) -> bool

Check if this SEXP is a matrix.

Equivalent to R’s Rf_isMatrix(x).

fn is_array(&self) -> bool

Check if this SEXP is an array.

Equivalent to R’s Rf_isArray(x).

fn is_function(&self) -> bool

Check if this SEXP is a function (closure, builtin, or special).

Equivalent to R’s Rf_isFunction(x).

fn is_s4(&self) -> bool

Check if this SEXP is an S4 object.

Equivalent to R’s Rf_isS4(x).

fn is_data_frame(&self) -> bool

Check if this SEXP is a data.frame.

Equivalent to R’s Rf_isDataFrame(x).

fn is_numeric(&self) -> bool

Check if this SEXP is a numeric type (integer, logical, or real, excluding factors).

Equivalent to R’s Rf_isNumeric(x).

fn is_number(&self) -> bool

Check if this SEXP is a number type (numeric or complex).

Equivalent to R’s Rf_isNumber(x).

fn is_vector_atomic(&self) -> bool

Check if this SEXP is an atomic vector.

Returns true for logical, integer, real, complex, character, and raw vectors.

fn is_vector_list(&self) -> bool

Check if this SEXP is a vector list (VECSXP or EXPRSXP).

fn is_vector(&self) -> bool

Check if this SEXP is a vector (atomic vector or list).

fn is_object(&self) -> bool

Check if this SEXP is an R “object” (has a class attribute).

fn coerce(&self, target: SEXPTYPE) -> SEXP

Coerce this SEXP to the given type, returning a new SEXP.

The result is guaranteed to have the requested SEXPTYPE. Equivalent to R’s Rf_coerceVector(x, target).

fn as_logical(&self) -> Option<bool>

Extract a scalar logical value.

Returns None for NA. Coerces non-logical inputs. Equivalent to R’s Rf_asLogical(x).

fn as_integer(&self) -> Option<i32>

Extract a scalar integer value.

Returns None for NA_integer_. Coerces non-integer inputs. Equivalent to R’s Rf_asInteger(x).

fn as_real(&self) -> Option<f64>

Extract a scalar real value.

Returns None for NA_real_ (NaN). Coerces non-real inputs. Equivalent to R’s Rf_asReal(x).

fn as_char(&self) -> SEXP

Extract a scalar CHARSXP from this SEXP.

The result is guaranteed to be a CHARSXP. Equivalent to R’s Rf_asChar(x).

fn get_attr(&self, name: SEXP) -> SEXP

Get an attribute by symbol.

fn set_attr(&self, name: SEXP, val: SEXP)

Set an attribute by symbol.

fn get_names(&self) -> SEXP

Get the names attribute.

fn set_names(&self, names: SEXP)

Set the names attribute.

fn get_class(&self) -> SEXP

Get the class attribute.

fn set_class(&self, class: SEXP)

Set the class attribute.

fn get_dim(&self) -> SEXP

Get the dim attribute.

fn set_dim(&self, dim: SEXP)

Set the dim attribute.

fn get_dimnames(&self) -> SEXP

Get the dimnames attribute.

fn set_dimnames(&self, dimnames: SEXP)

Set the dimnames attribute.

fn get_levels(&self) -> SEXP

Get the levels attribute (factors).

fn set_levels(&self, levels: SEXP)

Set the levels attribute (factors).

fn get_row_names(&self) -> SEXP

Get the row.names attribute.

fn set_row_names(&self, row_names: SEXP)

Set the row.names attribute.

fn inherits_class(&self, class: &CStr) -> bool

Check if this SEXP inherits from a class.

Equivalent to R’s inherits(x, "class_name").

fn string_elt(&self, i: isize) -> SEXP

Get the i-th CHARSXP element from a STRSXP.

Equivalent to R’s STRING_ELT(x, i).

fn string_elt_str(&self, i: isize) -> Option<&str>

Get the i-th string element as Option<&str>.

Returns None for NA_character_. The returned &str borrows from R’s internal string cache (CHARSXP global pool) and is valid as long as the parent STRSXP is protected from GC. The lifetime is tied to &self by the borrow checker, but the true validity depends on GC protection — do not hold the &str across allocation boundaries without ensuring the SEXP remains protected.

fn set_string_elt(&self, i: isize, charsxp: SEXP)

Set the i-th CHARSXP element of a STRSXP.

Equivalent to R’s SET_STRING_ELT(x, i, v).

fn is_na_string(&self) -> bool

Check if this CHARSXP is NA_character_.

fn vector_elt(&self, i: isize) -> SEXP

Get the i-th element of a VECSXP (generic vector / list).

Equivalent to R’s VECTOR_ELT(x, i).

fn set_vector_elt(&self, i: isize, val: SEXP)

Set the i-th element of a VECSXP.

Equivalent to R’s SET_VECTOR_ELT(x, i, v).

fn integer_elt(&self, i: isize) -> i32

Get the i-th integer element.

fn real_elt(&self, i: isize) -> f64

Get the i-th real element.

fn logical_elt(&self, i: isize) -> i32

Get the i-th logical element (raw i32: 0/1/NA_LOGICAL).

fn complex_elt(&self, i: isize) -> Rcomplex

Get the i-th complex element.

fn raw_elt(&self, i: isize) -> u8

Get the i-th raw element.

fn set_integer_elt(&self, i: isize, v: i32)

Set the i-th integer element.

fn set_real_elt(&self, i: isize, v: f64)

Set the i-th real element.

fn set_logical_elt(&self, i: isize, v: i32)

Set the i-th logical element (raw i32: 0/1/NA_LOGICAL).

fn set_complex_elt(&self, i: isize, v: Rcomplex)

Set the i-th complex element.

fn set_raw_elt(&self, i: isize, v: u8)

Set the i-th raw element.

fn printname(&self) -> SEXP

Get the print name (CHARSXP) of a symbol (SYMSXP).

Safety

The SEXP must be a valid SYMSXP.

fn r_char(&self) -> *const c_char

Get the C string pointer from a CHARSXP.

The returned pointer is valid as long as the CHARSXP is protected.

Safety

The SEXP must be a valid CHARSXP.

fn r_char_str(&self) -> Option<&str>

Get a &str from a CHARSXP. Returns None for NA_character_.

fn resize(&self, newlen: R_xlen_t) -> SEXP

Resize a vector to a new length, returning a (possibly new) SEXP.

If the new length is shorter, elements are truncated. If longer, new elements are filled with NA/NULL. Equivalent to R’s Rf_xlengthgets(x, newlen).

fn duplicate(&self) -> SEXP

Deep-copy this SEXP. Equivalent to R’s Rf_duplicate(x).

fn shallow_duplicate(&self) -> SEXP

Shallow-copy this SEXP. Equivalent to R’s Rf_shallow_duplicate(x).

unsafe fn string_elt_unchecked(&self, i: isize) -> SEXP

Get the i-th CHARSXP from a STRSXP. No thread check.

Safety

Must be called from R’s main thread.

unsafe fn set_string_elt_unchecked(&self, i: isize, charsxp: SEXP)

Set the i-th CHARSXP of a STRSXP. No thread check.

Safety

Must be called from R’s main thread.

unsafe fn vector_elt_unchecked(&self, i: isize) -> SEXP

Get the i-th element of a VECSXP. No thread check.

Safety

Must be called from R’s main thread.

unsafe fn set_vector_elt_unchecked(&self, i: isize, val: SEXP)

Set the i-th element of a VECSXP. No thread check.

Safety

Must be called from R’s main thread.

unsafe fn get_attr_unchecked(&self, name: SEXP) -> SEXP

Get an attribute by symbol. No thread check.

Safety

Must be called from R’s main thread.

unsafe fn set_attr_unchecked(&self, name: SEXP, val: SEXP)

Set an attribute by symbol. No thread check.

Safety

Must be called from R’s main thread.

unsafe fn r_char_unchecked(&self) -> *const c_char

Get C string pointer from a CHARSXP. No thread check.

Safety

Must be called from R’s main thread. The SEXP must be a valid CHARSXP.

Provided Methods

fn get_attr_opt(&self, name: SEXP) -> Option<SEXP>

Get an attribute by symbol, returning None for R_NilValue.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl SexpExt for SEXP