Skip to main content

Module nullable

Module nullable 

Source
Expand description

The NULL-on-None optional (Nullable<T>): a return, an #[r_data] field, or an argument read as Option<T>. Nullable<T>: an optional value whose None is NULL in R.

An Option<T> return converts through Option<T>’s own IntoR: None is NULL for a vector, list or class, but NA for a scalar (Option<i32> gives NA_integer_), because R stores a missing scalar as NA. Where None means that there is no value at all, whatever T is, return Nullable<T>: Some(v) converts as v does, and None is NULL. The RIterator adapter uses it for the end of iteration, which an NA item would be indistinguishable from.

ⓘ
use miniextendr_api::{miniextendr, Nullable};

#[miniextendr]
pub fn first_even(xs: Vec<i32>) -> Nullable<i32> {
    Nullable(xs.into_iter().find(|x| x % 2 == 0))
}
// R: first_even(c(1L, 4L)) → 4L
//    first_even(c(1L, 3L)) → NULL  (an `Option<i32>` return gives NA_integer_)

It reads from R as Option<T> does (TryFromSexp): NULL and NA are None. That makes it an #[r_data] field type of an #[derive(ExternalPtr)] struct, whose getter reads NULL for None and whose setter stores None for NULL (#2270); an Option<T> field reads NA for a scalar None, unless it is marked #[r_data(null_if_none)]. As a #[miniextendr] argument it behaves exactly as Option<T> (#2294): the same R-side checks and conversion message ('x' must be NULL or ...), and coerce, no_na and match_arg look through it. An optional argument is usually spelled Option<T>.

With the serde feature, Nullable<T> serializes and deserializes as Option<T> does, so a serde struct can hold one.

Re-exports§

use crate::SEXP; 🔒
use crate::from_r::prepared::Arms; 🔒
use crate::from_r::prepared::Prepared; 🔒
use crate::from_r::NativeBorrow; 🔒
use crate::from_r::TryFromSexp; 🔒
use crate::into_r::IntoR; 🔒

Structs§

Nullable
An optional value that R receives as NULL when None, whatever T is, and that reads NULL or NA from R as None. See the module docs.