Binary Serialization using Cereal

Often, we need to convert our C++ objects into a form that can be stored or transported outside of our program.

For example, we may want to save the state of our objects onto a hard drive, so our program can recover it when it is reopened later.

Or we may want to send the state of our objects to another instance of our program, running on another machine, over the internet. This allows our users to collaborate on projects, or to share the same world in a multiplayer game.

Serialization is the process of converting our objects into a format that can be stored or transmitted. Our previous lessons had examples of this using JSON. Here, we’ll focus on binary serialization.

Installing Cereal

For this lesson, we’ll be using the cereal library, which is a popular choice for binary serialization. The cereal homepage is available here.

We can install cereal using our preferred method. In a previous lesson, we covered vcpkg, a C++ package manager that makes library installation easier.

Installing vcpkg on Windows

An introduction to C++ package managers, and a step-by-step guide to installing vcpkg on Windows and Visual Studio.

Users of vcpkg can install cereal using this command:

1.\vcpkg install cereal

Cereal reads and writes the serialized data to streams, so this lesson is building on previous lessons, where we covered those concepts.

In the following examples, we’ll be using file streams, which we’ll assume readers are already familiar with. We have dedicated lessons on the file system and file streams earlier in the course:

Working with the File System

Create, delete, move, and navigate through directories and files using the standard library's filesystem module.

File Streams

A detailed guide to reading and writing files in C++ using the standard library’s fstream type

1// Suppress compilation errors
2#define _SILENCE_CXX23_ALIGNED_STORAGE_DEPRECATION_WARNING
3
4// Cereal includes must come after
5#include <cereal/archives/binary.hpp>
6#include <cereal/types/memory.hpp>
7
8int main() {
9  // ...
10}

Cereal Archives

The key objects within cereal that manage the serialization and deserialization process are called archives. Archives have a direction:

• Output archives are for serializing our C++ objects, and then sending that data to an output stream
• Input archives are for reading data from an input stream, and then deserializing it to create C++ objects

Cereal supports a few options for the data format we want to use, including binary, XML, JSON, and the ability to define our own. In this lesson, we’ll focus on binary serialization.

We #include archives from the cereal/archives directory.

Let's start by creating a binary output archive, which will send data to an output file stream:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3
4int main() {
5  std::ofstream File{"SaveFile"};
6  cereal::BinaryOutputArchive OArchive(File);
7}

Archives are callable, which is how we use them to serialize our data:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3
4int main() {
5  std::ofstream File{"SaveFile"};
6  cereal::BinaryOutputArchive OArchive(File);
7
8  int SomeInt{42};
9  float SomeFloat{3.14f};
10  bool SomeBoolean{true};
11
12  OArchive(SomeInt, SomeFloat, SomeBoolean);
13}

After running this code, we should have our three objects serialized to a file on our hard drive. Remember, binary data is not intended to be human-readable, so the contents of this file will likely appear to be junk.

But, we can deserialize it back into our application, to ensure everything is working correctly. Note, in the following example, our file stream is now an input stream, and our cereal archive is now an input archive:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3#include <iostream>
4
5int main() {
6  std::ifstream File{"SaveFile"};
7  cereal::BinaryInputArchive IArchive(File);
8
9  int SomeInt;
10  float SomeFloat;
11  bool SomeBoolean;
12
13  IArchive(SomeInt, SomeFloat, SomeBoolean);
14
15  std::cout << "SomeInt: " << SomeInt;
16  std::cout << "\nSomeFloat: " << SomeFloat;
17  std::cout << "\nSomeBoolean: "
18            << std::boolalpha << SomeBoolean;
19}

1SomeInt: 42
2SomeFloat: 3.14
3SomeBoolean: true

Archives Behave like Streams

We do not need to create our entire archive as a single expression. We can build our archives up over time:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3
4int main() {
5  std::ofstream File{"SaveFile"};
6
7  cereal::BinaryOutputArchive OArchive(File);
8
9  int SomeInt{42};
10  OArchive(SomeInt);
11
12  float SomeFloat{3.14f};
13  OArchive(SomeFloat);
14
15  bool SomeBoolean{true};
16  OArchive(SomeBoolean);
17}

