pub struct RustConversionBuilder {Show 14 fields
inferred_types: bool,
coerce_all: bool,
coerce_params: Vec<String>,
convert_params: Vec<String>,
strict: bool,
match_arg_several_ok_params: Vec<String>,
layered_choice_params: Vec<(String, ChoiceLeaf)>,
no_na_params: Vec<(String, Option<String>)>,
param_markers: Vec<(String, Vec<ParamMarker>)>,
conversion_error_class: Vec<String>,
unevaluated_args: bool,
self_type: Option<Type>,
formals: Formals,
prepared_params: Vec<String>,
}Expand description
Builder for generating Rust conversion statements from R SEXP parameters.
Handles:
- Unit types
()→ identity binding &Dots→ special wrapper with storage- Slices
&[T]→ TryFromSexp &str→ a borrow of R’s CHARSXP (TryFromRoot)- Scalar references → DATAPTR_RO_unchecked
- Coercion → multi-source numeric conversion (incl. widened native
i32/f64) or logical/integer bool conversion - Default → TryFromSexp
Fields§
§inferred_types: boolInfer copied trait signature types from a concrete method item.
coerce_all: boolEnable coercion for all parameters
coerce_params: Vec<String>Parameter names that should use coercion
convert_params: Vec<String>§strict: boolEnable strict input conversion for lossy types
match_arg_several_ok_params: Vec<String>Parameter names with match_arg + several_ok — use match_arg_vec_from_sexp instead of TryFromSexp.
layered_choice_params: Vec<(String, ChoiceLeaf)>Choice parameters whose type wraps the choice in Missing / Option
layers (#1473, #1551), with the kind of their innermost value. Decoded
by layered_choice_expr instead of TryFromSexp.
no_na_params: Vec<(String, Option<String>)>no_na parameters (Rust name) with the author’s no_na(message = ..),
if any: their converted value is checked right after the conversion
(see Self::with_no_na).
param_markers: Vec<(String, Vec<ParamMarker>)>Parameters (Rust name) declared with parameter markers
(Checked<T> / Unchecked<T>, #1566), outermost first: the inner
type converts, then the value is wrapped (see
Self::with_param_markers).
conversion_error_class: Vec<String>The crate’s conversion_error_class ([package.metadata.miniextendr]),
appended to every conversion condition’s class vector.
unevaluated_args: boolWhether Quoted / Quosure parameters are bound (a standalone fn,
whose R wrapper passes them unevaluated, #1835). Elsewhere they are a
compile error.
self_type: Option<Type>The impl’s type, for Self in a method’s borrowed external argument
(other: &Self): the wrapper is a free function.
formals: FormalsThe R formal of each parameter (#1842): what a conversion condition
names the argument (see Self::with_formals).
prepared_params: Vec<String>Parameters (Rust name) whose alias check declared a prepared state
(#1504, see Self::preparation): their conversion reads it.
Implementations§
Source§impl RustConversionBuilder
impl RustConversionBuilder
Sourcepub fn new() -> Self
pub fn new() -> Self
Create a new conversion builder, carrying the crate-level
conversion_error_class from the manifest (empty when unset).
Sourcepub(crate) fn with_prepared_param(self, param_name: String) -> Self
pub(crate) fn with_prepared_param(self, param_name: String) -> Self
Convert param_name (its Rust name) from the prepared state its
alias check left (#1504): the check declared the binding
prepared_binding names, from Self::preparation.
Sourcefn converts_plainly(&self, pat_type: &PatType) -> bool
fn converts_plainly(&self, pat_type: &PatType) -> bool
Whether pat_type converts through the plain TryFromSexp arm (or a
copied trait signature’s witness): the arm Self::conversion_stmts
falls back to, after every special conversion. Only that conversion
can be prepared. Erring towards false only loses the exact arm of an
Either (the check then takes both arms).
Sourcepub(crate) fn preparation(
&self,
pat_type: &PatType,
sexp_ident: &Ident,
) -> Option<Preparation>
pub(crate) fn preparation( &self, pat_type: &PatType, sexp_ident: &Ident, ) -> Option<Preparation>
The Preparation of an argument for the second pass of the alias
check (#1504), through TryFromSexp::__mx_prepare. None unless the
argument converts through the plain TryFromSexp arm.
The check prepares an argument only when the first pass marks it: its
metadata is an Either at the top level (NativeBorrow::selects, a
constant, so every other argument’s preparation optimises out), and
its arms meet another argument.
pub(crate) fn with_inferred_types(self) -> Self
Sourcepub fn with_self_type(self, self_type: Type) -> Self
pub fn with_self_type(self, self_type: Type) -> Self
Name the impl’s type for Self in borrowed external arguments.
Sourcefn external_arg(&self, pat_type: &PatType) -> Option<ExternalArg>
fn external_arg(&self, pat_type: &PatType) -> Option<ExternalArg>
The borrowed external argument (&T / &mut T / a view, #2106)
pat_type declares. A parameter marker’s parameter is none: the
marker rebinds the converted value, which a borrowed argument only
gets after every conversion.
Sourcepub fn with_unevaluated_args(self) -> Self
pub fn with_unevaluated_args(self) -> Self
Bind Quoted / Quosure parameters (#1835): set for standalone fns,
whose R wrapper passes those arguments unevaluated
(r_wrapper_builder::RArgumentBuilder::build_call_args_vec). Without
it such a parameter is a compile error.
Sourcepub fn with_coerce_all(self) -> Self
pub fn with_coerce_all(self) -> Self
Enable coercion for all parameters.
Sourcepub fn with_coerce_param(self, param_name: String) -> Self
pub fn with_coerce_param(self, param_name: String) -> Self
Add a single parameter name that should use coercion.
param_name is matched against the identifier in the function signature.
Can be called multiple times to add several parameters.
Sourcepub fn with_strict(self) -> Self
pub fn with_strict(self) -> Self
Enable strict input conversion for lossy types (i64/u64/isize/usize + Vec variants).
Sourcepub fn with_match_arg_several_ok(self, param_name: String) -> Self
pub fn with_match_arg_several_ok(self, param_name: String) -> Self
Mark a parameter as match_arg + several_ok — uses match_arg_vec_from_sexp
instead of TryFromSexp for converting STRSXP → Vec<EnumType>.
Sourcepub fn with_layered_choice(self, param_name: String, leaf: ChoiceLeaf) -> Self
pub fn with_layered_choice(self, param_name: String, leaf: ChoiceLeaf) -> Self
Mark a choice parameter whose type wraps the choice in Missing /
Option layers (#1473, #1551): it is decoded layer by layer with the
miniextendr_api::match_arg_* helpers (see layered_choice_expr)
instead of TryFromSexp. There is no TryFromSexp for Option<T> a
downstream crate could provide for its own enum (orphan rule), and a
T: MatchArg blanket would collide with the newtype blanket in
miniextendr_api::newtype, so the wrapper calls the helpers directly.
Sourcepub fn with_no_na(self, param_name: String, message: Option<String>) -> Self
pub fn with_no_na(self, param_name: String, message: Option<String>) -> Self
Mark a #[miniextendr(no_na)] parameter (param_name is its Rust
name), with the author’s no_na(message = "...") if given.
The R guard !anyNA(x) runs first; a type can still read an input as
missing that anyNA() does not see (the reading markers AsNumeric* /
AsCharacter* read the text "NA" or a blank string as NA). So when
the parameter converts through plain TryFromSexp, the converted value
is asked TryFromSexp::__mx_has_na right after its binding, and a
refusal returns the R guard’s own condition (see
no_na_value_stmt). No type is named: Rust resolves the call on the
value’s real type, so aliases and derived newtypes of a marker are
checked too, and for any other type the default false optimises out.
The reference arms (&T, &[T], &str) emit no check and keep only
the R guard: they convert through the reference type’s own impl, and
no reading marker converts by reference. A parameter that coerce
converts through its mapping is checked on its argument SEXP before
the conversion instead (see non_na_check).
An Either parameter (also under Missing) has no R guard
(r_preconditions::no_na_checked_after_conversion). Its value is asked
TryFromSexp::__mx_input_has_na with the input SEXP instead: the arm
the value converted to makes the guard’s anyNA() check on the input
in Rust, then its own __mx_has_na, and a DataFrame arm refuses
nothing (also behind a derived newtype or Result<_, ()>, which
forward the call).
Sourcepub fn with_formals(self, formals: Formals) -> Self
pub fn with_formals(self, formals: Formals) -> Self
Name each argument by its R formal (#1842) in its conversion
condition: the message’s '<p>' and e$param. Without a declared
formal, the Rust name without leading underscores.
Sourcepub fn with_param_markers(
self,
param_name: String,
markers: Vec<ParamMarker>,
) -> Self
pub fn with_param_markers( self, param_name: String, markers: Vec<ParamMarker>, ) -> Self
Mark a parameter (param_name is its Rust name) whose declared type
wraps the one it converts as in parameter markers (Checked<T> /
Unchecked<T>, #1566), outermost first. The pat_type this builder
sees holds the inner type, so the conversion and its failure context
(e$rust_type) are the inner type’s; after the parameter’s last
statement (the conversion or its no_na check) the value is rebound
through each marker’s from_inner, innermost first, so the call
receives the declared type.
Sourcefn marker_rebind(&self, pat_type: &PatType) -> Option<TokenStream>
fn marker_rebind(&self, pat_type: &PatType) -> Option<TokenStream>
The rebinding of a marked parameter’s converted value (see
Self::with_param_markers), or None for an unmarked parameter.
Sourcefn non_na_check(
&self,
pat_type: &PatType,
sexp_ident: &Ident,
) -> Option<TokenStream>
fn non_na_check( &self, pat_type: &PatType, sexp_ident: &Ident, ) -> Option<TokenStream>
The check of the argument SEXP sexp_ident before its conversion: the
no_na R guard’s anyNA() again, in Rust (from_r::__mx_any_na). It
raises the guard’s condition, as the post-conversion no_na check
does (no_na_value_stmt), and covers a .Call() that skips the R
wrapper. Emitted for
- a
NonNa<T>parameter, so the marker’s value holds noNAon every conversion arm (borrowed included); - a
no_naparameter thatcoerceconverts through its mapping (#2274): that arm has no post-conversion check, and itsOption/Vec<Option<_>>forms read anNAasNonewithout an error.
None for any other parameter.
Sourcepub fn with_convert_param(self, param_name: String) -> Self
pub fn with_convert_param(self, param_name: String) -> Self
Select the reference’s conversion, including its native-borrow metadata.
fn explicit_conversion(&self, pat_type: &PatType) -> bool
Sourcefn should_coerce(&self, param_name: &str) -> bool
fn should_coerce(&self, param_name: &str) -> bool
Returns true if coerce_all is set or param_name appears in the per-parameter list.
Sourcepub(crate) fn native_borrow_metadata(
&self,
pat_type: &PatType,
sexp_ident: &Ident,
) -> Option<TokenStream>
pub(crate) fn native_borrow_metadata( &self, pat_type: &PatType, sexp_ident: &Ident, ) -> Option<TokenStream>
Describe only the conversion actually used for this argument.
Special paths can have no TryFromSexp impl for the declared type. Omit their metadata queries at codegen time; a runtime branch still typechecks.
fn borrow_metadata_for( &self, ty: &Type, name: &Ident, rooted: bool, ) -> TokenStream
Sourcefn unevaluated_binding(
&self,
ident: &Ident,
sexp_ident: &Ident,
r_name: &str,
ty: &Type,
param: UnevaluatedParam,
) -> TokenStream
fn unevaluated_binding( &self, ident: &Ident, sexp_ident: &Ident, r_name: &str, ty: &Type, param: UnevaluatedParam, ) -> TokenStream
The binding of a Quoted / Quosure parameter (#1835) from the
argument its R wrapper passed: the capture, or the missing-argument
sentinel. Missing<..> reads the sentinel as Missing::Absent; a bare
marker returns R’s own error for a missing argument as a conversion
condition naming the parameter (e$param). The marker borrows the
argument SEXP (rooted by .Call() for the call), so it cannot outlive
the call.
Sourcefn conversion_stmt(
&self,
try_expr: TokenStream,
ctx: &ArgContext,
ident: &Ident,
ty: &Type,
span: Span,
) -> TokenStream
fn conversion_stmt( &self, try_expr: TokenStream, ctx: &ArgContext, ident: &Ident, ty: &Type, span: Span, ) -> TokenStream
Generate a conversion expression that returns a tagged condition SEXP on failure.
The R wrapper inspects .val and raises a structured rust_* condition; the
return happens from inside the C wrapper body before any further conversion.
try_expr: TheResult<T, E>-producing expressionctx: The argument’s R-facing failure context (ArgContext): the message prefix,e$paramande$rust_typeident: The binding name for the converted valuety: The target Rust type (for theletbinding). The annotation is load-bearing: theErrarm probes the error type by method call (conversion_err_arm), which needs that type known at that point.span: Source span for error reporting
Sourcepub fn build_conversion(
&self,
pat_type: &PatType,
sexp_ident: &Ident,
) -> Vec<TokenStream>
pub fn build_conversion( &self, pat_type: &PatType, sexp_ident: &Ident, ) -> Vec<TokenStream>
Generate conversion statements for a single parameter.
pat_type: the typed pattern from the function signature (e.g.,x: i32).sexp_ident: the identifier of the raw SEXP variable holding the R argument.
Returns a flat list of let binding statements that convert sexp_ident into
the Rust type declared in pat_type. Every statement runs inside the
wrapper’s with_r_unwind_protect closure, where the argument SEXPs are
live for the whole call, so &str and the shared native references
borrow R’s storage directly (TryFromRoot).
Sourcefn conversion_stmts(
&self,
pat_type: &PatType,
sexp_ident: &Ident,
) -> Vec<TokenStream>
fn conversion_stmts( &self, pat_type: &PatType, sexp_ident: &Ident, ) -> Vec<TokenStream>
The conversion of one parameter, without the NonNa check before it
or the marker rebinding after it (see Self::build_conversion).
Sourcepub fn build_conversions(
&self,
inputs: &Punctuated<FnArg, Comma>,
sexp_idents: &[Ident],
) -> Vec<TokenStream>
pub fn build_conversions( &self, inputs: &Punctuated<FnArg, Comma>, sexp_idents: &[Ident], ) -> Vec<TokenStream>
Generate conversion statements for all parameters in a function signature.
Iterates over inputs (the function’s parameter list) paired with sexp_idents
(the corresponding SEXP variable names), calling build_conversion
for each typed parameter. Receiver parameters (self) are silently skipped.
Returns a flat list of all conversion statements, in parameter order.
Trait Implementations§
Auto Trait Implementations§
impl !Send for RustConversionBuilder
impl !Sync for RustConversionBuilder
impl Forget for RustConversionBuilder
impl Freeze for RustConversionBuilder
impl RefUnwindSafe for RustConversionBuilder
impl Unpin for RustConversionBuilder
impl UnsafeUnpin for RustConversionBuilder
impl UnwindSafe for RustConversionBuilder
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> SizeHint for Twhere
T: ?Sized,
impl<T> SizeHint for Twhere
T: ?Sized,
Source§default fn lower_bound(&self) -> usize
default fn lower_bound(&self) -> usize
core_io_internals)[u8; 12] could return any value between 0 and
12 inclusively as a correct implementation. Read moreSource§impl<T> SizedTypeProperties for T
impl<T> SizedTypeProperties for T
Source§#[doc(hidden)]const SIZE: usize
#[doc(hidden)]const SIZE: usize
sized_type_properties)Source§#[doc(hidden)]const ALIGN: usize
#[doc(hidden)]const ALIGN: usize
sized_type_properties)Source§#[doc(hidden)]const ALIGNMENT: Alignment
#[doc(hidden)]const ALIGNMENT: Alignment
ptr_alignment_type)Source§#[doc(hidden)]const IS_ZST: bool
#[doc(hidden)]const IS_ZST: bool
sized_type_properties)Source§#[doc(hidden)]const LAYOUT: Layout
#[doc(hidden)]const LAYOUT: Layout
sized_type_properties)Source§#[doc(hidden)]const MAX_SLICE_LEN: usize
#[doc(hidden)]const MAX_SLICE_LEN: usize
sized_type_properties)[Self]. Read moreLayout§
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: 568 bytes