Utility Functionality

Name-value pairs, binary data wrappers, exceptions, and other utility functions. More...

Classes
struct	cereal::RapidJSONException
	An exception thrown when rapidjson fails an internal assertion. More...
struct	cereal::Exception
	An exception class thrown when things go wrong at runtime. More...

Macros
#define	CEREAL_NVP(T)   ::cereal::make_nvp(#T, T)
	Creates a name value pair for the variable T with the same name as the variable.
#define	CEREAL_CLASS_VERSION(TYPE, VERSION_NUMBER)
	Defines a class version for some type. More...

Functions
template<class T >
NameValuePair< T >	make_nvp (std::string const &name, T &&value)
	Creates a name value pair.
template<class T >
NameValuePair< T >	make_nvp (const char *name, T &&value)
	Creates a name value pair.
template<class T >
BinaryData< T >	binary_data (T &&data, size_t size)
	Convenience function to create binary data for both const and non const pointers. More...
template<class T >
SizeTag< T >	make_size_tag (T &&sz)
	Creates a size tag from some variable. More...
template<class T >
DeferredData< T >	defer (T &&value)
	Marks data for deferred serialization. More...

Detailed Description

Name-value pairs, binary data wrappers, exceptions, and other utility functions.

Macro Definition Documentation

CEREAL_CLASS_VERSION

#define CEREAL_CLASS_VERSION	(		TYPE,
			VERSION_NUMBER
	)

Value:

  namespace cereal { namespace detail {                                          \
    template <> struct Version<TYPE>                                             \
    {                                                                            \
      static const std::uint32_t version;                                        \
      static std::uint32_t registerVersion()                                     \
      {                                                                          \
        ::cereal::detail::StaticObject<Versions>::getInstance().mapping.emplace( \
             std::type_index(typeid(TYPE)).hash_code(), VERSION_NUMBER );        \
        return VERSION_NUMBER;                                                   \
      }                                                                          \
      CEREAL_UNUSED_FUNCTION                                                     \
    }; /* end Version */                                                         \
    const std::uint32_t Version<TYPE>::version =                                 \
      Version<TYPE>::registerVersion();                                          \
  } }

Defines a class version for some type.

Versioning information is optional and adds some small amount of overhead to serialization. This overhead will occur both in terms of space in the archive (the version information for each class will be stored exactly once) as well as runtime (versioned serialization functions must check to see if they need to load or store version information).

Versioning is useful if you plan on fundamentally changing the way some type is serialized in the future. Versioned serialization functions cannot be used to load non-versioned data.

By default, all types have an assumed version value of zero. By using this macro, you may change the version number associated with some type. cereal will then use this value as a second parameter to your serialization functions.

The interface for the serialization functions is nearly identical to non-versioned serialization with the addition of a second parameter, const std::uint32_t version, which will be supplied with the correct version number. Serializing the version number on a save happens automatically.

Versioning cannot be mixed with non-versioned serialization functions. Having both types will result result in a compile time error. Data serialized without versioning cannot be loaded by a serialization function with added versioning support.

Example interface for versioning on a non-member serialize function:

CEREAL_CLASS_VERSION( Mytype, 77 ); // register class version
 
template <class Archive>
void serialize( Archive & ar, Mytype & t, const std::uint32_t version )
{
  // When performing a load, the version associated with the class
  // is whatever it was when that data was originally serialized
  //
  // When we save, we'll use the version that is defined in the macro
 
  if( version >= some_number )
    // do this
  else
    // do that
}

Interfaces for other forms of serialization functions is similar. This macro should be placed at global scope. On C++17, define the StaticObject as inline to merge the definitions across TUs This prevents multiple definition errors when this macro appears in a header file included in multiple TUs.

Function Documentation

binary_data()

template<class T >

BinaryData< T > binary_data ( T &&  data, size_t  size  )

related

Convenience function to create binary data for both const and non const pointers.

Parameters

data	Pointer to beginning of the data
size	The size in bytes of the data

defer()

template<class T >

DeferredData< T > defer ( T &&  value )

related

Marks data for deferred serialization.

cereal performs a recursive depth-first traversal of data it serializes. When serializing smart pointers to large, nested, or cyclical data structures, it is possible to encounter a stack overflow from excessive recursion when following a chain of pointers.

Deferment can help in these situations if the data can be serialized separately from the pointers used to traverse the structure. For example, a graph structure can have its nodes serialized before its edges:

struct MyEdge
{
  std::shared_ptr<MyNode> connection;
  int some_value;
 
  template<class Archive>
  void serialize(Archive & archive)
  {
    // when we serialize an edge, we'll defer serializing the associated node
    archive( cereal::defer( connection ),
             some_value );
  }
};
 
struct MyGraphStructure
{
  std::vector<MyEdge> edges;
  std::vector<MyNodes> nodes;
 
  template<class Archive>
  void serialize(Archive & archive)
  {
    // because of the deferment, we ensure all nodes are fully serialized
    // before any connection pointers to those nodes are serialized
    archive( edges, nodes );
 
    // we have to explicitly inform the archive when it is safe to serialize
    // the deferred data
    archive.serializeDeferments();
  }
};

make_size_tag()

template<class T >

SizeTag< T > make_size_tag ( T &&  sz )

related

Creates a size tag from some variable.

Will normally be used to serialize size (e.g. size()) information for variable size containers. If you have a variable sized container, the very first thing it serializes should be its size, wrapped in a SizeTag.