cereal.hpp File Reference

Main cereal functionality. More...

#include <type_traits>
#include <string>
#include <memory>
#include <functional>
#include <unordered_map>
#include <unordered_set>
#include <vector>
#include <cstddef>
#include <cstdint>
#include "cereal/macros.hpp"
#include "cereal/details/traits.hpp"
#include "cereal/details/helpers.hpp"
#include "cereal/types/base_class.hpp"
#include "cereal/types/common.hpp"

Go to the source code of this file.

Classes
class	cereal::OutputArchive< ArchiveType, Flags >
	The base output archive class. More...
class	cereal::InputArchive< ArchiveType, Flags >
	The base input archive class. More...

Namespaces
	cereal
	in certain simple scenarios. They should probably not be used if maximizing performance is the main objective.

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. More...
#define	CEREAL_REGISTER_ARCHIVE(Archive)
	Registers a specific Archive type with cereal. More...
#define	CEREAL_UNUSED_FUNCTION   static void unused() { (void)version; }
	Helper macro to omit unused warning. More...
#define	CEREAL_CLASS_VERSION(TYPE, VERSION_NUMBER)
	Defines a class version for some type. More...
#define	PROCESS_IF(name)
	Helper macro that expands the requirements for activating an overload. More...
#define	PROCESS_IF(name)
	Helper macro that expands the requirements for activating an overload. More...

Enumerations
enum	cereal::Flags { cereal::AllowEmptyClassElision = 1 }
	Special flags for archives. More...

Functions
template<class Archive , class T >
void	cereal::prologue (Archive &, T const &)
template<class Archive , class T >
void	cereal::epilogue (Archive &, T const &)

Detailed Description

Main cereal functionality.

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.

CEREAL_NVP

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

CEREAL_REGISTER_ARCHIVE

#define CEREAL_REGISTER_ARCHIVE

(

Archive

)

Value:

  namespace cereal { namespace detail {                                 \
  template <class T, class BindingTag>                                  \
  typename polymorphic_serialization_support<Archive, T>::type          \
  instantiate_polymorphic_binding( T*, Archive*, BindingTag, adl_tag ); \
  } } /* end namespaces */

Registers a specific Archive type with cereal.

This registration should be done once per archive. A good place to put this is immediately following the definition of your archive. Archive registration is only strictly necessary if you wish to support pointers to polymorphic data types. All archives that come with cereal are already registered.

CEREAL_UNUSED_FUNCTION

#define CEREAL_UNUSED_FUNCTION   static void unused() { (void)version; }

Helper macro to omit unused warning.

PROCESS_IF [1/2]

#define PROCESS_IF

(

name

)

Value:

      traits::EnableIf<traits::has_##name<T, ArchiveType>::value,                          \
                       !traits::has_invalid_output_versioning<T, ArchiveType>::value,      \
                       (traits::is_output_serializable<T, ArchiveType>::value &&           \
                        (traits::is_specialized_##name<T, ArchiveType>::value ||           \
                         !traits::is_specialized<T, ArchiveType>::value))> = traits::sfinae

Helper macro that expands the requirements for activating an overload.

Requirements: Has the requested serialization function Does not have version and unversioned at the same time Is output serializable AND is specialized for this type of function OR has no specialization at all

Requirements: Has the requested serialization function Does not have version and unversioned at the same time Is input serializable AND is specialized for this type of function OR has no specialization at all

PROCESS_IF [2/2]

#define PROCESS_IF

(

name

)

Value:

      traits::EnableIf<traits::has_##name<T, ArchiveType>::value,                           \
                       !traits::has_invalid_input_versioning<T, ArchiveType>::value,        \
                       (traits::is_input_serializable<T, ArchiveType>::value &&             \
                        (traits::is_specialized_##name<T, ArchiveType>::value ||            \
                         !traits::is_specialized<T, ArchiveType>::value))> = traits::sfinae

Helper macro that expands the requirements for activating an overload.

Requirements: Has the requested serialization function Does not have version and unversioned at the same time Is output serializable AND is specialized for this type of function OR has no specialization at all

Requirements: Has the requested serialization function Does not have version and unversioned at the same time Is input serializable AND is specialized for this type of function OR has no specialization at all