extendr_api/
lib.rs

1//! An ergonomic, opinionated, safe and user-friendly wrapper to the R-API
2//!
3//! This library aims to provide an interface that will be familiar to
4//! first-time users of Rust or indeed any compiled language.
5//!
6//! See [`Robj`] for much of the content of this crate.
7//! [`Robj`] provides a safe wrapper for the R object type.
8//!
9//! ## Examples
10//!
11//! Use attributes and macros to export to R.
12//!
13//! ```ignore
14//! use extendr_api::prelude::*;
15//! // Export a function or impl to R.
16//! #[extendr]
17//! fn fred(a: i32) -> i32 {
18//!     a + 1
19//! }
20//!
21//! // define exports using extendr_module
22//! extendr_module! {
23//!    mod mymodule;
24//!    fn fred;
25//! }
26//!
27//! ```
28//!
29//! In R:
30//!
31//! ```ignore
32//! result <- fred(1)
33//! ```
34//!
35//! [Robj] is a wrapper for R objects.
36//! The r!() and R!() macros let you build R objects
37//! using Rust and R syntax respectively.
38//! ```
39//! use extendr_api::prelude::*;
40//! test! {
41//!     // An R object with a single string "hello"
42//!     let character = r!("hello");
43//!     let character = r!(["hello", "goodbye"]);
44//!
45//!     // An R integer object with a single number 1L.
46//!     // Note that in Rust, 1 is an integer and 1.0 is a real.
47//!     let integer = r!(1);
48//!
49//!     // An R real object with a single number 1.
50//!     // Note that in R, 1 is a real and 1L is an integer.
51//!     let real = r!(1.0);
52//!
53//!     // An R real vector.
54//!     let real_vector = r!([1.0, 2.0]);
55//!     let real_vector = &[1.0, 2.0].iter().collect_robj();
56//!     let real_vector = r!(vec![1.0, 2.0]);
57//!
58//!     // An R function object.
59//!     let function = R!("function(x, y) { x + y }")?;
60//!
61//!     // A named list using the list! macro.
62//!     let list = list!(a = 1, b = 2);
63//!
64//!     // An unnamed list (of R objects) using the List wrapper.
65//!     let list = r!(List::from_values(vec![1, 2, 3]));
66//!     let list = r!(List::from_values(vec!["a", "b", "c"]));
67//!     let list = r!(List::from_values(&[r!("a"), r!(1), r!(2.0)]));
68//!
69//!     // A symbol
70//!     let sym = sym!(wombat);
71//!
72//!     // A R vector using collect_robj()
73//!     let vector = (0..3).map(|x| x * 10).collect_robj();
74//! }
75//! ```
76//!
77//! In Rust, we prefer to use iterators rather than loops.
78//!
79//! ```
80//! use extendr_api::prelude::*;
81//! test! {
82//!     // 1 ..= 100 is the same as 1:100
83//!     let res = r!(1 ..= 100);
84//!     assert_eq!(res, R!("1:100")?);
85//!
86//!     // Rust arrays are zero-indexed so it is more common to use 0 .. 100.
87//!     let res = r!(0 .. 100);
88//!     assert_eq!(res.len(), 100);
89//!
90//!     // Using map is a super fast way to generate vectors.
91//!     let iter = (0..3).map(|i| format!("fred{}", i));
92//!     let character = iter.collect_robj();
93//!     assert_eq!(character, r!(["fred0", "fred1", "fred2"]));
94//! }
95//! ```
96//!
97//! To index a vector, first convert it to a slice and then
98//! remember to use 0-based indexing. In Rust, going out of bounds
99//! will cause and error (a panic) unlike C++ which may crash.
100//! ```
101//! use extendr_api::prelude::*;
102//! test! {
103//!     let vals = r!([1.0, 2.0]);
104//!     let slice = vals.as_real_slice().ok_or("expected slice")?;
105//!     let one = slice[0];
106//!     let two = slice[1];
107//!     // let error = slice[2];
108//!     assert_eq!(one, 1.0);
109//!     assert_eq!(two, 2.0);
110//! }
111//! ```
112//!
113//! Much slower, but more general are these methods:
114//! ```
115//! use extendr_api::prelude::*;
116//! test! {
117//!     let vals = r!([1.0, 2.0, 3.0]);
118//!
119//!     // one-based indexing [[i]], returns an object.
120//!     assert_eq!(vals.index(1)?, r!(1.0));
121//!
122//!     // one-based slicing [x], returns an object.
123//!     assert_eq!(vals.slice(1..=2)?, r!([1.0, 2.0]));
124//!
125//!     // $ operator, returns an object
126//!     let list = list!(a = 1.0, b = "xyz");
127//!     assert_eq!(list.dollar("a")?, r!(1.0));
128//! }
129//! ```
130//!
131//! The [R!] macro lets you embed R code in Rust
132//! and takes Rust expressions in {{ }} pairs.
133//!
134//! The [Rraw!] macro will not expand the {{ }} pairs.
135//! ```
136//! use extendr_api::prelude::*;
137//! test! {
138//!     // The text "1 + 1" is parsed as R source code.
139//!     // The result is 1.0 + 1.0 in Rust.
140//!     assert_eq!(R!("1 + 1")?, r!(2.0));
141//!
142//!     let a = 1.0;
143//!     assert_eq!(R!("1 + {{a}}")?, r!(2.0));
144//!
145//!     assert_eq!(R!(r"
146//!         x <- {{ a }}
147//!         x + 1
148//!     ")?, r!(2.0));
149//!
150//!     assert_eq!(R!(r#"
151//!         x <- "hello"
152//!         x
153//!     "#)?, r!("hello"));
154//!
155//!     // Use the R meaning of {{ }} and do not expand.
156//!     assert_eq!(Rraw!(r"
157//!         x <- {{ 1 }}
158//!         x + 1
159//!     ")?, r!(2.0));
160//! }
161//! ```
162//!
163//! The [r!] macro converts a rust object to an R object
164//! and takes parameters.
165//! ```
166//! use extendr_api::prelude::*;
167//! test! {
168//!     // The text "1.0+1.0" is parsed as Rust source code.
169//!     let one = 1.0;
170//!     assert_eq!(r!(one+1.0), r!(2.0));
171//! }
172//! ```
173//!
174//! Rust has a concept of "Owned" and "Borrowed" objects.
175//!
176//! Owned objects, such as [Vec] and [String] allocate memory
177//! which is released when the object lifetime ends.
178//!
179//! Borrowed objects such as &[i32] and &str are just pointers
180//! to annother object's memory and can't live longer than the
181//! object they reference.
182//!
183//! Borrowed objects are much faster than owned objects and use less
184//! memory but are used only for temporary access.
185//!
186//! When we take a slice of an R vector, for example, we need the
187//! original R object to be alive or the data will be corrupted.
188//!
189//! ```
190//! use extendr_api::prelude::*;
191//! test! {
192//!     // robj is an "Owned" object that controls the memory allocated.
193//!     let robj = r!([1, 2, 3]);
194//!
195//!     // Here slice is a "borrowed" reference to the bytes in robj.
196//!     // and cannot live longer than robj.
197//!     let slice = robj.as_integer_slice().ok_or("expected slice")?;
198//!     assert_eq!(slice.len(), 3);
199//! }
200//! ```
201//!
202//! ## Writing tests
203//!
204//! To test the functions exposed to R, wrap your code in the [`test!`] macro.
205//! This macro starts up the necessary R machinery for tests to work.
206//!
207//! ```no_run
208//! use extendr_api::prelude::*;
209//!
210//! #[extendr]
211//! fn things() ->  Strings {
212//!     Strings::from_values(vec!["Test", "this"])
213//! }
214//!
215//! // define exports using extendr_module
216//! extendr_module! {
217//!    mod mymodule;
218//!    fn things;
219//! }
220//!
221//!
222//! #[cfg(test)]
223//! mod test {
224//!     use super::*;
225//!     use extendr_api::prelude::*;
226//!
227//!     #[test]
228//!     fn test_simple_function() {
229//!         assert_eq!(things().elt(0), "Test")
230//!     }
231//! }
232//! ```
233//!
234//! ## Returning `Result<T, E>` to R
235//!
236//! Two experimental features for returning error-aware R `list`s, `result_list` and `result_condition`,
237//! can be toggled to avoid panics on `Err`. Instead, an `Err` `x` is returned as either
238//!  - list: `list(ok=NULL, err=x)` when `result_list` is enabled,
239//!  - error condition: `<error: extendr_error>`, with `x` placed in `condition$value`, when `resultd_condition` is enabled.
240//!
241//! It is currently solely up to the user to handle any result on R side.
242//!
243//! There is an added overhead of wrapping Rust results in an R `list` object.
244//!
245//! ```ignore
246//! use extendr_api::prelude::*;
247//! // simple function always returning an Err string
248//! #[extendr]
249//! fn oups(a: i32) -> std::result::Result<i32, String> {
250//!     Err("I did it again".to_string())
251//! }
252//!
253//! // define exports using extendr_module
254//! extendr_module! {
255//!    mod mymodule;
256//!    fn oups;
257//! }
258//!
259//! ```
260//!
261//! In R:
262//!
263//! ```ignore
264//! # default result_panic feature
265//! oups(1)
266//! > ... long panic traceback from rust printed to stderr
267//!
268//! # result_list feature
269//! lst <- oups(1)
270//! print(lst)
271//! > list(ok = NULL, err = "I did it again")
272//!
273//! # result_condition feature
274//! cnd <- oups(1)
275//! print(cnd)
276//! > <error: extendr_error>
277//! print(cnd$value)
278//! > "I did it again"
279//!
280//! # handling example for result_condition
281//! oups_handled <- function(a) {
282//!   val_or_err <- oups(1)
283//!   if (inherits(val_or_err, "extendr_error")) stop(val_or_err)
284//!   val_or_err
285//! }
286//! ```
287//!
288//! ## Feature gates
289//!
290//! extendr-api has some optional features behind these feature gates:
291//!
292//! - `ndarray`: provides the conversion between R's matrices and [`ndarray`](https://docs.rs/ndarray/latest/ndarray/).
293//! - `num-complex`: provides the conversion between R's complex numbers and [`num-complex`](https://docs.rs/num-complex/latest/num_complex/).
294//! - `serde`: provides the [`serde`](https://serde.rs/) support.
295//! - `graphics`: provides the functionality to control or implement graphics devices.
296//! - `either`: provides implementation of type conversion traits for `Either<L, R>` from [`either`](https://docs.rs/either/latest/either/) if `L` and `R` both implement those traits.
297//! - `faer`: provides conversion between R's matrices and [`faer`](https://docs.rs/faer/latest/faer/).
298//!
299//! extendr-api supports three ways of returning a Result<T,E> to R.
300//! Only one behavior feature can be enabled at a time.
301//! - `result_panic`: Default behavior, return `Ok` as is, panic! on any `Err`
302//!
303//! Default behavior can be overridden by specifying `extend_api` features, i.e. `extendr-api = {..., default-features = false, features= ["result_condition"]}`
304//! These features are experimental and are subject to change.
305//! - `result_list`: return `Ok` as `list(ok=?, err=NULL)` or `Err` `list(ok=NULL, err=?)`
306//! - `result_condition`: return `Ok` as is or `Err` as $value in an R error condition.
307#![doc(
308    html_logo_url = "https://raw.githubusercontent.com/extendr/extendr/master/extendr-logo-256.png"
309)]
310
311pub mod error;
312pub mod functions;
313pub mod io;
314pub mod iter;
315pub mod lang_macros;
316pub mod metadata;
317pub mod na;
318pub mod optional;
319pub mod ownership;
320pub mod prelude;
321pub mod rmacros;
322pub mod robj;
323pub mod scalar;
324pub mod thread_safety;
325pub mod wrapper;
326
327pub use robj::Robj;
328pub use std::convert::{TryFrom, TryInto};
329pub use std::ops::Deref;
330pub use std::ops::DerefMut;
331
332#[cfg(feature = "serde")]
333pub mod serializer;
334
335#[cfg(feature = "serde")]
336pub mod deserializer;
337
338#[cfg(feature = "graphics")]
339pub mod graphics;
340
341pub(crate) mod conversions;
342
343//////////////////////////////////////////////////
344// Note these pub use statements are deprecated
345//
346// `use extendr_api::prelude::*;`
347//
348// instead.
349
350pub use error::*;
351pub use functions::*;
352pub use lang_macros::*;
353pub use na::*;
354pub use robj::*;
355pub use thread_safety::{catch_r_error, handle_panic, single_threaded, throw_r_error};
356pub use wrapper::*;
357
358pub use extendr_macros::*;
359
360use extendr_ffi::SEXPTYPE;
361use scalar::Rbool;
362
363//////////////////////////////////////////////////
364
365/// TRUE value eg. `r!(TRUE)`
366pub const TRUE: Rbool = Rbool::true_value();
367
368/// FALSE value eg. `r!(FALSE)`
369pub const FALSE: Rbool = Rbool::false_value();
370
371/// NULL value eg. `r!(NULL)`
372pub const NULL: () = ();
373
374/// NA value for integers eg. `r!(NA_INTEGER)`
375pub const NA_INTEGER: Option<i32> = None;
376
377/// NA value for real values eg. `r!(NA_REAL)`
378pub const NA_REAL: Option<f64> = None;
379
380/// NA value for strings. `r!(NA_STRING)`
381pub const NA_STRING: Option<&str> = None;
382
383/// NA value for logical. `r!(NA_LOGICAL)`
384pub const NA_LOGICAL: Rbool = Rbool::na_value();
385
386#[doc(hidden)]
387pub use std::collections::HashMap;
388
389/// This is needed for the generation of wrappers.
390#[doc(hidden)]
391pub use extendr_ffi::DllInfo;
392
393/// This is necessary for `#[extendr]`-impl
394#[doc(hidden)]
395pub use extendr_ffi::R_ExternalPtrAddr;
396
397/// This is used in `#[extendr(use_rng = true)]` on `fn`-items.
398#[doc(hidden)]
399pub use extendr_ffi::GetRNGstate;
400
401/// This is used in `#[extendr(use_rng = true)]` on `fn`-items.
402#[doc(hidden)]
403pub use extendr_ffi::PutRNGstate;
404
405#[doc(hidden)]
406pub use extendr_ffi::SEXP;
407
408#[doc(hidden)]
409use std::ffi::CString;
410
411pub use metadata::Metadata;
412
413#[doc(hidden)]
414pub struct CallMethod {
415    pub call_symbol: std::ffi::CString,
416    pub func_ptr: *const u8,
417    pub num_args: i32,
418}
419
420unsafe fn make_method_def(
421    cstrings: &mut Vec<std::ffi::CString>,
422    rmethods: &mut Vec<extendr_ffi::R_CallMethodDef>,
423    func: &metadata::Func,
424    wrapped_name: &str,
425) {
426    cstrings.push(std::ffi::CString::new(wrapped_name).unwrap());
427    rmethods.push(extendr_ffi::R_CallMethodDef {
428        name: cstrings.last().unwrap().as_ptr(),
429        fun: Some(std::mem::transmute(func.func_ptr)),
430        numArgs: func.args.len() as i32,
431    });
432}
433
434// Internal function used to implement the .Call interface.
435// This is called from the code generated by the #[extendr] attribute.
436#[doc(hidden)]
437pub unsafe fn register_call_methods(info: *mut extendr_ffi::DllInfo, metadata: Metadata) {
438    let mut rmethods = Vec::new();
439    let mut cstrings = Vec::new();
440    for func in metadata.functions {
441        let wrapped_name = format!("wrap__{}", func.mod_name);
442        make_method_def(&mut cstrings, &mut rmethods, &func, wrapped_name.as_str());
443    }
444
445    for imp in metadata.impls {
446        for func in imp.methods {
447            let wrapped_name = format!("wrap__{}__{}", imp.name, func.mod_name);
448            make_method_def(&mut cstrings, &mut rmethods, &func, wrapped_name.as_str());
449        }
450    }
451
452    rmethods.push(extendr_ffi::R_CallMethodDef {
453        name: std::ptr::null(),
454        fun: None,
455        numArgs: 0,
456    });
457
458    extendr_ffi::R_registerRoutines(
459        info,
460        std::ptr::null(),
461        rmethods.as_ptr(),
462        std::ptr::null(),
463        std::ptr::null(),
464    );
465
466    // This seems to allow both symbols and strings,
467    extendr_ffi::R_useDynamicSymbols(info, extendr_ffi::Rboolean::FALSE);
468    extendr_ffi::R_forceSymbols(info, extendr_ffi::Rboolean::FALSE);
469}
470
471/// Type of R objects used by [Robj::rtype].
472#[derive(Debug, PartialEq)]
473pub enum Rtype {
474    Null,        // NILSXP
475    Symbol,      // SYMSXP
476    Pairlist,    // LISTSXP
477    Function,    // CLOSXP
478    Environment, // ENVSXP
479    Promise,     // PROMSXP
480    Language,    // LANGSXP
481    Special,     // SPECIALSXP
482    Builtin,     // BUILTINSXP
483    Rstr,        // CHARSXP
484    Logicals,    // LGLSXP
485    Integers,    // INTSXP
486    Doubles,     // REALSXP
487    Complexes,   // CPLXSXP
488    Strings,     // STRSXP
489    Dot,         // DOTSXP
490    Any,         // ANYSXP
491    List,        // VECSXP
492    Expressions, // EXPRSXP
493    Bytecode,    // BCODESXP
494    ExternalPtr, // EXTPTRSXP
495    WeakRef,     // WEAKREFSXP
496    Raw,         // RAWSXP
497    S4,          // S4SXP
498    Unknown,
499}
500
501/// Enum use to unpack R objects into their specialist wrappers.
502// Todo: convert all Robj types to wrappers.
503// Note: this only works if the wrappers are all just SEXPs.
504#[derive(Debug, PartialEq)]
505pub enum Rany<'a> {
506    Null(&'a Robj),               // NILSXP
507    Symbol(&'a Symbol),           // SYMSXP
508    Pairlist(&'a Pairlist),       // LISTSXP
509    Function(&'a Function),       // CLOSXP
510    Environment(&'a Environment), // ENVSXP
511    Promise(&'a Promise),         // PROMSXP
512    Language(&'a Language),       // LANGSXP
513    Special(&'a Primitive),       // SPECIALSXP
514    Builtin(&'a Primitive),       // BUILTINSXP
515    Rstr(&'a Rstr),               // CHARSXP
516    Logicals(&'a Logicals),       // LGLSXP
517    Integers(&'a Integers),       // INTSXP
518    Doubles(&'a Doubles),         // REALSXP
519    Complexes(&'a Complexes),     // CPLXSXP
520    Strings(&'a Strings),         // STRSXP
521    Dot(&'a Robj),                // DOTSXP
522    Any(&'a Robj),                // ANYSXP
523    List(&'a List),               // VECSXP
524    Expressions(&'a Expressions), // EXPRSXP
525    Bytecode(&'a Robj),           // BCODESXP
526    ExternalPtr(&'a Robj),        // EXTPTRSXP
527    WeakRef(&'a Robj),            // WEAKREFSXP
528    Raw(&'a Raw),                 // RAWSXP
529    S4(&'a S4),                   // S4SXP
530    Unknown(&'a Robj),
531}
532
533/// Convert extendr's Rtype to R's SEXPTYPE.
534/// Panics if the type is Unknown.
535pub fn rtype_to_sxp(rtype: Rtype) -> SEXPTYPE {
536    use extendr_ffi::SEXPTYPE;
537    match rtype {
538        Rtype::Null => SEXPTYPE::NILSXP,
539        Rtype::Symbol => SEXPTYPE::SYMSXP,
540        Rtype::Pairlist => SEXPTYPE::LISTSXP,
541        Rtype::Function => SEXPTYPE::CLOSXP,
542        Rtype::Environment => SEXPTYPE::ENVSXP,
543        Rtype::Promise => SEXPTYPE::PROMSXP,
544        Rtype::Language => SEXPTYPE::LANGSXP,
545        Rtype::Special => SEXPTYPE::SPECIALSXP,
546        Rtype::Builtin => SEXPTYPE::BUILTINSXP,
547        Rtype::Rstr => SEXPTYPE::CHARSXP,
548        Rtype::Logicals => SEXPTYPE::LGLSXP,
549        Rtype::Integers => SEXPTYPE::INTSXP,
550        Rtype::Doubles => SEXPTYPE::REALSXP,
551        Rtype::Complexes => SEXPTYPE::CPLXSXP,
552        Rtype::Strings => SEXPTYPE::STRSXP,
553        Rtype::Dot => SEXPTYPE::DOTSXP,
554        Rtype::Any => SEXPTYPE::ANYSXP,
555        Rtype::List => SEXPTYPE::VECSXP,
556        Rtype::Expressions => SEXPTYPE::EXPRSXP,
557        Rtype::Bytecode => SEXPTYPE::BCODESXP,
558        Rtype::ExternalPtr => SEXPTYPE::EXTPTRSXP,
559        Rtype::WeakRef => SEXPTYPE::WEAKREFSXP,
560        Rtype::Raw => SEXPTYPE::RAWSXP,
561        #[cfg(not(use_objsxp))]
562        Rtype::S4 => SEXPTYPE::S4SXP,
563        #[cfg(use_objsxp)]
564        Rtype::S4 => SEXPTYPE::OBJSXP,
565        Rtype::Unknown => panic!("attempt to use Unknown Rtype"),
566    }
567}
568
569/// Convert R's SEXPTYPE to extendr's Rtype.
570pub fn sxp_to_rtype(sxptype: SEXPTYPE) -> Rtype {
571    match sxptype {
572        SEXPTYPE::NILSXP => Rtype::Null,
573        SEXPTYPE::SYMSXP => Rtype::Symbol,
574        SEXPTYPE::LISTSXP => Rtype::Pairlist,
575        SEXPTYPE::CLOSXP => Rtype::Function,
576        SEXPTYPE::ENVSXP => Rtype::Environment,
577        SEXPTYPE::PROMSXP => Rtype::Promise,
578        SEXPTYPE::LANGSXP => Rtype::Language,
579        SEXPTYPE::SPECIALSXP => Rtype::Special,
580        SEXPTYPE::BUILTINSXP => Rtype::Builtin,
581        SEXPTYPE::CHARSXP => Rtype::Rstr,
582        SEXPTYPE::LGLSXP => Rtype::Logicals,
583        SEXPTYPE::INTSXP => Rtype::Integers,
584        SEXPTYPE::REALSXP => Rtype::Doubles,
585        SEXPTYPE::CPLXSXP => Rtype::Complexes,
586        SEXPTYPE::STRSXP => Rtype::Strings,
587        SEXPTYPE::DOTSXP => Rtype::Dot,
588        SEXPTYPE::ANYSXP => Rtype::Any,
589        SEXPTYPE::VECSXP => Rtype::List,
590        SEXPTYPE::EXPRSXP => Rtype::Expressions,
591        SEXPTYPE::BCODESXP => Rtype::Bytecode,
592        SEXPTYPE::EXTPTRSXP => Rtype::ExternalPtr,
593        SEXPTYPE::WEAKREFSXP => Rtype::WeakRef,
594        SEXPTYPE::RAWSXP => Rtype::Raw,
595        #[cfg(not(use_objsxp))]
596        SEXPTYPE::S4SXP => Rtype::S4,
597        #[cfg(use_objsxp)]
598        SEXPTYPE::OBJSXP => Rtype::S4,
599        _ => Rtype::Unknown,
600    }
601}
602
603const PRINTF_NO_FMT_CSTRING: &[std::os::raw::c_char] = &[37, 115, 0]; // same as "%s\0"
604#[doc(hidden)]
605pub fn print_r_output<T: Into<Vec<u8>>>(s: T) {
606    let cs = CString::new(s).expect("NulError");
607    unsafe {
608        extendr_ffi::Rprintf(PRINTF_NO_FMT_CSTRING.as_ptr(), cs.as_ptr());
609    }
610}
611
612#[doc(hidden)]
613pub fn print_r_error<T: Into<Vec<u8>>>(s: T) {
614    let cs = CString::new(s).expect("NulError");
615    unsafe {
616        extendr_ffi::REprintf(PRINTF_NO_FMT_CSTRING.as_ptr(), cs.as_ptr());
617    }
618}
619
620#[cfg(test)]
621mod tests {
622    use super::prelude::*;
623    use crate as extendr_api;
624
625    use extendr_macros::extendr;
626    use extendr_macros::extendr_module;
627    use extendr_macros::pairlist;
628
629    #[extendr]
630    pub fn inttypes(a: i8, b: u8, c: i16, d: u16, e: i32, f: u32, g: i64, h: u64) {
631        assert_eq!(a, 1);
632        assert_eq!(b, 2);
633        assert_eq!(c, 3);
634        assert_eq!(d, 4);
635        assert_eq!(e, 5);
636        assert_eq!(f, 6);
637        assert_eq!(g, 7);
638        assert_eq!(h, 8);
639    }
640
641    #[extendr]
642    pub fn floattypes(a: f32, b: f64) {
643        assert_eq!(a, 1.);
644        assert_eq!(b, 2.);
645    }
646
647    #[extendr]
648    pub fn strtypes(a: &str, b: String) {
649        assert_eq!(a, "abc");
650        assert_eq!(b, "def");
651    }
652
653    #[extendr]
654    pub fn vectortypes(a: Vec<i32>, b: Vec<f64>) {
655        assert_eq!(a, [1, 2, 3]);
656        assert_eq!(b, [4., 5., 6.]);
657    }
658
659    #[extendr]
660    pub fn robjtype(a: Robj) {
661        assert_eq!(a, Robj::from(1))
662    }
663
664    #[extendr]
665    pub fn return_u8() -> u8 {
666        123
667    }
668
669    #[extendr]
670    pub fn return_u16() -> u16 {
671        123
672    }
673
674    #[extendr]
675    pub fn return_u32() -> u32 {
676        123
677    }
678
679    #[extendr]
680    pub fn return_u64() -> u64 {
681        123
682    }
683
684    #[extendr]
685    pub fn return_i8() -> i8 {
686        123
687    }
688
689    #[extendr]
690    pub fn return_i16() -> i16 {
691        123
692    }
693
694    #[extendr]
695    pub fn return_i32() -> i32 {
696        123
697    }
698
699    #[extendr]
700    pub fn return_i64() -> i64 {
701        123
702    }
703
704    #[extendr]
705    pub fn return_f32() -> f32 {
706        123.
707    }
708
709    #[extendr]
710    pub fn return_f64() -> f64 {
711        123.
712    }
713
714    #[extendr]
715    pub fn f64_slice(x: &[f64]) -> &[f64] {
716        x
717    }
718
719    #[extendr]
720    pub fn i32_slice(x: &[i32]) -> &[i32] {
721        x
722    }
723
724    #[extendr]
725    pub fn bool_slice(x: &[Rbool]) -> &[Rbool] {
726        x
727    }
728
729    #[extendr]
730    pub fn f64_iter(x: Doubles) -> Doubles {
731        x
732    }
733
734    #[extendr]
735    pub fn i32_iter(x: Integers) -> Integers {
736        x
737    }
738
739    // #[extendr]
740    // pub fn bool_iter(x: Logicals) -> Logicals {
741    //     x
742    // }
743
744    #[extendr]
745    pub fn symbol(x: Symbol) -> Symbol {
746        x
747    }
748
749    #[extendr]
750    pub fn matrix(x: RMatrix<f64>) -> RMatrix<f64> {
751        x
752    }
753
754    #[extendr]
755    struct Person {
756        pub name: String,
757    }
758
759    #[extendr]
760    /// impl comment.
761    impl Person {
762        fn new() -> Self {
763            Self {
764                name: "".to_string(),
765            }
766        }
767
768        fn set_name(&mut self, name: &str) {
769            self.name = name.to_string();
770        }
771
772        fn name(&self) -> &str {
773            self.name.as_str()
774        }
775    }
776
777    // see metadata_test for the following comments.
778
779    /// comment #1
780    /// comment #2
781    /**
782        comment #3
783        comment #4
784    **/
785    #[extendr]
786    /// aux_func doc comment.
787    fn aux_func(_person: &Person) {}
788
789    // Macro to generate exports
790    extendr_module! {
791        mod my_module;
792        fn aux_func;
793        impl Person;
794    }
795
796    #[test]
797    fn export_test() {
798        test! {
799            use super::*;
800            // Call the exported functions through their generated C wrappers.
801            unsafe {
802                wrap__inttypes(
803                    Robj::from(1).get(),
804                    Robj::from(2).get(),
805                    Robj::from(3).get(),
806                    Robj::from(4).get(),
807                    Robj::from(5).get(),
808                    Robj::from(6).get(),
809                    Robj::from(7).get(),
810                    Robj::from(8).get(),
811                );
812                wrap__inttypes(
813                    Robj::from(1.).get(),
814                    Robj::from(2.).get(),
815                    Robj::from(3.).get(),
816                    Robj::from(4.).get(),
817                    Robj::from(5.).get(),
818                    Robj::from(6.).get(),
819                    Robj::from(7.).get(),
820                    Robj::from(8.).get(),
821                );
822                wrap__floattypes(Robj::from(1.).get(), Robj::from(2.).get());
823                wrap__floattypes(Robj::from(1).get(), Robj::from(2).get());
824                wrap__strtypes(Robj::from("abc").get(), Robj::from("def").get());
825                wrap__vectortypes(
826                    Robj::from(&[1, 2, 3] as &[i32]).get(),
827                    Robj::from(&[4., 5., 6.] as &[f64]).get(),
828                );
829                wrap__robjtype(Robj::from(1).get());
830
831                // General integer types.
832                assert_eq!(Robj::from_sexp(wrap__return_u8()), Robj::from(123_u8));
833                assert_eq!(Robj::from_sexp(wrap__return_u16()), Robj::from(123));
834                assert_eq!(Robj::from_sexp(wrap__return_u32()), Robj::from(123.));
835                assert_eq!(Robj::from_sexp(wrap__return_u64()), Robj::from(123.));
836                assert_eq!(Robj::from_sexp(wrap__return_i8()), Robj::from(123));
837                assert_eq!(Robj::from_sexp(wrap__return_i16()), Robj::from(123));
838                assert_eq!(Robj::from_sexp(wrap__return_i32()), Robj::from(123));
839                assert_eq!(Robj::from_sexp(wrap__return_i64()), Robj::from(123.));
840
841                // Floating point types.
842                assert_eq!(Robj::from_sexp(wrap__return_f32()), Robj::from(123.));
843                assert_eq!(Robj::from_sexp(wrap__return_f64()), Robj::from(123.));
844            }
845        }
846    }
847
848    #[test]
849    fn class_wrapper_test() {
850        test! {
851            let mut person = Person::new();
852            person.set_name("fred");
853            let robj = r!(person);
854            assert_eq!(robj.check_external_ptr_type::<Person>(), true);
855            let person2 = <&Person>::try_from(&robj).unwrap();
856            assert_eq!(person2.name(), "fred");
857        }
858    }
859
860    #[test]
861    fn slice_test() {
862        test! {
863            unsafe {
864                // #[extendr]
865                // pub fn f64_slice(x: &[f64]) -> &[f64] { x }
866
867                let robj = r!([1., 2., 3.]);
868                assert_eq!(Robj::from_sexp(wrap__f64_slice(robj.get())), robj);
869
870                // #[extendr]
871                // pub fn i32_slice(x: &[i32]) -> &[i32] { x }
872
873                let robj = r!([1, 2, 3]);
874                assert_eq!(Robj::from_sexp(wrap__i32_slice(robj.get())), robj);
875
876                // #[extendr]
877                // pub fn bool_slice(x: &[Rbool]) -> &[Rbool] { x }
878
879                let robj = r!([TRUE, FALSE, TRUE]);
880                assert_eq!(Robj::from_sexp(wrap__bool_slice(robj.get())), robj);
881
882                // #[extendr]
883                // pub fn f64_iter(x: Doubles) -> Doubles { x }
884
885                let robj = r!([1., 2., 3.]);
886                assert_eq!(Robj::from_sexp(wrap__f64_iter(robj.get())), robj);
887
888                // #[extendr]
889                // pub fn i32_iter(x: Integers) -> Integers { x }
890
891                let robj = r!([1, 2, 3]);
892                assert_eq!(Robj::from_sexp(wrap__i32_iter(robj.get())), robj);
893
894                // #[extendr]
895                // pub fn bool_iter(x: Logicals) -> Logicals { x }
896
897                // TODO: reinstate this test.
898                // let robj = r!([TRUE, FALSE, TRUE]);
899                // assert_eq!(Robj::from_sexp(wrap__bool_iter(robj.get())), robj);
900
901                // #[extendr]
902                // pub fn symbol(x: Symbol) -> Symbol { x }
903
904                let robj = sym!(fred);
905                assert_eq!(Robj::from_sexp(wrap__symbol(robj.get())), robj);
906
907                // #[extendr]
908                // pub fn matrix(x: Matrix<&[f64]>) -> Matrix<&[f64]> { x }
909
910                let m = RMatrix::new_matrix(1, 2, |r, c| if r == c {1.0} else {0.});
911                let robj = r!(m);
912                assert_eq!(Robj::from_sexp(wrap__matrix(robj.get())), robj);
913            }
914        }
915    }
916
917    #[test]
918    fn r_output_test() {
919        // R equivalent
920        // > txt_con <- textConnection("test_con", open = "w")
921        // > sink(txt_con)
922        // > cat("Hello world")
923        // > sink()
924        // > close(txt_con)
925        // > expect_equal(test_con, "Hello world")
926        //
927
928        test! {
929            let txt_con = R!(r#"textConnection("test_con", open = "w")"#).unwrap();
930            call!("sink", &txt_con).unwrap();
931            rprintln!("Hello world %%!"); //%% checks printf formatting is off, yields one % if on
932            call!("sink").unwrap();
933            call!("close", &txt_con).unwrap();
934            let result = R!("test_con").unwrap();
935            assert_eq!(result, r!("Hello world %%!"));
936        }
937    }
938
939    #[test]
940    fn test_na_str() {
941        assert_ne!(<&str>::na().as_ptr(), "NA".as_ptr());
942        assert_eq!(<&str>::na(), "NA");
943        assert!(!"NA".is_na());
944        assert!(<&str>::na().is_na());
945    }
946
947    #[test]
948    fn metadata_test() {
949        test! {
950            // Rust interface.
951            let metadata = get_my_module_metadata();
952            assert_eq!(metadata.functions[0].doc, " comment #1\n comment #2\n\n        comment #3\n        comment #4\n    *\n aux_func doc comment.");
953            assert_eq!(metadata.functions[0].rust_name, "aux_func");
954            assert_eq!(metadata.functions[0].mod_name, "aux_func");
955            assert_eq!(metadata.functions[0].r_name, "aux_func");
956            assert_eq!(metadata.functions[0].args[0].name, "_person");
957            assert_eq!(metadata.functions[1].rust_name, "get_my_module_metadata");
958            assert_eq!(metadata.impls[0].name, "Person");
959            assert_eq!(metadata.impls[0].methods.len(), 3);
960
961            // R interface
962            let robj = Robj::from_sexp(wrap__get_my_module_metadata());
963            let functions = robj.dollar("functions").unwrap();
964            let impls = robj.dollar("impls").unwrap();
965            assert_eq!(functions.len(), 3);
966            assert_eq!(impls.len(), 1);
967        }
968    }
969
970    #[test]
971    fn pairlist_macro_works() {
972        test! {
973            assert_eq!(pairlist!(1, 2, 3), Pairlist::from_pairs(&[("", 1), ("", 2), ("", 3)]));
974            assert_eq!(pairlist!(a=1, 2, 3), Pairlist::from_pairs(&[("a", 1), ("", 2), ("", 3)]));
975            assert_eq!(pairlist!(1, b=2, 3), Pairlist::from_pairs(&[("", 1), ("b", 2), ("", 3)]));
976            assert_eq!(pairlist!(a=1, b=2, c=3), Pairlist::from_pairs(&[("a", 1), ("b", 2), ("c", 3)]));
977            assert_eq!(pairlist!(a=NULL), Pairlist::from_pairs(&[("a", ())]));
978            assert_eq!(pairlist!(), Pairlist::from(()));
979        }
980    }
981
982    #[test]
983    fn big_r_macro_works() {
984        test! {
985            assert_eq!(R!("1")?, r!(1.0));
986            assert_eq!(R!(r"1")?, r!(1.0));
987            assert_eq!(R!(r"
988                x <- 1
989                x
990            ")?, r!(1.0));
991            assert_eq!(R!(r"
992                x <- {{ 1.0 }}
993                x
994            ")?, r!(1.0));
995            assert_eq!(R!(r"
996                x <- {{ (0..4).collect_robj() }}
997                x
998            ")?, r!([0, 1, 2, 3]));
999            assert_eq!(R!(r#"
1000                x <- "hello"
1001                x
1002            "#)?, r!("hello"));
1003            assert_eq!(Rraw!(r"
1004                x <- {{ 1 }}
1005                x
1006            ")?, r!(1.0));
1007        }
1008    }
1009}