Skip to main content

Module non_na

Module non_na 

Source
Expand description

NonNa<T>: a value that holds no R NA, a #[miniextendr] parameter marker. NonNa<T>: a value that holds no R NA.

As a #[miniextendr] parameter type, NonNa<T> is #[miniextendr(no_na)] written in the type: the parameter converts as T, an argument holding an NA is refused with no_na’s argument error, and the body receives a value that says so in its type.

ⓘ
use miniextendr_api::{NonNa, miniextendr};

/// `xs` holds no `NA` (and no `NaN`); `sum()` needs no check of its own.
#[miniextendr]
pub fn total(xs: NonNa<Vec<f64>>) -> f64 {
    xs.iter().sum()
}

/// A string argument: `NA_character_` is refused instead of reaching the
/// body as `""`, as it would for a plain `String`.
#[miniextendr]
pub fn greet(name: NonNa<String>) -> String {
    format!("hello {}", name.unwrap())
}

“NA” is what R’s anyNA() counts: NA in every type, and NaN in doubles and complex numbers. The generated R wrapper checks it first (!anyNA(x), the no_na guard), and the C wrapper checks the argument again before converting it, so a .Call() that skips the R wrapper cannot hand the body an NA either. A reading marker (AsNumeric, …) is also asked after its conversion, as under no_na ("NA" strings, blank cells). The custom message of no_na(message = "...") applies when both are written.

The marker composes with the precondition markers (Unchecked<NonNa<Vec<f64>>> drops the type checks and keeps this one). Like them it goes outermost (NonNa<Option<T>> is refused, since a value without NA makes Option mean only NULL: write Option<T> with #[miniextendr(no_na)] for that), it is a parameter type only, and it cannot appear in a #[miniextendr] trait’s method signature (spell no_na(x) on the impl) or on an extern "C-unwind" function.

§Construction

The generated wrapper builds a NonNa after its check. Rust code builds one with NonNa::new, which checks the value (MaybeNa) and returns None when it holds an NA, or with NonNa::new_unchecked, whose caller promises there is none. There is no other way in: the field is private, and there is no DerefMut / AsMut, which would let code write an NA into it.

Re-exports§

use std::borrow::Borrow; 🔒
use std::ops::Deref; 🔒
use crate::sexp_types::IsNA; 🔒
use crate::sexp_types::RLogical; 🔒
use crate::sexp_types::Rcomplex; 🔒

Macros§

never_na 🔒
Types with no NA form: an R NA is refused when converting to them, or (strings) has no value of the type.

Structs§

NonNa
A value that holds no R NA: a #[miniextendr] parameter refuses an argument with one (see the module docs). Transparent over T.

Traits§

MaybeNa
A type whose values can hold R’s NA, with the check NonNa::new makes.