HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
UT_Serialization.h File Reference
#include "UT_IStream.h"
#include "UT_OStream.h"
#include "UT_Array.h"
#include "UT_String.h"
#include "UT_StringHolder.h"
#include "UT_TupleUtil.h"
#include "UT_ValArray.h"
#include "UT_WorkBuffer.h"
#include <SYS/SYS_Types.h>
#include <tuple>
#include <type_traits>
#include <utility>
#include <stddef.h>
#include <string.h>
+ Include dependency graph for UT_Serialization.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  UT_SaveSerializable< OBJ_T >
 
struct  UT_LoadSerializable< OBJ_T >
 
struct  UT_ArraySaveSerializable< T, ARRAY >
 
struct  UT_ArrayLoadSerializable< T, ARRAY >
 
class  UT_SaveArchiver< ARCHIVER_T >
 Base class for archivers. More...
 
class  UT_LoadArchiver< ARCHIVER_T >
 
class  UT_SaveArchiverManip< OBJ_T, ARCHIVER_T >
 Manipulators for streaming archivers. More...
 
class  UT_LoadArchiverManip< OBJ_T, ARCHIVER_T >
 

Macros

#define UT_DECLARE_SERIALIZABLE(OBJ_T)
 
#define UT_DECLARE_ARRAY_SERIALIZABLE(ARRAY_T)
 

Functions

template<typename ARCHIVER_T , typename OBJ_T >
bool UTserialize (ARCHIVER_T &archiver, OBJ_T &obj)
 
 UT_DECLARE_SERIALIZABLE (bool)
 
 UT_DECLARE_SERIALIZABLE (int8)
 
 UT_DECLARE_SERIALIZABLE (int16)
 
 UT_DECLARE_SERIALIZABLE (int32)
 
 UT_DECLARE_SERIALIZABLE (int64)
 
 UT_DECLARE_SERIALIZABLE (fpreal16)
 
 UT_DECLARE_SERIALIZABLE (fpreal32)
 
 UT_DECLARE_SERIALIZABLE (fpreal64)
 
template<typename ARCHIVER_T >
bool UTserializeSave (ARCHIVER_T &archiver, UT_String &str)
 
template<typename ARCHIVER_T >
bool UTserializeLoad (ARCHIVER_T &archiver, UT_String &str)
 
template<typename ARCHIVER_T >
bool UTserializeSave (ARCHIVER_T &archiver, UT_WorkBuffer &str)
 
template<typename ARCHIVER_T >
bool UTserializeLoad (ARCHIVER_T &archiver, UT_WorkBuffer &str)
 
template<typename ARCHIVER_T >
bool UTserializeSave (ARCHIVER_T &archiver, UT_StringHolder &str)
 
template<typename ARCHIVER_T >
bool UTserializeLoad (ARCHIVER_T &archiver, UT_StringHolder &str)
 
template<typename OBJ_T , typename ARCHIVER_T >
UT_OStreamoperator<< (UT_OStream &out, UT_SaveArchiverManip< OBJ_T, ARCHIVER_T > manip)
 UT_OStream manipulator << overload. More...
 
template<typename OBJ_T , typename ARCHIVER_T >
UT_IStreamoperator>> (UT_IStream &in, UT_LoadArchiverManip< OBJ_T, ARCHIVER_T > manip)
 UT_IStream manipulator >> overload. More...
 
template<typename ARCHIVER_T , typename OBJ_T >
bool UTserializeSave (ARCHIVER_T &archiver, OBJ_T &obj)
 
template<typename ARCHIVER_T , typename OBJ_T >
bool UTserializeLoad (ARCHIVER_T &archiver, OBJ_T &obj)
 

Detailed Description

Generic class serialization support

Support structure for generic class serialization.If you just want to save/load to/from classes that already have serialize() methods, then see UT_JSONArchive.h.

To add support for serializing your data, you have two choices for implementation:

-# Implement instrusive serialize() class methods. eg.
template <typename ARCHIVER_T>
bool LIB_MyClass::serialize(ARCHIVER_T &archiver)
{
using namespace std;
// serialize an unordered map of key value pairs
if (!archiver(make_tuple(
make_tuple("key1", myValue),
make_tuple("key2", mySpecificRefArray)
/* ... etc ... */
)))
return false;
}
Note
You can just declare the template function in your header and only implement it in the .C file if you're always going to load/save within your class.
  1. Partially specialize UTserialize() to serialize your data. eg.
    template <typename ARCHIVER_T>
    bool
    UTserialize(ARCHIVER_T &archiver, LIB_MyClass &obj)
    {
    using namespace std;
    // serialize an unordered map of key value pairs
    if (!archiver(make_tuple(
    make_tuple("key1", myValue),
    make_tuple("key2", mySpecificRefArray)
    /* ... etc ... */
    )))
    return false;
    }

To implement serialization for custom types that need different handling between saving and loading, you specialize UTserializeSave/UTserializeLoad instead. For member serialize() methods, you can also call archiver.isLoading() or archiver.isSaving().

