Trait TryFromSexp

Source

pub trait TryFromSexp: Sized {
    type Error;

    const NATIVE_BORROW: Option<NativeBorrow> = None;
    const CHARACTER_ONLY: bool = false;
    #[doc(hidden)]
    const __MX_EXPECTATION: Option<&'static str> = None;

    // Required method
    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>;

    // Provided methods
    unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error> { ... }
    #[doc(hidden)]
    unsafe fn __mx_try_from_rooted(root: Root<'_>) -> Result<Self, Self::Error> { ... }
    #[doc(hidden)]
    fn __mx_has_na(&self) -> bool { ... }
    #[doc(hidden)]
    fn __mx_input_has_na(&self, input: SEXP) -> bool { ... }
    #[doc(hidden)]
    fn __mx_try_from_sexp_with_check(
        sexp: SEXP,
        check: &ElementCheck<'_>,
    ) -> Result<Self, SexpError>
       where Self::Error: Into<SexpError> { ... }
    #[doc(hidden)]
    unsafe fn __mx_try_from_sexp_unchecked_with_check(
        sexp: SEXP,
        check: &ElementCheck<'_>,
    ) -> Result<Self, SexpError>
       where Self::Error: Into<SexpError> { ... }
}

Expand description

TryFrom-style trait for converting SEXP to Rust types.

Inbound counterpart of crate::into_r::IntoR. Strict by construction (returns Result) — for a looser, multi-source coercion path use crate::coerce::Coerce / crate::coerce::TryCoerce.

§Examples

use miniextendr_api::SEXP;
use miniextendr_api::from_r::TryFromSexp;

fn example(sexp: SEXP) {
    let value: i32 = TryFromSexp::try_from_sexp(sexp).unwrap();
    let text: String = TryFromSexp::try_from_sexp(sexp).unwrap();
}

Provided Associated Constants§

Source

const NATIVE_BORROW: Option<NativeBorrow> = None

Native vector storage retained by this conversion, if any.

Generated wrappers use this before conversion to reject aliased mutable borrows. Owned and custom object conversions default to no native borrow. Conversions that retain native references must describe their leaf and forward this metadata through their containers.

Source

const CHARACTER_ONLY: bool = false

Whether this conversion accepts only character input: every value it converts, other than NULL, is a character vector or a factor.

#[miniextendr] reads it for choice parameters (match_arg / choices) typed Either<T, R>. Their R wrapper sends all character and factor input to the choice T, so an R with CHARACTER_ONLY = true could receive at most NULL, and the macro rejects the signature at compile time.

Defaults to false, which is always safe: the check is skipped. Set it to true in an implementation that reads only strings or factors, and forward it (<Inner as TryFromSexp>::CHARACTER_ONLY) in one that delegates to another conversion. Do not set it on a type that also converts numbers, logicals or lists: that would reject valid parameters.

The built-in string and factor conversions (including the types given try_from_sexp_via_str_parse!, such as uuid, url, regex and num-bigint), #[derive(MatchArg)] and #[derive(RFactor)] set it. Option<T>, Vec<T>, Box<[T]>, Missing<T> and #[derive(TryFromSexp)] newtypes forward it. AsCharacter leaves it false, since it also converts numbers.

§Examples

use miniextendr_api::SEXP;
use miniextendr_api::from_r::{SexpError, TryFromSexp};

pub struct Username(String);

impl TryFromSexp for Username {
    type Error = SexpError;
    const CHARACTER_ONLY: bool = <String as TryFromSexp>::CHARACTER_ONLY;

    fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error> {
        String::try_from_sexp(sexp).map(Username)
    }
}

Source

#[doc(hidden)]
const __MX_EXPECTATION: Option<&'static str> = None

What an argument of this type must be, in R terms, when #[miniextendr] cannot tell from the type as written: the <expected> of a failed conversion’s '' must be <expected>: ....

#[derive(TryFromSexp)] sets it from the newtype’s inner type (struct Dose(AsNumeric) says a single number, as AsNumeric does) or forwards the inner type’s. The generated wrapper reads it on the failure path of a parameter whose type the macro does not know, alone or as an arm of an Either. None (the default) leaves the expectation to the conversion error, else invalid '' argument.

Required Associated Types§

Source

type Error

The error type returned when conversion fails.

Required Methods§

Source

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Attempt to convert an R SEXP to this Rust type.

In debug builds, may assert that we’re on R’s main thread.

Provided Methods§

Source

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

Convert from SEXP without thread safety checks.

§Safety

Must be called from R’s main thread. In debug builds, this still calls the checked version by default, but implementations may skip thread assertions for performance.

Source

#[doc(hidden)]
unsafe fn __mx_try_from_rooted(root: Root<'_>) -> Result<Self, Self::Error>

Convert with a scope able to retain uncached ALTREP elements. Custom reference converters keep their existing behavior by default.

§Safety

R’s main thread. Any R-backed references in the result must be narrowed to the lifetime of root; this hook does not change Self’s lifetime.

Source

#[doc(hidden)]
fn __mx_has_na(&self) -> bool

Whether the converted argument holds a value #[miniextendr(no_na)] refuses after the conversion.

The default is false, because no_na’s R guard (!anyNA(x)) already refuses R’s NA before the conversion runs. The reading markers (AsNumeric*, AsCharacter*) override it: they read more inputs as missing than anyNA() sees (the text "NA", blank strings, a factor NA level, …). The layers a marker can sit in (Option, Missing, the named-list maps, Result<T, ()>, Either, #[derive(TryFromSexp)] newtypes) forward it, so a type alias or a newtype of a marker is checked too. The generated C wrapper calls it on the value of every no_na parameter that has the R guard.

Source

#[doc(hidden)]
fn __mx_input_has_na(&self, input: SEXP) -> bool

Whether #[miniextendr(no_na)] refuses this converted argument, read from input (the R value it converted from), when no R guard ran.

An Either parameter gets no !anyNA(x) guard: one test on the whole argument is wrong for an arm with its own reading of NA, such as a data frame whose cells may be missing. Its C wrapper calls this instead of __mx_has_na. The default makes the guard’s check in Rust (R’s anyNA(input)), then asks __mx_has_na for what a marker reads as NA beyond it. Either asks the arm the value converted to, Missing asks its value, and DataFrame refuses nothing, so the NA cells of a data frame arm get through. The wrappers Result<T, ()>, Option<DataFrame>, Option<Either<L, R>> and #[derive(TryFromSexp)] newtypes ask their value too, so a Result<DataFrame, ()> or Option<DataFrame> arm, a newtype of a DataFrame, or the data frame arm of an Option<Either<..>> keeps its NA cells as well. Their Err(()) / None comes only from NULL, which holds no NA, so it passes.

An Option arm over a scalar (Either<Option<AsNumeric>, DataFrame>) keeps the default, which reads the input rather than the value: NULL holds no NA and passes as None, while an NA the arm reads as None (Option<f64>, Option<String>) is still refused. An override that answered false for None would let that NA through; the overrides above can, since their None is never an NA.

Source

#[doc(hidden)]
fn __mx_try_from_sexp_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>
where Self::Error: Into<SexpError>,

Convert, running check, an element type’s TryFromSexpElement::check_sexp, on the R value that carries an element’s class (#1837).

The newtype containers read Vec<T> through Vec<T::Inner> and Vec<Option<T>> through Vec<Option<T::Inner>> with this, passing T::check_sexp, so the inner container decides where the check runs:

The default runs it once, on the whole input, then converts. An atomic vector carries its class on the vector.
A list of R objects runs it on each element instead, where each object carries its own class: Vec<List> on every element, Vec<Option<List>> on every element but NULL.
The newtype containers pass it on, with their own element’s check after it, so a newtype of a newtype checks outer then inner, as its scalar does.

An override must also override __mx_try_from_sexp_unchecked_with_check. Not public API.

Source

#[doc(hidden)]
unsafe fn __mx_try_from_sexp_unchecked_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>
where Self::Error: Into<SexpError>,

__mx_try_from_sexp_with_check through try_from_sexp_unchecked. Not public API.

§Safety

As try_from_sexp_unchecked.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Input	Result
Regular SEXP	Passed through unchanged
ALTREP SEXP	Materialized via `ensure_materialized`, then passed through

Trait TryFromSexp Copy item path

§Examples

Provided Associated Constants§

const NATIVE_BORROW: Option<NativeBorrow> = None

const CHARACTER_ONLY: bool = false

§Examples

#[doc(hidden)]const __MX_EXPECTATION: Option<&'static str> = None

Required Associated Types§

type Error

Required Methods§

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

Provided Methods§

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

§Safety

#[doc(hidden)]unsafe fn __mx_try_from_rooted(root: Root<'_>) -> Result<Self, Self::Error>

§Safety

#[doc(hidden)]fn __mx_has_na(&self) -> bool

#[doc(hidden)]fn __mx_input_has_na(&self, input: SEXP) -> bool

#[doc(hidden)]fn __mx_try_from_sexp_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>where Self::Error: Into<SexpError>,

#[doc(hidden)]unsafe fn __mx_try_from_sexp_unchecked_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>where Self::Error: Into<SexpError>,

§Safety

Dyn Compatibility§

Implementations on Foreign Types§

impl TryFromSexp for &'static str

§NA Handling

§Safety

const CHARACTER_ONLY: bool = true

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn __mx_try_from_rooted(root: Root<'_>) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for Arc<str>

const CHARACTER_ONLY: bool = true

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<String>

const CHARACTER_ONLY: bool = true

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<bool>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<i8>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<i16>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<i32>

type Error = SexpTypeError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<i64>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<isize>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<u8>

type Error = SexpTypeError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<u16>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<u32>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<u64>

type Error = SexpError

fn try_from_sexp(sexp: SEXP) -> Result<Self, Self::Error>

unsafe fn try_from_sexp_unchecked(sexp: SEXP) -> Result<Self, Self::Error>

impl TryFromSexp for BTreeSet<usize>

type Error = SexpError

Trait TryFromSexp

#[doc(hidden)]
const __MX_EXPECTATION: Option<&'static str> = None

#[doc(hidden)]
unsafe fn __mx_try_from_rooted(root: Root<'_>) -> Result<Self, Self::Error>

#[doc(hidden)]
fn __mx_has_na(&self) -> bool

#[doc(hidden)]
fn __mx_input_has_na(&self, input: SEXP) -> bool

#[doc(hidden)]
fn __mx_try_from_sexp_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>
where Self::Error: Into<SexpError>,

#[doc(hidden)]
unsafe fn __mx_try_from_sexp_unchecked_with_check( sexp: SEXP, check: &ElementCheck<'_>, ) -> Result<Self, SexpError>
where Self::Error: Into<SexpError>,