[mrpt-serialization]

Detailed Description

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

Back to list of all libraries | See all modules

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

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 CStreams

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 std::ostream and std::istream

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

Write me!

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::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>)