Under the hood, they behave as streams. We can imagine them having an internal position, that advances on every invocation, ensuring our new data gets appended to the end.

This concept also applies when reading data from archives - we can do so incrementally. Every argument we pass to the archive’s () operator will be updated, and then an internal pointer is advanced.

As a result, the next time we call it, we get the next piece of data:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3#include <iostream>
4
5int main() {
6  std::ifstream File{"SaveFile"};
7
8  cereal::BinaryInputArchive IArchive(File);
9
10  int SomeInt;
11  IArchive(SomeInt);
12  std::cout << "SomeInt: " << SomeInt;
13
14  float SomeFloat;
15  IArchive(SomeFloat);
16  std::cout << "\nSomeFloat: " << SomeFloat;
17
18  bool SomeBoolean;
19  IArchive(SomeBoolean);
20  std::cout << "\nSomeBoolean: "
21            << std::boolalpha << SomeBoolean;
22}

1SomeInt: 42
2SomeFloat: 3.14
3SomeBoolean: true

Because of this, we need to be mindful of how data is ordered in our streams. We should deserialize data in the same order we serialized it, or we’ll get crashes and unpredictable behavior:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3
4int main() {
5  // Serialize
6  {
7    std::ofstream File{"SaveFile"};
8
9    cereal::BinaryOutputArchive OArchive(File);
10
11    int SomeInt{42};
12    float SomeFloat{3.14f};
13
14    OArchive(SomeInt, SomeFloat);
15  }
16
17  // Deserialize
18  {
19    std::ifstream File{"SaveFile"};
20
21    cereal::BinaryInputArchive IArchive(File);
22
23    int SomeInt;
24    float SomeFloat;
25
26    // Order has changed
27    IArchive(SomeFloat, SomeInt);
28
29    std::cout << "SomeInt: " << SomeInt;
30    std::cout << "\nSomeFloat: " << SomeFloat;
31  }
32}

1SomeInt: 1078523331
2SomeFloat: 5.88545e-44

Serializing Standard Library Types

When dealing with more complex types, we need to define functions that describe how objects of that type will be serialized.

For most standard library types, Cereal has already done that for us. All we need to do is #include appropriate files, contained within the cereal/types directory.

For example, we can serialize std::string and std::vector objects by including string.hpp and vector.hpp respectively:

1#include <cereal/archives/binary.hpp>
2#include <cereal/types/string.hpp>
3#include <cereal/types/vector.hpp>
4#include <fstream>
5
6int main() {
7  std::ofstream File{"SaveFile"};
8
9  cereal::BinaryOutputArchive OArchive(File);
10
11  std::vector SomeInts{1, 2, 3};
12  std::string SomeString{"Hello"};
13
14  OArchive(SomeInts, SomeString);
15}

We also #include them when we need to deserialize:

1#include <cereal/archives/binary.hpp>
2#include <cereal/types/string.hpp>
3#include <cereal/types/vector.hpp>
4#include <fstream>
5
6int main() {
7  std::ifstream File{"SaveFile"};
8
9  cereal::BinaryInputArchive IArchive(File);
10
11  std::vector<int> SomeInts;
12  std::string SomeString;
13
14  IArchive(SomeInts, SomeString);
15
16  std::cout << "SomeInts: ";
17  for (auto i : SomeInts) {
18    std::cout << i << ", ";
19  }
20  std::cout << "\nSomeString: " << SomeString;
21}

1SomeInts: 1, 2, 3,
2SomeString: Hello

Needing to know what type of data is on an archive before we deserialize it may seem problematic. But in practice, it tends not to be an issue.

As we’ll see, we tend to keep serialization and deserialization code within the same file, so we’re already including the required files anyway,

Serializing User-Defined Types

To add Cereal support to our custom types, we need to provide functions for serializing and deserializing them.

These functions are called save and load respectively, and they receive a reference to the archive we need to save or load our object from. The save function must be const.

