Skip to main content

Module rust_conversion_builder

Module rust_conversion_builder 

Source
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).
ConversionSubject 🔒
What a conversion failure is about: the value it names and how.
LayeredValue 🔒
The innermost value of a layered choice parameter.
Preparation 🔒
How the alias check prepares one argument (#1504).
RustConversionBuilder
Builder for generating Rust conversion statements from R SEXP parameters.

Enums§

ChoiceLayer 🔒
A layer around a choice parameter’s value, outermost first.
ChoiceLeaf
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 (under Missing / Option layers too) borrows what R borrows, for input other than character or factor. Read through EitherArmProbe, so an R without TryFromSexp adds no error of its own. None without an Either layer: a choice is owned.
class_slice 🔒
The &[&str] expression for classes the macro knows: the crate’s conversion_error_class, read where it expands.
conversion_err_arm 🔒
The Err(e) arm of a conversion binding: return the tagged kind = "conversion" value. __mx_conversion_err_parts! takes the class vector, message and data from an RConditionData error type, the R-worded reason from a built-in conversion error and the Display text otherwise; conversion_condition_value puts the context’s prefix before it, appends the crate’s conversion_error_class and adds e$param and e$rust_type.
conversion_err_arm_with_call 🔒
crate_class is an &[&str] expression (conversion_value_tokens).
conversion_value_tokens 🔒
The conversion_condition_value(...) expression for the error bound as e on subject, with the crate class and call. crate_class is 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 ty declares when the macro has no wording for it: an Option<String>, with the error bound as e. Only for a type the binding converts with TryFromSexp, whose __MX_EXPECTATION it reads.
either_arm_guards 🔒
One compile-time assertion per leaf of the R arm of an Either choice parameter param of type ty (nested Eithers on the R side peeled): compilation fails when the leaf’s TryFromSexp is CHARACTER_ONLY, since the choice check never sends character or factor input there. Read through EitherArmProbe, so a leaf without TryFromSexp adds no error of its own. Empty without an Either layer.
expected_arm 🔒
The from_r::ExpectedArm of one side of an Either, of type ty: the macro’s wording when it has one (crate::r_preconditions::conversion_expectation), a nested Either side by side, NULL or <T> for an Option<T> (or Nullable<T>) or Result<T, ()> side, else the type’s __MX_EXPECTATION, with its @param noun (crate::type_inspect::r_value_noun) for when neither the type nor its error names it. Every side is a TryFromSexp type, as Either’s own impl requires (and the Option / Nullable / Result impls of their T).
layered_choice_expr 🔒
The decoding expression for a choice parameter of type ty whose value sits under Missing / Option / Either layers (#1473, #1551), applied to the SEXP binding sexp. Each layer is one miniextendr_api::match_arg_* helper that takes the decoder of the layers below it, so Missing<Option<Mode>> becomes
na_refusal_stmt 🔒
if <has_na> { return <the no_na argument error>; }: the tagged kind = "conversion" value no_na’s R guard would raise (see no_na_value_stmt), for the post-conversion no_na check and the NonNa<T> check before the conversion alike.
names_impl_trait 🔒
Whether ty spells an impl Trait anywhere (impl AsRef<str>, Vec<impl Display>).
no_na_value_stmt 🔒
The post-conversion no_na check of the binding ident (R name r_name): when the value holds what its type reads as NA (TryFromSexp::__mx_has_na), return the tagged kind = "conversion" value no_na’s R guard would raise, with message verbatim, the crate’s conversion_error_class and e$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_sexp of an argument whose alias check may have prepared it (#1504): the conversion reads the prepared_binding the 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_ty supplies TryFromSexp expectations when the conversion uses that trait; rooted views instead derive their expectation from the error.
try_from_sexp 🔒
TryFromSexp on sexp_ident, and the type its binding names: ty, or for a copied trait signature (#2123) _, with the conversion through the witness target inferred 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 🔒
T for a Result<T, ()> type, which reads NULL as Err(()).