Detailed Description

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

Back to list of all libraries | See all modules

Library <tt>mrpt-serialization</tt>

[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

Main classes and concepts associated with this library:

mrpt::serialization::CArchive provides:
- An abstraction of I/O streams (e.g. std::stream's, MRPT's mrpt::io::CStream's, sockets)
- A portable API (endianness aware) for serialization of data structures on those streams.
mrpt::serialization::CSerializable provides:
- A generic way to define persistent C++ classes.
- Versioning: if class fields are added or removed, you'll still be able to read old data files.

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

Direct overloading of the <</>> operators for mrpt::serialization::CArchive objects.
- Pros: concise declaration (just the two operator functions).
- Cons: Cannot handle versioning. Cannot deserialize unknown types (i.e. no support for class factory).
Via mrpt::serialization::CSerializable and associated macros:
- Pros: Allows polymorphic classes to be (de)serialized. Allows versioning.
- Cons: Requires adding macros to class definitions. Requires registering the class with [mrpt-rtti].

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 <tt>CStream</tt>s

See: serialization_stl/test.cpp

#include <mrpt/serialization/stl_serialization.h>
#include <mrpt/serialization/CArchive.h>
#include <mrpt/io/CFileInputStream.h>
#include <mrpt/io/CFileOutputStream.h>
 
#include <iostream>  // cout
 
void WriteAndReadExample()
{
        // 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 <tt>std::ostream</tt> and <tt>std::istream</tt>

See: serialization_stl/test.cpp

#include <mrpt/serialization/stl_serialization.h>
#include <mrpt/serialization/CArchive.h>
#include <mrpt/serialization/archiveFrom_std_streams.h>
#include <fstream>  // io std streams
 
#include <iostream>  // cout
 
void WriteAndReadExampleStdIO()
{
        // 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