Expand description
Shared utilities for converting R SEXP parameters to Rust types.
This module provides a builder for generating Rust conversion code from R SEXP arguments, ensuring consistent behavior across standalone functions and impl methods.
Re-exports§
use crate::miniextendr_fn::CoercionMapping;🔒use proc_macro2::TokenStream;🔒use quote::quote;🔒use quote::quote_spanned;🔒use syn::spanned::Spanned;🔒
Structs§
- ArgContext 🔒
- The R-facing context of one argument’s conversion failure (#1591).
- Conversion
Subject 🔒 - What a conversion failure is about: the value it names and how.
- Layered
Value 🔒 - The innermost value of a layered choice parameter.
- Preparation 🔒
- How the alias check prepares one argument (#1504).
- Rust
Conversion Builder - Builder for generating Rust conversion statements from R SEXP parameters.
Enums§
- Choice
Layer 🔒 - A layer around a choice parameter’s value, outermost first.
- Choice
Leaf - Where the innermost value of a layered choice parameter comes from.
- Expected 🔒
- Where the
<expected>of a conversion failure’s'<p>' must be <expected>comes from.
Functions§
- choice_
native_ 🔒borrow - The native borrow of a choice parameter (#1504): an
Either<T, R>choice (underMissing/Optionlayers too) borrows whatRborrows, for input other than character or factor. Read throughEitherArmProbe, so anRwithoutTryFromSexpadds no error of its own.Nonewithout anEitherlayer: a choice is owned. - class_
slice 🔒 - The
&[&str]expression for classes the macro knows: the crate’sconversion_error_class, read where it expands. - conversion_
err_ 🔒arm - The
Err(e)arm of a conversion binding: return the taggedkind = "conversion"value.__mx_conversion_err_parts!takes the class vector, message and data from anRConditionDataerror type, the R-worded reason from a built-in conversion error and theDisplaytext otherwise;conversion_condition_valueputs the context’s prefix before it, appends the crate’sconversion_error_classand addse$paramande$rust_type. - conversion_
err_ 🔒arm_ with_ call crate_classis an&[&str]expression (conversion_value_tokens).- conversion_
value_ 🔒tokens - The
conversion_condition_value(...)expression for the error bound aseonsubject, with the crate class andcall.crate_classis an expression of type&[&str], evaluated only on the failure path: the literal classes (class_slice), or a shim’s run-time read. - declared_
expectation 🔒 - The expression, on a conversion failure’s path, for what a parameter of
type
tydeclares when the macro has no wording for it: anOption<String>, with the error bound ase. Only for a type the binding converts withTryFromSexp, whose__MX_EXPECTATIONit reads. - either_
arm_ 🔒guards - One compile-time assertion per leaf of the
Rarm of anEitherchoice parameterparamof typety(nestedEithers on theRside peeled): compilation fails when the leaf’sTryFromSexpisCHARACTER_ONLY, since the choice check never sends character or factor input there. Read throughEitherArmProbe, so a leaf withoutTryFromSexpadds no error of its own. Empty without anEitherlayer. - expected_
arm 🔒 - The
from_r::ExpectedArmof one side of anEither, of typety: the macro’s wording when it has one (crate::r_preconditions::conversion_expectation), a nestedEitherside by side,NULL or <T>for anOption<T>(orNullable<T>) orResult<T, ()>side, else the type’s__MX_EXPECTATION, with its@paramnoun (crate::type_inspect::r_value_noun) for when neither the type nor its error names it. Every side is aTryFromSexptype, asEither’s own impl requires (and theOption/Nullable/Resultimpls of theirT). - layered_
choice_ 🔒expr - The decoding expression for a choice parameter of type
tywhose value sits underMissing/Option/Eitherlayers (#1473, #1551), applied to theSEXPbindingsexp. Each layer is oneminiextendr_api::match_arg_*helper that takes the decoder of the layers below it, soMissing<Option<Mode>>becomes - na_
refusal_ 🔒stmt if <has_na> { return <the no_na argument error>; }: the taggedkind = "conversion"valueno_na’s R guard would raise (seeno_na_value_stmt), for the post-conversionno_nacheck and theNonNa<T>check before the conversion alike.- names_
impl_ 🔒trait - Whether
tyspells animpl Traitanywhere (impl AsRef<str>,Vec<impl Display>). - no_
na_ 🔒value_ stmt - The post-conversion
no_nacheck of the bindingident(R namer_name): when the value holds what its type reads asNA(TryFromSexp::__mx_has_na), return the taggedkind = "conversion"valueno_na’s R guard would raise, withmessageverbatim, the crate’sconversion_error_classande$param(arg_check_condition_value). The call is the wrapper’s call slot, as for a conversion failure. - owned_
string_ 🔒storage - The four borrowed character shapes supported by the raw converters, with the owned type each decodes into and the borrow of that storage. Do not generalize this to arbitrary list nesting, which has different conversion and rooting requirements (#1427).
- prepared_
binding 🔒 - The binding of a parameter’s prepared state between its alias check and its conversion (#1504). Mixed-site, like every conversion temporary.
- prepared_
conversion 🔒 try_from_sexpof an argument whose alias check may have prepared it (#1504): the conversion reads theprepared_bindingthe check left.- shim_
conversion_ 🔒err_ arm - Trait shims have no R call slot. They return the same structured argument
error as C wrappers; a View re-panic attributes it to the consumer’s call.
read_tysupplies TryFromSexp expectations when the conversion uses that trait; rooted views instead derive their expectation from the error. - try_
from_ 🔒sexp TryFromSexponsexp_ident, and the type its binding names:ty, or for a copied trait signature (#2123)_, with the conversion through the witnesstargetinferred from the concrete method, so a declaration-local type is never spelled in the impl’s module.- two_
pass_ 🔒alias_ guard - The alias check of a wrapper or trait shim with preparable arguments (#1504), in two passes:
- unit_
result_ 🔒ok_ type Tfor aResult<T, ()>type, which readsNULLasErr(()).