Struct Dots

Source

pub struct Dots {
    pub inner: SEXP,
}

Expand description

Rust type representing R’s ... (variadic arguments).

The generated R wrapper captures ... as list(...) and passes it to Rust, so Dots holds a list SEXP. Use as_list or try_list to access elements by name or position.

Declare as the last parameter: fn foo(x: i32, _dots: &Dots). Use name @ ... syntax for a custom parameter name.

Fields§

§inner: SEXP

Raw list backing this ... capture.

This is usually a VECSXP built from list(...) by generated wrappers.

Implementations§

Source §

impl Dots

Source

pub fn empty() -> Self

Create an empty Dots (equivalent to no ... arguments).

This is useful when calling R functions from Rust that expect dots arguments but you want to pass nothing.

§Example

#[miniextendr]
pub fn my_constructor(x: Doubles, dots: ...) -> Robj {
    // ...
}

// Call from Rust with empty dots:
let result = my_constructor(data, Dots::empty());

Source

pub fn as_list(&self) -> List

Convert to a List without additional validation.

This is a zero-cost conversion since the R wrapper already passes list(...) to us. Use this when you trust the input or want maximum performance.

§Safety Note

This is safe because the miniextendr macro always wraps ... in list(...) on the R side. However, if you’re receiving a SEXP from another source, use try_list instead.

§Example

#[miniextendr]
pub fn process_dots(dots: ...) -> i32 {
    let list = dots.as_list();
    list.len() as i32
}

Source

pub fn try_list(&self) -> Result<List, ListFromSexpError>

Try to convert to a List with full validation.

This validates that the underlying SEXP is actually a list and checks for duplicate names. Use this when you want strict validation or are working with untrusted input.

§Errors

Returns ListFromSexpError if:

The SEXP is not a list type (VECSXP or pairlist)
The list contains duplicate non-NA names

§Example

#[miniextendr]
pub fn safe_process_dots(dots: ...) -> Result<i32, String> {
    let list = dots.try_list().map_err(|e| e.to_string())?;
    Ok(list.len() as i32)
}

Source

pub fn len(&self) -> isize

Get the number of elements in the dots list.

This is equivalent to dots.as_list().len() but avoids creating an intermediate List wrapper.

Source

pub fn is_empty(&self) -> bool

Returns true if no arguments were passed to ....

Source

pub fn typed(&self, spec: TypedListSpec) -> Result<TypedList, TypedListError>

Validate the dots against a typed list specification.

This provides structured validation with clear error messages for functions that expect specific named arguments via ....

§Example

use miniextendr_api::typed_list::{TypedListSpec, TypedEntry, TypeSpec};

#[miniextendr]
pub fn process_args(dots: ...) -> Result<i32, String> {
    let spec = TypedListSpec::new(vec![
        TypedEntry::required("alpha", TypeSpec::Numeric(Some(4))),
        TypedEntry::optional("beta", TypeSpec::List(None)),
    ]);

    let validated = dots.typed(spec).map_err(|e| e.to_string())?;
    let alpha: Vec<f64> = validated.get("alpha").map_err(|e| e.to_string())?;
    Ok(alpha.len() as i32)
}