Module convert 

Wrapper helpers to force specific IntoR representations.

This module provides two approaches for controlling how Rust types are converted to R:

1. As* Wrappers (Call-site Control)

Use these wrappers when you want to override the conversion for a single return value:

• AsList<T>: Convert T to an R list via IntoList
• AsExternalPtr<T>: Convert T to an R external pointer
• AsRNative<T>: Convert scalar T to a length-1 R vector

#[miniextendr]
fn get_data() -> AsList<MyStruct> {
    AsList(MyStruct { x: 1, y: 2 })
}

2. Prefer* Derive Macros (Type-level Control)

Use these derives when a type should always use a specific conversion:

• #[derive(IntoList, PreferList)]: Type always converts to R list
• #[derive(ExternalPtr, PreferExternalPtr)]: Type always converts to external pointer
• #[derive(RNativeType, PreferRNativeType)]: Newtype always converts to native R scalar

#[derive(IntoList, PreferList)]
struct Point { x: f64, y: f64 }

#[miniextendr]
fn make_point() -> Point {  // Automatically becomes R list
    Point { x: 1.0, y: 2.0 }
}

3. #[miniextendr(return = "...")] Attribute

Use this when you want to control conversion for a specific #[miniextendr] function without modifying the type itself:

• return = "list": Wrap result in AsList
• return = "externalptr": Wrap result in AsExternalPtr
• return = "native": Wrap result in AsRNative

#[miniextendr(return = "list")]
fn get_as_list() -> MyStruct {
    MyStruct { x: 1 }
}

Choosing the Right Approach

Situation	Recommended Approach
Type should always convert one way	Prefer* derive
Override conversion for one function	As* wrapper or return attribute
Type has multiple valid representations	Don’t use Prefer*; use As* or return

A note on the Collect* adapters (naming-convention boundary)

This module also exposes Collect, CollectStrings, CollectNA, and CollectNAInt. These are representation-forcing IntoR wrappers in the same spirit as the As* family, but they deliberately do not carry the As* prefix. The distinction is structural: the As* wrappers wrap a finished value T and re-route its conversion (AsList<T>, AsExternalPtr<T>, AsRNative<T>), whereas the Collect* wrappers wrap an iterator I: ExactSizeIterator and materialize it directly into a freshly allocated R vector. The As*-of-T shape (“convert this value as a list / pointer / native scalar”) does not describe what these do — Collect names the operation (drain an iterator into an R vector), which is the more accurate verb. This divergence is intentional and tracked; see the conversion control-surface analysis (analysis/conversion-control-surface-2026-06-07.md, §3.4 / §4.5) and issue #871.

Re-exports

pub use crate::dataframe::ColumnSource;

Structs

AsDataFrame

Wrap a value and convert it to an R data.frame via IntoDataFrame when returned.

AsDisplay

Wrap a T: Display and convert it to an R character scalar.

AsDisplayVec

Wrap a Vec<T: Display> and convert it to an R character vector.

AsExternalPtr

Wrap a value and convert it to an R external pointer when returned from Rust.

AsFromStr

Wrap a parsed T: FromStr from an R character scalar.

AsFromStrVec

Wrap a Vec<T: FromStr> parsed from an R character vector.

AsList

Wrap a value and convert it to an R list via IntoList when returned from Rust.

AsNamedList

Wrap a tuple pair collection and convert it to a named R list (VECSXP).

AsNamedVector

Wrap a tuple pair collection and convert it to a named atomic R vector (INTSXP, REALSXP, LGLSXP, RAWSXP, or STRSXP).

AsRNative

Wrap a scalar RNativeType and force native R vector conversion.

Collect

Write an ExactSizeIterator of native R types directly into an R vector.

CollectNA

Write an ExactSizeIterator of Option<T> directly into an R vector with NA support.

CollectNAInt

Write an ExactSizeIterator of Option<i32> directly into an R integer vector with NA.

CollectStrings

Write an ExactSizeIterator of String directly into an R character vector.

Traits

AsDataFrameExt

Extension trait for wrapping values as AsDataFrame.

AsExternalPtrExt

Extension trait for wrapping values as AsExternalPtr.

AsListExt

Extension trait for wrapping values as AsList.

AsNamedListExt

Extension trait for wrapping tuple pair collections as AsNamedList.

AsNamedVectorExt

Extension trait for wrapping tuple pair collections as AsNamedVector.

AsRNativeExt

Extension trait for wrapping values as AsRNative.

Functions

gather_column 👻 ^⚠

Gather the rows at idx (0-based, in order) out of a typed column SEXP into a new dense SEXP of length idx.len(), where out[j] = src[idx[j]].

gather_native 🔒 ^⚠

Gather the rows at idx (0-based, in order) from a contiguous primitive column into a fresh dense vector, where out[j] = src[idx[j]].

named_vector_from_pairs 🔒

Shared helper: build a named atomic vector from an owning iterator of (key, value) pairs.

scatter_column 👻 ^⚠

Scatter a typed column SEXP from a dense inner data frame into a new SEXP of length n_rows, placing NA/NULL at rows not in present_idx.

scatter_native 🔒 ^⚠

Scatter a dense typed column into a fresh SEXP of length n_rows, placing the j-th source value at row present_idx[j] and the per-type NA sentinel (RNativeType::R_NA) at every absent row.