Git Product home page Git Product logo

rcpp's Introduction

Rcpp: Seamless R and C++ Integration

CI License CRAN Dependencies Coverage Status Debian package r-universe Last Commit Downloads (monthly) Downloads (total) CRAN use CRAN indirect BioConductor use JSS Springer useR! TAS

Synopsis

The Rcpp package integrates R and C++ via R functions and a (header-only) C++ library.

All underlying R types and objects, i.e., everything a SEXP represents internally in R, are matched to corresponding C++ objects. This covers anything from vectors, matrices or lists to environments, functions and more. Each SEXP variant is automatically mapped to a dedicated C++ class. For example, numeric vectors are represented as instances of the Rcpp::NumericVector class, environments are represented as instances of Rcpp::Environment, functions are represented as Rcpp::Function, etc ... The Rcpp-introduction vignette (now published as a TAS paper; an earlier introduction was also published as a JSS paper provides a good entry point to Rcpp as do the Rcpp website, the Rcpp page and the Rcpp Gallery. Full documentation is provided by the Rcpp book.

Other highlights:

  • The conversion from C++ to R and back is driven by the templates Rcpp::wrap and Rcpp::as which are highly flexible and extensible, as documented in the Rcpp-extending vignette.

  • Rcpp also provides Rcpp modules, a framework that allows exposing C++ functions and classes to the R level. The Rcpp-modules vignette details the current set of features of Rcpp-modules.

  • Rcpp includes a concept called Rcpp sugar that brings many R functions into C++. Sugar takes advantage of lazy evaluation and expression templates to achieve great performance while exposing a syntax that is much nicer to use than the equivalent low-level loop code. The Rcpp-sugar gives an overview of the feature.

  • Rcpp attributes provide a high-level syntax for declaring C++ functions as callable from R and automatically generating the code required to invoke them. Attributes are intended to facilitate both interactive use of C++ within R sessions as well as to support R package development. Attributes are built on top of Rcpp modules and their implementation is based on previous work in the inline package. See the Rcpp-atttributes vignettes for more details.

Documentation

The package ships with ten pdf vignettes, including a recent introduction to Rcpp now published as a paper in TAS (and as a preprint in PeerJ). Also available is an earlier introduction which was published as a JSS paper.

Among the other vignettes are the Rcpp FAQ and the introduction to Rcpp Attributes. Additional documentation is available via the Rcpp book by Eddelbuettel (2013, Springer); see 'citation("Rcpp")' for details.

Performance

Rcpp follows the C++ motto of "you pay only for what you use" and imposes no run-time performance penalty: Rcpp outperforms related packages in direct comparison, see for example this repo for details.

Compile-time performance can be tuned by selecting components. But it is also worth noting that use of ccache will (strongly) dominate all such possible component choices, we have previously recommended its use.

Examples

The Rcpp Gallery showcases over one hundred fully documented and working examples. The package RcppExamples contains a few basic examples covering the core data types.

A number of examples are included, as are well over one thousand unit tests which provide additional usage examples.

An earlier version of Rcpp, containing what we now call the 'classic Rcpp API' was written during 2005 and 2006 by Dominick Samperi. This code has been factored out of Rcpp into the package RcppClassic, and it is still available for code relying on the older interface. New development should always use this Rcpp package instead.

Other usage examples are provided by packages using Rcpp. As of early January 2024, there are 2791 CRAN packages using Rcpp (corresponding to 13.8% of all packages, and 59.9% of packages containing compiled code), a further 254 BioConductor packages in its current release as well as an unknown number of GitHub, Bitbucket, R-Forge, ... repositories using Rcpp. All these packages provide usage examples for Rcpp. The package is in widespread use and has been downloaded over 78.1 million times (per the partial logs from the cloud mirrors of CRAN).

Installation

CRAN

Rcpp released on CRAN are carefully tested and curated. CRAN ensures they interoperate with all other CRAN package on all test environment. The released and tested versions are available via all mirrors of CRAN network, and can be installed from within R via

install.packages("Rcpp")

Release Candidates

For the last several releases, we also made interim candidate releases available on the Rcpp Drat Repo. Versions from a drat repo can be installed either by just temporarily setting the drat repo as in

install.packages("Rcpp", repos="https://RcppCore.github.io/drat")

or by setting a drat repo more permanently (as described in the documentation of the drat package).

Testing the release candidates prior to actual release help. Please run this if you can.

Source

To install from source, ensure you have a complete package development environment for R as discussed in the relevant documentation; also see questions 1.2 and 1.3 in the Rcpp-FAQ.

Less Common Versions and Platforms

If you want to run Rcpp on another (not-tested on CRAN) platform, or on releases older than the previous release, we suggest you do your due diligence and test accordingly. Rcpp is provided by an all-volunteer team with finite resources. We work hard to test Rcpp with several thousand CRAN packages using it---but we cannot test on outdated versions of R or your OS.

Support

The best place for questions is the Rcpp-devel mailing list hosted at R-forge. Note that in order to keep spam down, you must be a subscriber in order to post. One can also consult the list archives to see if your question has been asked before.

Another option is to use StackOverflow and its 'rcpp' tag. Search functionality (use rcpp in squared brackets as in [rcpp] my question terms to tag the query) is very valuable as many questions have indeed been asked, and answered, before.

The issue tickets at the GitHub repo are the primary bug reporting interface. As with the other web resources, previous issues can be searched as well.

Authors

Dirk Eddelbuettel, Romain Francois, JJ Allaire, Kevin Ushey, Qiang Kou, Nathan Russell, Iñaki Ucar, Doug Bates, and John Chambers

License

GPL (>= 2)

rcpp's People

Contributors

artemklevtsov avatar cauthmann avatar coatless avatar dcdillon avatar dmbates avatar eddelbuettel avatar ellert avatar enchufa2 avatar filipsch avatar jeroen avatar jimhester avatar jjallaire avatar johnmchambers avatar jpritikin avatar kevinushey avatar krlmlr avatar lionel- avatar luckyrandom avatar mattpd avatar mlysy avatar nathan-russell avatar pkrog avatar renkun-ken avatar romainfrancois avatar rstub avatar stephematician avatar traversc avatar waltersom avatar wush978 avatar yixuan avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

rcpp's Issues

logical indexing

logical indexing, ie NumericVector[ LogicalVector ].

We should flip the problem and delegate the responsability of extracting to a class. For example do something like this;

template <typename T>
Extractor<Vector,T> operator[]( const T& x) ;

So that we define the meaning in a separate class Extractor or something. This way we would just have to redefine Extractor when we want to handle a new extractor type.

Rcpp::Factor

A factor is not much more than an IntegerVector with a labels attribute. We should have a special class like Rcpp::Factor to deal with it.

In particular, operator[](int) should return a proxy that knows how to handle strings and integers.

Make Rcpp header only

We can't really achieve header only, but we can achieve that what the client package sees is only headers. So that we no longer need linking against the Rcpp library, which makes this library useless.

I did this in Rcpp11

Reimplement get_last_call with contexts

inline SEXP get_last_call(){
    SEXP sys_calls_symbol = Rf_install( "sys.calls" ) ;
    Shield<SEXP> sys_calls_expr = Rf_lang1(sys_calls_symbol);   
    Shield<SEXP> calls = Rf_eval( sys_calls_expr, R_GlobalEnv ) ;
    SEXP res = calls ;
    while( !Rf_isNull(CDR(res)) ) res = CDR(res); 
    return CAR(res) ;
}

We can do this with contexts instead, e.g. rJava does it

Better empty data frame impl

        inline SEXP empty_data_frame(){
            SEXP dataFrameSym = ::Rf_install( "data.frame");
            return ::Rf_eval( ::Rf_lang1( dataFrameSym ), R_GlobalEnv ) ;       
        }

we can do better

More flexible attributes

It would be useful for packages to be able to extend attributes. Package foo could register a foo::bar attribute to do something about a function, a class, whatever ...

I have one use case in mind for this in dplyr where it would be nice to be able to register hybrid handlers as:

// [[dplyr::handler(hitchhiker)]]
Result* hitchhiker_handler( SEXP, const LazySubsets&, int ){
    return new Hitchhiker ;        
}

See the hybrid evaluation vignette for context.

statistical distribution functions

other statistical distribution functions:

multinom : this only has dmultinom which is handled in R, so
maybe we can skip it

    signrank : has the weird call to .C( "signrank_free" ), need
to understand that

    wilcox : has the weird call to .C( "wilcox_free" ), need to
understand that

    tukey : only has p and q, no r or d

should rep be lazy

not sure rep should be lazy, i.e. rep( x, 4 ) fetches x[i] 4 times,
maybe we should use LazyVector like in outer to somehow cache the
result when it is judged expensive to calculate

Fast indexing

The TODO had:

Fast indexing and g++ 4.5.0 or later: open issue of why this compiler
gets upset when the previous version(s) coped just fine

Are we still using this fast indexing we mention there. Is this still an issue ?

Skip callback in string_to_try_error

inline SEXP string_to_try_error( const std::string& str){
    using namespace Rcpp;

    Shield<SEXP> simpleErrorExpr = Rf_lang2(::Rf_install("simpleError"), Rf_mkString(str.c_str()));
    Shield<SEXP> simpleError = Rf_eval(simpleErrorExpr, R_GlobalEnv);
    Shield<SEXP> tryError = Rf_mkString( str.c_str() ) ;
    Rf_setAttrib( tryError, R_ClassSymbol, Rf_mkString("try-error") ) ; 
    Rf_setAttrib( tryError, Rf_install( "condition") , simpleError ) ; 

    return tryError;
}

The only reason we call R's simpleError is to deal with the call attribute. There is probably a better and less expensive way to handle that.

Redesign time and date classes

Current classes DateVector and DatetimeVector should be redesigned into something that feels more like Rcpp's api, i.e. hook back to the internal numeric vector instead of having its own memory.

We might be able to keep Date and Datetime as proxy objects but a DateVector should not be a std::vector<Date> as it currently is.

random number generators

other random generators:

    rmultinom : tricky because it generates a matrix

    rnbeta : the R version is implemented in R (not in C), 
    should we still have it in Rcpp in compile code ?

    rnf : idem

    rnt : idem

tests are run twice when R CMD check

This is a ridiculous consequence of having the unit test vignette.

* checking tests ...
  Running ‘doRUnit.R’
* checking running R code from vignettes ...
   ‘Rcpp-attributes.Rnw’ ... OK
   ‘Rcpp-extending.Rnw’ ... failed
   ‘Rcpp-FAQ.Rnw’ ... failed
   ‘Rcpp-modules.Rnw’ ... OK
   ‘Rcpp-package.Rnw’ ... OK
   ‘Rcpp-quickref.Rnw’ ... OK
   ‘Rcpp-sugar.Rnw’ ... OK
   ‘Rcpp-introduction.Rnw’ ... OK
   ‘Rcpp-unitTests.Rnw’ ...

We need to dump Rcpp-unitTests.Rnw.

64 bit integers

From Murray:

A vector of 64-bit integers in C++ code should be either returned as

  1. An integer vector (if all values are < INT_MAX in the C code) corresponding to R's integer type.

  2. A numeric vector (if all values are < 1L << 53 such that they can be stored precisely in a double without losing any digits of precision) corresponding to R's numeric type.

  3. A vector of strings (if at least 1 value > 1L << 53 such that returning a numeric would lose precision in the result. e.g. 64-bit fingerprints, userids, network addresses or other things can not be stored in a numeric accurately.

Sorry no patch, I work around this in my application code currently before calling Rcpp::wrap().

BH

Can we use BH in Rcpp ?

This would give us a few things from boost we would no longer have to reinvent.

This would give us something better than RCPP_UNORDERED_MAP macro and all the dispatch it is involved with. We could just use boost::unordered_map instead

XPtr<void>

Because void& does not make sense, we need a specialization of XPtr<void>

NameProxy const ness

This is bad:

    inline NameProxy operator[]( const std::string& name ) const {
        return NameProxy( const_cast<Vector_Impl&>(*this), name ) ;
    }
    inline NameProxy operator()( const std::string& name ) const {
        return NameProxy( const_cast<Vector_Impl&>(*this), name ) ;
    }

We should have a const_NameProxy class and avoid doing const_cast

recycling

recycling : binary operators and math functions of 2 or more arguments
need to recycle their arguments.

Reference::update

        void update( SEXP x){
            // TODO: check that x is of a reference class
            if( ! ::Rf_isS4(x) ) throw not_reference() ;
        }

@johnmchambers is there a test for "is this a reference class object"

Update documentation for github repo

R-Forge is mentioned in DESCRIPTION, vignettes and more:

edd@max:~/svn/rcpp/pkg/Rcpp$ grep -lr r-forge 
tests/doRUnit.R
inst/announce/ANNOUNCE-0.10.0.txt
inst/announce/ANNOUNCE-0.6.0.txt
inst/announce/ANNOUNCE-0.8.0.txt
inst/announce/ANNOUNCE-0.9.0.txt
DESCRIPTION
debian/copyright
vignettes/Rcpp-FAQ.Rnw
vignettes/rcpp.index.html
ChangeLog
edd@max:~/svn/rcpp/pkg/Rcpp$ 

2 argument .property() doesn't seem to compile

In setting up inherited read-only fields in classModule(), I seemed to get C++ compile errors from a .poperty() w/o either a setter or a document string.

The workaround was to generate a trivial document string, which seems to work fine.

E.g., I generate a line in one example:

.property("size", &module_PopCount_NS::field_size_get, "read-only field")

If I delete the string argument, compile of the resulting .cpp file fails with:

PopCountModule.cpp: In function 'void rcpp_module_class_PopCount_init()':
PopCountModule.cpp:21: error: no matching function for call to 'Rcpp::class
::property(const char [5], std::vector<long int, std::allocator > ()(PopCount))'
make: *** [PopCountModule.o] Error 1

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.