MRPT  2.0.1
Classes | Modules | Functions
[mrpt-serialization]

Detailed Description

Serialization (marshalling) portable library for C++ objects persistence.

Library `mrpt-serialization`

[New in MRPT 2.0.0]

This library is part of MRPT and can be installed in Debian-based systems with:

    sudo apt install libmrpt-serialization-dev

See: Using MRPT from your CMake project

Binary serialization (most efficient)

Main classes and concepts associated with this library:

Serialization happens via archive << object operators in all cases but, underneath, two mechanisms are provided:

Support for STL containers is provided via this "direct mechanism" for the container structure itself, but contained elements can use any of the serialization mechanisms.

Serializing shared_ptr<T> is supported for any arbitrary type T. It is legal to serialize an empty (nullptr) smart pointer; an empty pointer will be read back. Polymorphic classes can be also writen and read, although reading a smart pointer to a polymorphic base class is only supported for classes derived from MRPT's CSerializable, since that operation requires registering types in a class factory (see mrpt_rtti_grp and mrpt::serialization::CSerializable).

Example #1: serialize STL container via MRPT `CStream`s

See: serialization_stl/test.cpp

#include <iostream> // cout
{
// Declare data to be serialized:
std::map<std::string, uint32_t> m1{{"one", 1}, {"two", 2}};
// === Write ===
{
// CStream output:
mrpt::io::CFileOutputStream ofs("file.bin");
auto arch_out = mrpt::serialization::archiveFrom(ofs);
// Use << to serialize in binary form:
arch_out << m1;
}
// === Read ===
std::map<std::string, uint32_t> m2;
{
// CStream output:
mrpt::io::CFileInputStream ifs("file.bin");
auto arch_in = mrpt::serialization::archiveFrom(ifs);
// Use >> to deserialize:
arch_in >> m2;
}
std::cout << "Wrote: ";
printMap(m1);
std::cout << "Read : ";
printMap(m2);
}

Output:

Wrote: one=1, two=2,
Read: one=1, two=2,

Example #2: serialize STL container via `std::ostream` and `std::istream`

See: serialization_stl/test.cpp

#include <fstream> // io std streams
#include <iostream> // cout
{
// Declare data to be serialized:
std::map<std::string, uint32_t> m1{{"one", 1}, {"two", 2}};
// === Write ===
{
// CStream output:
std::ofstream ofs("file.bin");
auto arch_out = mrpt::serialization::archiveFrom<std::ostream>(ofs);
// Use << to serialize in binary form:
arch_out << m1;
}
// === Read ===
std::map<std::string, uint32_t> m2;
{
// CStream output:
std::ifstream ifs("file.bin");
auto arch_in = mrpt::serialization::archiveFrom<std::istream>(ifs);
// Use >> to deserialize:
arch_in >> m2;
}
std::cout << "Wrote: ";
printMap(m1);
std::cout << "Read : ";
printMap(m2);
}

Output:

Wrote: one=1, two=2,
Read: one=1, two=2,

Example #3: Serialization of existing MRPT classes

Write me!

Example #4: Polymorphic serialization of user classes

Write me!

Schema (plain-text) serialization (human readable)

An alternative mechanism to serialize objects is based on mrpt::serialization::CSchemeArchive and allow objects to be (de)serialized in plain text formats like XML, JSON, YAML, etc. For now (Aug 2018) only JSON is implemented.

Example #1: Easy JSON serialization

This method only requires having MRPT built against jsoncpp, but does not enforce the user to also depend on that library.

See: serialization_json_example/test.cpp

#include <iostream> // cout
{
// Define the MRPT objects to be serialized:
// --------------------
// JSON Serialization
// --------------------
// Create a JSON archive:
// Writes the objects to the JSON archive:
arch["pose_pdf"] = pdf1;
arch["pose"] = p1;
// Writes the JSON representation to an std::ostream
std::stringstream ss;
ss << arch;
// also, print to cout for illustration purposes:
std::cout << arch << std::endl;
// --------------------
// JSON Deserialization
// --------------------
// rewind stream for reading from the start
ss.seekg(0);
// Create a new JSON archive for reading
// Load the plain text representation into the archive:
ss >> arch2;
// Parse the JSON data into an MRPT object:
arch2["pose_pdf"].readTo(pdf2);
arch2["pose"].readTo(p2);
std::cout << "read pose:" << p2.asString() << std::endl;
}

Output:

{
"pose" :
{
"datatype" : "CPose2D",
"phi" : 0,
"version" : 1,
"x" : 5,
"y" : 6
},
"pose_pdf" :
{
"cov" :
{
"data" : "[0.000000e+00 0.000000e+00 0.000000e+00 ;0.000000e+00 0.000000e+00 0.000000e+00 ;0.000000e+00 0.000000e+00 0.000000e+00 ]",
"datatype" : "CMatrixD",
"ncols" : 3,
"nrows" : 3,
"version" : 1
},
"datatype" : "CPosePDFGaussian",
"mean" :
{
"datatype" : "CPose2D",
"phi" : 1.5707963267948966,
"version" : 1,
"x" : 1,
"y" : 2
},
"version" : 1
}
}
read pose:[5.000000 6.000000 0.000000deg]

Example #2: JSON serialization with full access to jsoncpp

If you want to have full control on the JSON formatting and other details, you may directly depend on jsoncpp and use the following, template-based access to MRPT serialization:

See: serialization_json_example/test.cpp

#include <json/json.h>
void test()
{
Json::Value val;
std::make_unique<CSchemeArchive<Json::Value>>(val));
mrpt::poses::CPose2D pt1{1.0, 2.0, 3.0};
// Store any CSerializable object into the JSON value:
arch = pt1;
// Alternative:
// arch["pose"] = pt1;
std::stringstream ss;
ss << val;
std::cout << val << std::endl;
}
Collaboration diagram for [mrpt-serialization]:

Classes

class  mrpt::serialization::CArchive
 Virtual base class for "archives": classes abstracting I/O streams. More...
 
class  mrpt::serialization::CMessage
 A class that contain generic messages, that can be sent and received from a "CClientTCPSocket" object. More...
 
class  mrpt::serialization::CSchemeArchive< SCHEME_CAPABLE >
 Base template class for schema-capable "archives", e.g. More...
 
class  mrpt::serialization::CSchemeArchiveBase_impl
 Pure virtual class carrying the implementation of CSchemeArchiveBase as per the PIMPL idiom. More...
 
class  mrpt::serialization::CSchemeArchiveBase
 Virtual base class for "schematic archives" (JSON, XML,...) More...
 
class  mrpt::serialization::CSerializable
 The virtual base class which provides a unified interface for all persistent objects in MRPT. More...
 

Modules

 Non-CStream serialization functions (in
 #include <mrpt/serializatin/CSerializable.h>)
 

Functions

CSchemeArchiveBase mrpt::serialization::archiveJSON ()
 Returns an archive for reading/writing in JSON format. More...
 

Function Documentation

◆ archiveJSON()

CSchemeArchiveBase mrpt::serialization::archiveJSON ( )

Returns an archive for reading/writing in JSON format.

This feature requires compiling MRPT with jsoncpp support. See [mrpt-serialization] for examples of use.

Examples:
serialization_json_example/test.cpp.

Definition at line 23 of file CSchemeArchive.cpp.

References THROW_EXCEPTION.




Page generated by Doxygen 1.8.14 for MRPT 2.0.1 Git: 0fef1a6d7 Fri Apr 3 23:00:21 2020 +0200 at vie abr 3 23:20:28 CEST 2020