Skip to main content

Module r_preconditions

Module r_preconditions 

Source
Expand description

R-side precondition generation for type checking.

Generates argument checks in R wrapper functions that run BEFORE the .Call() boundary. This gives users clear, idiomatic R error messages with proper stack traces instead of Rust panic messages.

Each check tests ONE thing and names the requirement it enforces:

add <- function(a, b) {
  if (!isTRUE(is.integer(a))) .miniextendr_arg_error("a", "must be integer")
  if (!isTRUE(length(a) == 1L)) .miniextendr_arg_error("a", "must have length 1")
  if (!isTRUE(is.integer(b))) .miniextendr_arg_error("b", "must be integer")
  if (!isTRUE(length(b) == 1L)) .miniextendr_arg_error("b", "must have length 1")
  .Call(C_add, .call = sys.call(), a, b)
}

A failing check calls the preamble helper .miniextendr_arg_error (miniextendr-api/src/registry.rs), which raises the same condition as a failed Rust conversion: the crateโ€™s conversion_error_class, rust_error, kind = "conversion" and e$param, with the message 'a' must be integer (#1591). A passing check costs one isTRUE() test; the condition is only built on failure. isTRUE() keeps stopifnot()โ€™s failure semantics (NA fails too), and the guards are cheaper than the stopifnot() call they replace. conversion_expectation gives the Rust conversion the same vocabulary for its messages.

Re-exportsยง

use std::collections::HashMap; ๐Ÿ”’
use std::collections::HashSet; ๐Ÿ”’
use crate::naming::r_string_escape; ๐Ÿ”’

Structsยง

ExplicitChecks
R-side checks the author asked for by name on one parameter, rather than ones derived from its Rust type.
FallbackParam
A parameter whose Rust type is not in the static type table.
InheritsHint
One when(class = "...", message = "...") hint of an inherits check (#1824): the message a value gets when it fails the check and inherits from one of classes, in place of the checkโ€™s own. A data.frame passed where a model object is expected can be told which function takes a data frame, while NULL or a number gets the plain refusal.
PreconditionOptions
Per-function knobs that influence precondition codegen.
PreconditionOutput
Output of precondition analysis for a functionโ€™s parameters.
RAssertion ๐Ÿ”’
A single R-side check on one parameter: a requirement and the R condition enforcing it.

Enumsยง

RTypeCheck ๐Ÿ”’
Classification of an R-side type check for a function parameter.

Functionsยง

build_precondition_checks
Build precondition checks for a functionโ€™s parameters.
class_list_r ๐Ÿ”’
A class checkโ€™s classes in R: the quoted list for its message ('a', 'b' or 'c') and the argument of inherits() ("a" or c("a", "b", "c")), each class escaped as an R string.
coerce_widened ๐Ÿ”’
Keep the R gate in sync with the conversion actually selected for this type.
conversion_expectation ๐Ÿ”’
The R-facing expectation for a parameter of Rust type ty, for the message of its Rust conversion failure: '<p>' must be <expected>: ... (see RTypeCheck::expectation).
extract_single_generic_arg ๐Ÿ”’
Extract the single generic type argument from a path segment.
guarded ๐Ÿ”’
Let an Option<T> (or Nullable<T>) parameter pass NULL, and a Missing<T> parameter an omitted argument, in the named checks out on parameter param of type ty: each condition gains an is.null(param) || / missing(param) || prefix. The failure message names only the failed requirement: it is shown only for a present, non-NULL value.
has_type_check ๐Ÿ”’
Whether a parameter type has type-derived R-side checks at all, i.e. whether Checked / Unchecked and the per-parameter keywords have anything to keep or drop (SEXP, Missing<T>, ExternalPtr<T>, &Dots and unknown types have none).
integer_vector_wide_check ๐Ÿ”’
Build the lossless whole-number predicate for a REALSXP-accepting integer vector (the i64 / u64 / isize / usize family).
is_skip_type ๐Ÿ”’
Returns true for types that should never get a fallback precheck.
is_str ๐Ÿ”’
Whether ty is str.
is_vector_valued ๐Ÿ”’
Whether an argument of Rust type ty holds several values, so a no_na failure reads must not contain NA rather than must not be NA.
merge_message ๐Ÿ”’
Record from as the message of check, which may have only one.
needs_fallback ๐Ÿ”’
Returns true if a type is unknown to the static type table and should be recorded as a fallback parameter.
no_na_checked_after_conversion ๐Ÿ”’
Whether a no_na parameter of Rust type ty is checked for NA only in Rust, after the conversion, with no R guard: an Either<L, R>, also under Missing and Option. The layers are peeled as for a choice parameter (crate::type_inspect::choice_layers). A plain Option<Either<..>> converts through TryFromSexp, which reads NULL as None (no NA) and asks the Either otherwise; a choice Option<Either<Mode, X>> keeps the guard (see below). The type is read as written: an alias, a newtype or a Result<Either<..>, ()> keeps the guard.
no_na_holds_several ๐Ÿ”’
Whether a no_na value of Rust type ty holds several values, looking through the layers no_na checks through: Missing, Option (or Nullable), Result<T, _> (its T) and Either<L, R>, which holds several when either arm does. The text is fixed at compile time, before the conversion picks an arm, and contain also reads right for one value.
no_na_message ๐Ÿ”’
The condition message of a failed no_na check on parameter param of type ty: the authorโ€™s no_na(message = "...") verbatim (custom), else '<param>' must not be NA / '<param>' must not contain NA (no_na_requirement). The R guard builds the same text in R (.miniextendr_arg_error); the C wrapperโ€™s post-conversion check passes this one to arg_check_condition_value.
no_na_requirement ๐Ÿ”’
What a no_na parameter of Rust type ty must satisfy, without the parameter name: must not contain NA for a value holding several values (no_na_holds_several), else must not be NA.
numeric_or_text_check ๐Ÿ”’
Build the predicate for the AsNumeric / AsNumericVec markers.
numeric_type_check ๐Ÿ”’
Build the R expression for the numeric type predicate.
plain_na_check ๐Ÿ”’
The R test for a plain NA, Rโ€™s untyped missing value, as the argument param: (is.logical(p) && length(p) == 1L && is.na(p)). An optional scalar argument (Option<T> / Nullable<T> of a scalar T, a scalar match_arg / choices choice under Option) reads it as โ€œno valueโ€, like NULL (#2305): the type checks pass it (RAssertion::nullable) and the choice prelude skips it (crate::r_wrapper_builder::CallAttribution::match_arg_statement), as the Rust conversions read it as None (miniextendr_api::from_r::is_null_or_plain_na). && stops before is.na() for a value of another type or length, so the test is always TRUE or FALSE. An optional vector keeps is.null() alone: there a plain NA is a logical vector of length one.
r_check_for_reference ๐Ÿ”’
Map a reference type to its R-side type check.
r_check_for_type ๐Ÿ”’
Map a Rust type to its R-side type check, if applicable.
r_check_for_type_path ๐Ÿ”’
Map a syn::TypePath to its R-side type check.
r_check_for_vec_element ๐Ÿ”’
Map a Vec<T> or &[T] element type to the appropriate vector type check.
resolve_item_type_checks ๐Ÿ”’
resolve_type_checks without a per-parameter spelling: whether an item (function or method) keeps its type-derived checks by default, ranks 2 to 6. The condition-raise codegen keys on this item-level decision.
resolve_type_checks ๐Ÿ”’
Whether one parameter keeps its type-derived R-side checks, from every spelling that can decide it, most specific first; the first that speaks wins:
strict_conversion_expectation ๐Ÿ”’
The R-facing expectation of a strict lossy-integer parameter (i64, u64, isize, usize and their Vec / Vec<Option<_>> forms), whose Rust conversion accepts only integer and whole-number double input (#1594): a single whole number / a single non-negative whole number for a scalar, the vectorโ€™s usual integer or whole-number numeric (with non-negative for the unsigned ones) otherwise.
unchecked_expectation ๐Ÿ”’
The R-facing expectation of a type that has no R-side check, so its conversion alone says what it accepts (#1594):
unchecked_params ๐Ÿ”’
The R formals (formals) of the parameters of inputs whose type-derived checks are dropped, given each oneโ€™s rank-1 decision (param, keyed by Rust name) and the item, impl and crate defaults (resolve_type_checks; the feature is this macro crateโ€™s no-preconditions-default).