Typically, the archive will be a templated type for these functions, to allow them to work across different archive types.

Remember, we may need additional #include directives to support the types we’re serializing and deserializing. In the following example, we’re serializing a std::string, so we need to include cereal/types/string.hpp:

1// Character.h
2#pragma once
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  std::string Name;
8  int Level;
9
10  template <class Archive>
11  void save(Archive& Output) const {
12    Output(Name, Level);
13  }
14
15  template <class Archive>
16  void load(Archive& Input) {
17    Input(Name, Level);
18  }
19};

Typically, we don’t want these functions to be part of the public API of our classes.

We can make them private, and give cereal access by including cereal/access.hpp, and then have our class befriend cereal::access:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  std::string Name;
8  int Level;
9
10 private:
11  friend class cereal::access;
12  template <class Archive>
13  void save(Archive& Output) const {
14    Output(Name, Level);
15  }
16
17  template <class Archive>
18  void load(Archive& Input) {
19    Input(Name, Level);
20  }
21};

Friend Classes and Functions

An introduction to the friend keyword, which allows classes to give other objects and functions enhanced access to its members

The Combined serialize() Function

In this example, and many cases, the code in our save and load functions is effectively the same. Cereal allows us to create a combined serialize function to simplify things in scenarios like this:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  std::string Name;
8  int Level;
9
10 private:
11  friend class cereal::access;
12  template <class Archive>
13  void serialize(Archive& Data) {
14    Data(Name, Level);
15  }
16};

Now, we can serialize our custom objects as needed:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3#include "Character.h"
4
5int main() {
6  Character Player{"Bob", 50};
7
8  std::ofstream File{"SaveFile"};
9  cereal::BinaryOutputArchive OArchive(File);
10  OArchive(Player);
11}

And deserialize them later:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3#include "Character.h"
4
5int main() {
6  Character Player;
7
8  std::ifstream File{"SaveFile"};
9  cereal::BinaryInputArchive OArchive(File);
10  OArchive(Player);
11
12  std::cout << Player.Name << " (Level "
13            << Player.Level << ")";
14}

1Bob (Level 50)

Serializing Pointers

Cereal does not support the serialization of raw pointers (eg int* ) or references (eg int&), but we can serialize smart pointers, such as std::unique_ptr<int>.

Smart Pointers and std::unique_ptr

An introduction to memory ownership using smart pointers and std::unique_ptr in C++

We can do this by including the cereal/types/memory.hpp header:

1#include <cereal/archives/binary.hpp>
2#include <cereal/types/memory.hpp>
3#include <fstream>
4
5int main() {
6  // Serialize
7  {
8    auto Number{std::make_unique<int>(42)};
9
10    std::ofstream File{"SaveFile"};
11    cereal::BinaryOutputArchive OArchive(File);
12    OArchive(Number);
13  }
14
15  // Deserialize
16  {
17    std::unique_ptr<int> Number;
18
19    std::ifstream File{"SaveFile"};
20    cereal::BinaryInputArchive IArchive(File);
21    IArchive(Number);
22
23    std::cout << *Number;
24  }
25}

142

Deserializing Types without Default Constructors

To create an object from our serialized data, cereal first default constructs the object (ie, it creates it with no arguments) and then calls our serialization function to update the object.

This only works if our object is default constructible. Below, we’ve updated our Character object to now require that a Name is provided at construction:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  Character(std::string Name) : Name{Name} {}
8  std::string Name;
9  int Level;
10
11 private:
12  friend class cereal::access;
13  template <class Archive>
14  void serialize(Archive& Data) {
15    Data(Name, Level);
16  }
17};

If we update our main function to serialize and then deserialize a Character, we’ll see a compilation error:

1#include <cereal/archives/binary.hpp>
2#include <cereal/types/memory.hpp>
3#include <fstream>
4
5#include "Character.h"
6
7int main() {
8  // Serialize
9  {
10    auto Player{
11        std::make_unique<Character>("Bob")};
12
13    Player->Level = 50;
14
15    std::ofstream File{"SaveFile"};
16    cereal::BinaryOutputArchive OArchive(File);
17    OArchive(Player);
18  }
19
20  // Deserialize
21  {
22    std::unique_ptr<Character> Player;
23
24    std::ifstream File{"SaveFile"};
25    cereal::BinaryInputArchive IArchive(File);
26    IArchive(Player);
27  }
28}

