Skip to main content

Module into_r

miniextendr_api

Module into_r 

Source
Expand description

Conversions from Rust types to R SEXP.

This module provides the IntoR trait for converting Rust values to R SEXPs.

§Submodules

ModuleContents
large_integersi64, u64, isize, usize → REALSXP, plus string/bool/Option scalars
collectionsHashMap, BTreeMap, HashSet, BTreeSet → named/unnamed lists
resultResult<T, E> → list with ok/err fields
altrepAltrep<T> marker type, Lazy<T> alias, IntoRAltrep trait

§Choosing the right outbound conversion

IntoR is the lax outbound path — it silently widens 64-bit integers to R’s REALSXP when the value doesn’t fit INTSXP. The strict alternative lives in crate::strict and is opted into via #[miniextendr(strict)], which routes through crate::strict::checked_into_sexp_i64 and friends. Failure mode of staying on the default lax path when you care about exact representation: an i64 value just above i32::MAX lands in R as an inexact f64 (and IDs/counters larger than 2^53 start colliding).

For storage-directed conversions (e.g. force Vec<i64> into INTSXP when values fit), reach for crate::into_r_as::IntoRAs instead.

The inbound counterpart is crate::from_r::TryFromSexp (strict by construction — returns Result); the inbound looser path is crate::coerce::Coerce / crate::coerce::TryCoerce. There is intentionally no TryFromSexpStrict trait.

§Thread Safety

The trait provides two methods:

Use into_sexp_unchecked when you’re certain you’re on the main thread:

  • Inside ALTREP callbacks
  • Inside standalone #[miniextendr] functions (they run on the main thread)
  • Inside extern "C-unwind" functions called directly by R

§The absence contract: what None becomes in R

None does not map to one universal R value — it depends on the shape of T in Option<T>:

  • Owned scalars (Option<i32>, Option<f64>, Option<bool>, Option<String>, and friends in large_integers) → the matching NA_<type>_. R has a native NA sentinel for each of these.
  • Option<&T> where T: Copy (e.g. Option<&i32>) → NULL. A reference has nothing to copy on None, so there is no NA to produce. See the impl doc on Option<&T> in large_integers.
  • Option<&str> is the one exception to the previous rule: it returns NA_character_, matching Option<String>, because str is unsized and can’t use the generic Copy-bounded blanket impl — it has its own hand-written impl instead.
  • Containers (Option<Vec<T>>, Option<HashMap<..>>, Option<HashSet<..>>, Option<BTreeMap<..>>, Option<BTreeSet<..>>) → NULL. No container type has a native R NA sentinel either.

Changing a return type from Option<i32> to Option<&i32> or Option<Vec<i32>> therefore silently flips the R-visible absence value from NA_integer_ to NULL, with no compiler warning. See result for the analogous (and differently-shaped) contract on Result::Err.

Re-exports§

pub use altrep::*;
pub use result::*;

Modules§

altrep 🔒
ALTREP marker type (Altrep<T> / Lazy<T>).
collections 🔒
Collection conversions (HashMap, BTreeMap, HashSet, BTreeSet) to R.
large_integers 🔒
Large integer types → REALSXP (f64).
result 🔒
Result<T, E> conversions to R.

Macros§

impl_into_r_vec_native 🔒
impl_into_r_via_coerce 🔒
Macro for infallible widening IntoR via Coerce.
impl_lossy_string_into_r 🔒
Generate IntoR impls for types with to_string_lossy() (owned scalar, ref scalar, Option, Vec, Vec<Option>). Used for PathBuf/&Path and OsString/&OsStr.
impl_option_collection_into_r 🔒
impl_scalar_into_r 🔒
Macro for scalar IntoR via SEXP::scalar_* methods.
impl_set_coerce_into_r 🔒
Macro for HashSet<T>/BTreeSet<T> where T coerces to i32 (R’s native integer type).
impl_tuple_into_r 🔒
Macro to implement IntoR for tuples of various sizes. Converts Rust tuples to unnamed R lists (VECSXP).
impl_vec_coerce_into_r 🔒
Macro for Vec<T> where T coerces to a native R type.
impl_vec_map_into_r 🔒
impl_vec_option_coerce_into_r 🔒
Macro for Vec<Option<T>> where T coerces to a type with existing Option impl.
impl_vec_option_into_r 🔒
Macro for NA-aware Vec<Option<T>> → R vector conversions.
impl_vec_option_logical_into_r 🔒
impl_vec_option_smart_i64_into_r 🔒
Macro for NA-aware Vec<Option<T>> → R smart vector conversion. Checks if all non-None values fit i32 → INTSXP, otherwise REALSXP.
impl_vec_smart_i64_into_r 🔒
into_r_infallible 🔒
Generate an infallible IntoR impl whose only real method is into_sexp.

Traits§

IntoR
Trait for converting Rust types to R SEXP values.
IntoRAltrep
Extension trait for ALTREP conversions.

Functions§

alloc_r_vector 🔒 ⚠
Allocate an R vector of type T with n elements and return (SEXP, &mut [T]).
alloc_r_vector_unchecked 🔒 ⚠
Allocate an R vector (unchecked FFI variant).
logical_iter_to_lglsxp 🔒
Helper: allocate LGLSXP and fill from an i32 iterator (checked).
logical_iter_to_lglsxp_unchecked 🔒 ⚠
Helper: allocate LGLSXP and fill from an i32 iterator (unchecked).
opt_str_iter_to_strsxp 🔒
Helper: allocate STRSXP and fill from an optional-string iterator (checked).
opt_str_iter_to_strsxp_unchecked 🔒 ⚠
Helper: allocate STRSXP and fill from an optional-string iterator (unchecked).
str_iter_to_strsxp 🔒
Helper: allocate STRSXP and fill from a string iterator (checked).
str_iter_to_strsxp_unchecked 🔒 ⚠
Helper: allocate STRSXP and fill from a string iterator (unchecked).
vec_of_into_r_to_list 🔒
Helper: convert a Vec of IntoR items to an R list (VECSXP).
vec_of_maps_to_list 🔒
Helper to convert a Vec of map-like types to an R list of named lists.
vec_option_of_into_r_to_list 🔒
Helper: convert Vec<Option<C: IntoR>> to a VECSXP, with None mapping to R_NilValue (NULL) and Some(v) mapping to whatever v.into_sexp() produces.
vec_to_sexp 🔒 ⚠
Convert a slice to an R vector (checked) using copy_from_slice.
vec_to_sexp_unchecked 🔒 ⚠
Convert a slice to an R vector (unchecked) using copy_from_slice.
vecsxp_from_iter 🔒 ⚠
Build a VECSXP from an exact-size iterator of child SEXPs (checked).
vecsxp_from_iter_unchecked 🔒 ⚠
_unchecked twin of vecsxp_from_iter — uses ListBuilder::set_unchecked. For ALTREP / with_r_thread / unwind contexts. The caller’s adaptor must produce children via into_sexp_unchecked().