cereal
A C++11 library for serialization
Classes | Macros | Functions
Utility Functionality

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...
 

Detailed Description

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

Macro Definition Documentation

#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; \
} \
static void unused() { (void)version; } \
}; /* end Version */ \
const std::uint32_t Version<TYPE>::version = \
Version<TYPE>::registerVersion(); \
} }
Definition: access.hpp:40

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.

Function Documentation

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
dataPointer to beginning of the data
sizeThe size in bytes of the data
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.