1error C2512: 'Character::Character':
2no appropriate default constructor available

We have a few options for dealing with this. The most obvious solution is that we can provide a default constructor. It doesn’t need to be public - it just needs to be accessible to cereal::access, which can be done using the friend technique we’ve already been using:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  Character(std::string Name) : Name{Name} {}
8  std::string Name;
9  int Level;
10
11 private:
12  friend class cereal::access;
13  Character(){};  // Default constuctor
14  template <class Archive>
15  void serialize(Archive& Data) {
16    Data(Name, Level);
17  }
18};

Another option is to define a static load_and_construct method on our type. This will receive two arguments - the archive to load data from, and a cereal::construct object. This object allows us to both call the constructor for our type, and then access the constructed object:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  Character(std::string Name) : Name{Name} {}
8  std::string Name;
9  int Level;
10
11 private:
12  friend class cereal::access;
13
14  template <class Archive>
15  static void load_and_construct(
16      Archive& Data,
17      cereal::construct<Character>& Construct) {
18    // Local variable to temporarily hold data
19    std::string Name;
20
21    // Update local variable from the archive
22    Data(Name);
23
24    // Call the Character constructor
25    Construct(Name);
26
27    // Now that our object is constructed, we
28    // can access variables and methods using ->
29    // Reading a value:
30    std::cout << "Name:" << Construct->Name;
31
32    // Writing a value:
33    Data(Construct->Level);
34    std::cout << "\nLevel:" << Construct->Level;
35  }
36
37  template <class Archive>
38  void serialize(Archive& Data) {
39    Data(Name, Level);
40  }
41};

1Name:Bob
2Level:50

Our last option is very similar to the previous - it just implements the load_and_construct function outside of our class, rather than as a static member function.

To do this, we provide a specialization for the LoadAndConstruct struct within the cereal namespace:

1namespace cereal {
2template <>
3struct LoadAndConstruct<Character> {
4  // ...
5};
6}

Within that specialization, we’d implement the load_and_construct method, in the same way as the previous example:

1namespace cereal {
2template <>
3struct LoadAndConstruct<Character> {
4  template <class Archive>
5  static void load_and_construct(
6      Archive& Data,
7      cereal::construct<Character>& Construct) {
8      // ...
9  }
10};
11}

Template Specialization

A practical guide to template specialization in C++ covering full and partial specialization, and the scenarios where they’re useful

Serializing with Inheritance

Let's imagine we have an object of the Monster class, and Monster inherits from Character:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  std::string Name;
8  int Level;
9
10 private:
11  friend class cereal::access;
12  template <class Archive>
13  void serialize(Archive& Data) {
14    Data(Name, Level);
15  }
16};
17
18class Monster : public Character {
19 public:
20  bool isHostile;
21
22 private:
23  friend class cereal::access;
24  template <class Archive>
25  void serialize(Archive& Data) {
26    // TODO: Serialise inherited members too
27    Data(isHostile);
28  }
29};

When we’re serializing a Monster object, we don’t just want the isHostile variable to be serialized. Our Monster is also a Character, so the Character variables (Name and Level) need to be serialized too.

We could reference those variables directly in our Monster’s serialize object:

1void serialize(Archive& Data) {
2  Data(isHostile, Name, Level);
3}

But this is not a good design. If a new variable is added to Character, our code will have hard-to-detect bugs if we forget to add this new variable to the child classes’ serialize functions.

Another option would be to call the base class serialize function:

1void serialize(Archive& Data) {
2  Character::serialize();
3  Data(isHostile);
4}

But this is not always an option. Our base class might be using separate load and save methods instead. This approach would also require us to make our serialize functions protected rather than private.