To create a new archive type for serialization to a specific format, see UT_JSONArchive.h as an example. There are some requirements:

  • Create an archive class like UT_JSONArchive. This provides a partially specialized class of UT_ArchiveManip<T,Archiver>.
  • Your Archiver class should have two nested classes within it:
  • In turn, your Input/Output archiver classes need the following methods:
    • serializeValue<T>(): serialize a value of a POD type T.
    • serializeStringValue(): serialize a C string
    • serializeMapBegin()/serializeMapEnd(): begin/end serialization for an unordered collection of key value pairs. As an archiver implementer, you're free to ignore the unordered requirement if you want but the client serialize code is already setup to support it. bool serializeKey(UT_WorkBuffer &key)
    • serializeArrayBegin()/serializeArrayEnd(): begin/end serialization for an ordered sequence of values.
    • serializeUniformArray(): complete serialization of an ordered sequence of POD type values.

Definition in file UT_Serialization.h.

Macro Definition Documentation

#define UT_DECLARE_ARRAY_SERIALIZABLE (   ARRAY_T)
#define UT_DECLARE_SERIALIZABLE (   OBJ_T)
Value:
template <typename ARCHIVER_T> \
bool UTserialize(ARCHIVER_T &archiver, OBJ_T &obj) \
{ \
return archiver.serializeValue(obj); \
} \
bool UTserialize(ARCHIVER_T &archiver, OBJ_T &obj)

Definition at line 166 of file UT_Serialization.h.

Function Documentation

template<typename OBJ_T , typename ARCHIVER_T >
UT_OStream& operator<< ( UT_OStream out,
UT_SaveArchiverManip< OBJ_T, ARCHIVER_T >  manip 
)

UT_OStream manipulator << overload.

Definition at line 475 of file UT_Serialization.h.

template<typename OBJ_T , typename ARCHIVER_T >
UT_IStream& operator>> ( UT_IStream in,
UT_LoadArchiverManip< OBJ_T, ARCHIVER_T >  manip 
)

UT_IStream manipulator >> overload.

Definition at line 482 of file UT_Serialization.h.

UT_DECLARE_SERIALIZABLE ( bool  )
UT_DECLARE_SERIALIZABLE ( int8  )
UT_DECLARE_SERIALIZABLE ( int16  )
UT_DECLARE_SERIALIZABLE ( int32  )
UT_DECLARE_SERIALIZABLE ( int64  )
UT_DECLARE_SERIALIZABLE ( fpreal16  )
UT_DECLARE_SERIALIZABLE ( fpreal32  )
UT_DECLARE_SERIALIZABLE ( fpreal64  )
template<typename ARCHIVER_T , typename OBJ_T >
bool UTserialize ( ARCHIVER_T &  archiver,
OBJ_T &  obj 
)

Default function for non-instrusive serialization of classes. Specialize this when you can perform the same code using the archiver for serialization. If it isn't specialized, then it will call the intrusive version, which you must supply.

Definition at line 114 of file UT_Serialization.h.

template<typename ARCHIVER_T , typename OBJ_T >
bool UTserializeLoad ( ARCHIVER_T &  archiver,
OBJ_T &  obj 
)

Specialize UTserializeSave/UTserializeLoad for serialization when saving/loading needs to be different. By default, they just forward to the regular UTserialize() method.

Definition at line 133 of file UT_Serialization.h.

template<typename ARCHIVER_T >
bool UTserializeLoad ( ARCHIVER_T &  archiver,
UT_String str 
)

Definition at line 192 of file UT_Serialization.h.

template<typename ARCHIVER_T >
bool UTserializeLoad ( ARCHIVER_T &  archiver,
UT_WorkBuffer str 
)

Definition at line 208 of file UT_Serialization.h.

template<typename ARCHIVER_T >
bool UTserializeLoad ( ARCHIVER_T &  archiver,
UT_StringHolder str 
)

Definition at line 220 of file UT_Serialization.h.

template<typename ARCHIVER_T , typename OBJ_T >
bool UTserializeSave ( ARCHIVER_T &  archiver,
OBJ_T &  obj 
)

Specialize UTserializeSave/UTserializeLoad for serialization when saving/loading needs to be different. By default, they just forward to the regular UTserialize() method.

Definition at line 125 of file UT_Serialization.h.

template<typename ARCHIVER_T >
bool UTserializeSave ( ARCHIVER_T &  archiver,
UT_String str 
)

Definition at line 186 of file UT_Serialization.h.

template<typename ARCHIVER_T >
bool UTserializeSave ( ARCHIVER_T &  archiver,
UT_WorkBuffer str 
)

Definition at line 202 of file UT_Serialization.h.

template<typename ARCHIVER_T >
bool UTserializeSave ( ARCHIVER_T &  archiver,
UT_StringHolder str 
)

Definition at line 214 of file UT_Serialization.h.