Utility(3) Library Functions Manual Utility(3) # [NAME](#NAME) Utility - Utility Functionality # [SYNOPSIS](#SYNOPSIS) ## [Classes](#Classes) struct **cereal::RapidJSONException** An exception thrown when rapidjson fails an internal assertion. struct **cereal::Exception** An exception class thrown when things go wrong at runtime. ## [Macros](#Macros) #define **CEREAL\_NVP**(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. ## [Functions](#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. template<class T> SizeTag< T > **make\_size\_tag** (T &&sz) Creates a size tag from some variable. template<class T> **DeferredData**< T > **defer** (T &&value) Marks data for deferred serialization. # [Detailed Description](#Detailed_Description) Name-value pairs, binary data wrappers, exceptions, and other utility functions # [Macro Definition Documentation](#Macro_Definition_Documentation) ## [#define CEREAL\_CLASS\_VERSION( TYPE, VERSION\_NUMBER)](#_define_CEREAL_CLASS_VERSION%28_TYPE,__VERSION_NUMBER%29) **Value:** ``` namespace cereal { namespace detail { \ template <> struct Version \ { \ static const std::uint32_t version; \ static std::uint32_t registerVersion() \ { \ ::cereal::detail::StaticObject::getInstance().mapping.emplace( \ std::type_index(typeid(TYPE)).hash_code(), VERSION_NUMBER ); \ return VERSION_NUMBER; \ } \ CEREAL_UNUSED_FUNCTION \ }; \ const std::uint32_t Version::version = \ Version::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 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. ## [#define CEREAL\_NVP( T)](#_define_CEREAL_NVP%28_T%29) **Value:** ``` ::cereal::make_nvp(#T, T) ``` ``` ``` Creates a name value pair for the variable T with the same name as the variable. # [Function Documentation](#Function_Documentation) ## [template<class T> BinaryData< T > binary\_data (T && data, size\_t size) \[related\]](#template_class_T__BinaryData__T___binary_data_%28T_&&_data,_size_t_size%29) 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 ## [template<class T> **DeferredData**< T > defer (T && value) \[related\]](#template_class_T__) 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 connection; int some_value; template 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 edges; std::vector nodes; template 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(); } }; ``` ## [template<class T> SizeTag< T > make\_size\_tag (T && sz) \[related\]](#template_class_T__SizeTag__T___make_size_tag_%28T_&&_sz%29) 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**. # [Author](#Author) Generated automatically by Doxygen for cereal from the source code. Mon Oct 26 2026 02:55:37 cereal --- Document: Utility(3) from cereal 1.3.2-r7 (Chainguard OS) Source: https://github.com/USCiLab/cereal