Another option, which is frequently the best choice, is to use cereal’s cereal::base_class function instead. It receives the base class as a template parameter, and a pointer to the current object (via the this keyword) as a function parameter:

1void serialize(Archive& Data) {
2  Data(
3    cereal::base_class<Character>(this),
4    isHostile
5  );
6}

If the inheritance is virtual, we use cereal::virtual_base_class instead:

1class Monster : virtual Character {
2 using c = cereal;
3 public:
4  bool isHostile;
5
6 private:
7  friend class c::access;
8  template <class Archive>
9  void serialize(Archive& Data) {
10    Data(
11      c::virtual_base_class<Character>(this),
12      isHostile
13    );
14  }
15};

Over in our main function, we can now confirm both inherited and local members are being serialized and deserialized correctly:

1#include <cereal/archives/binary.hpp>
2#include <fstream>
3
4#include "Character.h"
5
6int main() {
7  // Serialize
8  {
9    std::ofstream File{"SaveFile"};
10    cereal::BinaryOutputArchive OArchive(File);
11
12    Monster Enemy{"Goblin", 10, true};
13    OArchive(Enemy);
14  }
15
16  // Deserialize
17  {
18    std::ifstream File{"SaveFile"};
19    cereal::BinaryInputArchive IArchive(File);
20
21    Monster Enemy;
22    IArchive(Enemy);
23
24    std::cout << Enemy.Name
25              << (Enemy.isHostile
26                      ? " is hostile"
27                      : " is not hostile");
28  }
29}

1Goblin is hostile

Deserializing with Polymorphic Types

An interesting problem arises when we’re serializing in scenarios where we're using run-time polymorphism.

Below, we have a Character pointer, which is specifically pointing to a Monster:

1#include <cereal/archives/binary.hpp>
2#include <cereal/types/memory.hpp>
3#include <fstream>
4#include "Character.h"
5
6int main() {
7  // Serialize
8  {
9    std::ofstream File{"SaveFile"};
10    cereal::BinaryOutputArchive OArchive(File);
11
12    // Character pointer pointing at a Monster
13    std::unique_ptr<Character> Enemy{
14        std::make_unique<Monster>()};
15
16    Enemy->Name = "Goblin";
17
18    OArchive(Enemy);
19  }
20
21  // Deserialize
22  {
23    std::ifstream File{"SaveFile"};
24    cereal::BinaryInputArchive IArchive(File);
25
26    // In the archive, this object is specifically
27    // a Monster, not just a Character
28    std::unique_ptr<Character> Enemy;
29    IArchive(Enemy);
30
31    Monster* EnemyMonsterPtr{
32        dynamic_cast<Monster*>(Enemy.get())};
33
34    std::cout << Enemy->Name
35              << (EnemyMonsterPtr
36                      ? " is a Monster"
37                      : " is not a Monster");
38  }
39}

The serialization part of this code will work correctly. At run time, cereal knows what our Character pointer is specifically pointing at, so it can serialize it as the correct derived type - Monster, in this case.

However, when it comes to deserialization, cereal needs a little more help. It’s attempting to deserialize a Monster into a Character pointer, but it doesn’t inherently understand the relationship between these two types.

It needs enough knowledge of our inheritance tree to establish the link between Character and Monster. We can help it out in three ways:

First, we include the header file that contains the polymorphic utilities:

1#include <cereal/types/polymorphic.hpp>

Next, we make cereal aware of our derived type, using the CEREAL_REGISTER_TYPE macro:

1CEREAL_REGISTER_TYPE(Monster);

Finally, we tell cereal that our derived type has a polymorphic relationship with a base type, using the CEREAL_REGISTER_POLYMORPHIC_RELATION macro. We pass the base type first, and the derived type second:

1CEREAL_REGISTER_POLYMORPHIC_RELATION(Character,
2                                     Monster)

Note, that both these macro calls need to happen after we #include the cereal archives we’ll be using. Our code is complying with this as we are calling the macros in Character.h which is included after cereal/archives/binary.hpp in our main file.

Our complete Character and Monster header file now looks like this. We've added a virtual destructor to make our Character class polymorphic:

