README

This package provides R with access to cereal header files. cereal is a header-only C++11 serialization library. cereal takes arbitrary data types and reversibly turns them into different representations, such as compact binary encodings, XML, or JSON.

Installation

Latest release

install.packages('Rcereal')

Development version

Use remotes::install_github to install the latest version of Rcereal. Optionally: use Rcereal::update_version to over-write the header files in the R library with a version from https://github.com/USCiLab/cereal.

remotes::install_github("wush978/Rcereal")
Rcereal::update_version() # optional

Usage

See the official cereal Quick Start guide for further details about using cereal in C++11.

Using cpp11

The following example shows how to use Rcereal alongside cpp11 to serialize and deserialize a user-defined struct using raw vectors:

// path/to/example.cpp
#include <sstream>

#include <cpp11/raws.hpp>

#include <cereal/archives/binary.hpp>

struct MyClass
{
    int x, y, z;
  // This method lets cereal know which data members to serialize
    template<class Archive>
    void serialize(Archive & archive)
    {
        archive( x, y, z ); // serialize things by passing them to the archive
    }
};

[[cpp11::linking_to("Rcereal")]]
[[cpp11::register]]
cpp11::raws serialize_myclass(int x = 1, int y = 2, int z = 3) {
    MyClass my_instance { x, y, z };
    std::stringstream ss;
    {
        cereal::BinaryOutputArchive oarchive(ss); // Create an output archive
        oarchive(my_instance);
    }
    ss.seekg(0, ss.end);
    cpp11::writable::raws result(ss.tellg());
    ss.seekg(0, ss.beg);
    std::copy(std::istreambuf_iterator<char>{ss},
              std::istreambuf_iterator<char>(),
              result.begin());
    return result;
}

[[cpp11::register]]
void deserialize_myclass(cpp11::raws src) {
    std::stringstream ss;
    std::copy(src.cbegin(), src.cend(), std::ostream_iterator<char>(ss));
    MyClass my_instance;
    {
        cereal::BinaryInputArchive iarchive(ss); // Read from input archive
        iarchive(my_instance);
    }
    Rprintf("%i,%i,%i\n", my_instance.x, my_instance.y, my_instance.z);
}

cpp11::cpp_source(file='path/to/example.cpp')
raw_vector <- serialize_myclass(1, 2, 4)
deserialize_myclass(raw_vector)

Using Rcpp

The following example shows how to use Rcereal alongside Rcpp to serialize and deserialize a user-defined struct using raw vectors:

// path/to/example.cpp

//[[Rcpp::depends(Rcereal)]]
#include <sstream>

#include <cereal/archives/binary.hpp>

#include <Rcpp.h>
using namespace Rcpp;

struct MyClass
{
    /* same as cpp11 example above */
};

//[[Rcpp::export]]
Rcpp::RawVector serialize_myclass(int x = 1, int y = 2, int z = 3) {
    MyClass my_instance { x, y, z };
    std::stringstream ss;
    {
        cereal::BinaryOutputArchive oarchive(ss); // Create an output archive
        oarchive(my_instance);
    }
    ss.seekg(0, ss.end);
    Rcpp::RawVector result(ss.tellg());
    ss.seekg(0, ss.beg);
    ss.read(reinterpret_cast<char*>(&result[0]), result.size());
    return result;
}

//[[Rcpp::export]]
void deserialize_myclass(Rcpp::RawVector src) {
    std::stringstream ss;
    ss.write(reinterpret_cast<char*>(&src[0]), src.size());
    ss.seekg(0, ss.beg);
    MyClass my_instance;
    {
        cereal::BinaryInputArchive iarchive(ss);
        iarchive(my_instance);
    }
    Rcpp::Rcout << my_instance.x << "," << my_instance.y << "," <<
        my_instance.z << std::endl;
}

Rcpp::sourceCpp("path/to/example.cpp")
raw_vector <- serialize_myclass(1, 2, 4)
deserialize_myclass(raw_vector)

Troubleshooting

C++11 may not be enabled by default for some compilers, if not; ensure that PKG_CXXFLAGS contains -std=c++11, e.g. if you use pkgbuild::compile_dll() to build a package (similarly for devtools::build):

withr::with_makevars(c("PKG_CXXFLAGS"="std=c++11"),
                     pkgbuild::compile_dll(),
                     assignment="+=")

If the compiler reports missing header files, try Rcereal::update_version() to update the content of cereal from GitHub. Check that a directory named cereal is in the folder system.file("include", package = "Rcereal").

Rcereal: cereal headers for R and C++ serialization