1#include <cereal/access.hpp>
2#include <cereal/types/string.hpp>
3#include <cereal/types/polymorphic.hpp>
4
5class Character {
6 public:
7  std::string Name;
8  int Level;
9  virtual ~Character() = default;
10
11 protected:
12  friend class cereal::access;
13  template <class Archive>
14  void serialize(Archive& Data) {
15    Data(Name, Level);
16  }
17};
18
19class Monster : public Character {
20 public:
21  bool isHostile;
22
23 private:
24  friend class cereal::access;
25  template <class Archive>
26  void serialize(Archive& Data) {
27    Data(cereal::base_class<Character>(this),
28         isHostile);
29  }
30};
31
32CEREAL_REGISTER_TYPE(Monster);
33CEREAL_REGISTER_POLYMORPHIC_RELATION(Character,
34                                     Monster)

With no changes to main.cpp, our code should now compile and run as expected, with the following output:

1Goblin is a Monster

When working with multiple layers of inheritance, cereal can automatically understand relationships through intermediate classes - we don't need to explicitly define them.

For example, if we tell cereal that Character is a base class for Monster, and Monster is a base class of Goblin, cereal is automatically able to infer that Character is also a base class for Goblin.

Class Versioning

When working with serialization, we must be mindful of version mismatches between our archives and code. For example, if we’re making a game, any update we release is going to make changes to some of our classes.

Many of those changes would impact serialization. For example, if we add a field to our Character class, any object serialized before that field was added is not going to contain that value in the archive.

We need to come up with a strategy to mitigate this, as our players are not going to be happy if every update we release makes their previous save files unusable.

In other words, we want our program to be backward compatible - new versions of our program should be able to load old versions of our archives.

A common strategy to accomplish this is to include a Version integer in our classes, right from the very first version of our software.

1#include <cereal/access.hpp>
2#include <cereal/types/string.hpp>
3
4class Character {
5 public:
6  std::string Name;
7  int Level;
8
9 private:
10  friend class cereal::access;
11
12  // Setting the version
13  static inline int Version{1};
14
15  template <class Archive>
16  void save(Archive& Data) {
17    // Saving the version to the archive
18    Data(Version, Name, Level);
19  }
20
21  template <class Archive>
22  void load(Archive& Data) {
23    // Reading the version from the archive
24    int ArchiveVersion;
25    Data(ArchiveVersion);
26    std::cout << "Archive Version: "
27              << ArchiveVersion
28              << "\nClass Version: " << Version;
29    Data(Name, Level);
30  }
31};

1Archive Version: 1
2Class Version: 1

When we need to make changes to our class, we can increase the version integer to 2.

Then, when we load an archive, we can check what version of our class created it, and take the steps we need to maintain backward compatibility. In the following example, version 2 of our class added the Health variable.

If our load function receives an archive version from before this time, it knows the archive won’t include the Health value, so it sets it to a fallback value of 100.

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  std::string Name;
8  int Level;
9  int Health;
10  static inline int Version{2};
11
12 private:
13  friend class cereal::access;
14
15  template <class Archive>
16  void save(Archive& Data) const {
17    Data(Version, Name, Level, Health);
18  }
19
20  template <class Archive>
21  void load(Archive& Data) {
22    int ArchiveVersion;
23    Data(ArchiveVersion);
24    std::cout << "Archive Version: "
25              << ArchiveVersion
26              << "\nClass Version: " << Version;
27
28    if (ArchiveVersion < 2) {
29      Data(Name, Level);
30      Health = 100;
31    } else {
32      Data(Name, Level, Health);
33    }
34  }
35};

Cereal supports this as a native feature. Rather than having a version integer in our class, we can instead call the CEREAL_CLASS_VERSION macro, passing in our class name, and the current version:

1CEREAL_CLASS_VERSION(Character, 1)

Variants of all the serialization functions are available that provide the archive version as an additional uint32_t. This allows us to check which version of our class created the data we’re seeing:

1#pragma once
2#include <cereal/access.hpp>
3#include <cereal/types/string.hpp>
4
5class Character {
6 public:
7  std::string Name;
8  int Level;
9  int Health;
10
11 private:
12  friend class cereal::access;
13
14  template <class Archive>
15  void save(Archive& Data,
16            std::uint32_t) const {
17    Data(Name, Level, Health);
18  }
19
20  template <class Archive>
21  void load(Archive& Data,
22            std::uint32_t ArchiveVersion) {
23    std::cout << "Archive Version: "
24              << ArchiveVersion;
25
26    if (ArchiveVersion < 2) {
27      Data(Name, Level);
28      Health = 100;
29    } else {
30      Data(Name, Level, Health);
31    }
32  }
33};
34
35CEREAL_CLASS_VERSION(Character, 2)

If the version of our software that generated the archive hadn’t specified the class version (using the CEREAL_CLASS_VERSION macro) for the object we’re trying to deserialize, the version passed to our function will be 0.

Note, when using separate save and load functions, we need to be consistent in whether we use the versioned or unversioned overload within the same class. In other words, if our load function has the archive version parameter, our save function will need it too, even though it typically won’t make use of it.

1template <class Archive>
2void save(Archive& Data, std::uint32_t) const {}
3
4template <class Archive>
5void load(Archive& Data,
6          std::uint32_t ArchiveVersion) {}

If we’re not consistent, we will encounter issues:

• Data serialized from a versioned save function is incompatible with an unversioned load function.
• Data serialized from an unversioned save function is incompatible with a versioned load function.

An additional side effect of these constraints means that, if we ever want to use versioning in our class, we should try to enable it right from the start. If we enable it as part of an update, we’ll have a much harder time trying to deserialize data that was generated before that update.

Portable Binaries / Endianness

There are multiple ways that computers can read binary data - this difference is sometimes referred to as endianness, If the reason we’re serializing data is to have it read on a different computer, the possibility that the other machine is using a different endianness is something we need to consider.

Cereal can take care of this for us, by using a portable binary archive.

Portable variations are used in the same way as their non-portable counterparts. We just need to update our #include directives and types to use the portable variants:

1#include <cereal/archives/portable_binary.hpp>
2#include <fstream>
3#include <iostream>
4
5int main() {
6  // Serialize
7  {
8    std::ofstream File{"SaveFile"};
9    cereal::PortableBinaryOutputArchive
10        OArchive(File);
11
12    int Number{5};
13    OArchive(Number);
14  }
15
16  // Deserialize
17  {
18    std::ifstream File{"SaveFile"};
19    cereal::PortableBinaryInputArchive IArchive(
20        File);
21
22    int Number;
23    IArchive(Number);
24
25    std::cout << "Number: " << Number;
26  }
27}

Portable binaries incur some performance costs - they are larger, and take longer to serialize and deserialize. Therefore, in performance-critical contexts, we shouldn’t use them unless we know our archives are going to be used across machines that have different endianness.

Summary

This lesson has taken us through binary serialization in C++. Here's a recap of the key points we've covered:

1. Concept of Serialization and Deserialization: We began by exploring the fundamental concepts of serialization and deserialization, understanding their role in saving and transmitting the state of objects in a program.
2. Binary vs. JSON Serialization: We compared binary serialization with JSON, highlighting binary's efficiency and compactness, making it a preferred choice for performance-critical uses.
3. Using Cereal Library: The cereal library was introduced as a tool for binary serialization in C++. We walked through its installation and basic usage, building a strong foundation for your serialization tasks.
4. Practical Examples and Code Implementation: Through various examples, you've learned how to serialize basic data types, standard library types, and custom user-defined types.
5. Handling Complex Scenarios: We delved into more advanced topics like serialization with inheritance, dealing with polymorphic types, and class versioning, preparing us for complex real-world projects.
6. Addressing Portability and Endianness: Finally, we touched upon the concept of endianness and the use of portable binaries, ensuring our serialized data maintains its integrity across different systems.

Part 2 - Available Now

Professional C++

Advance straight from the beginner course, dive deeper into C++, and learn expert workflows

View Course