UT/UT_Serialization.h File Reference

#include "UT_IStream.h"
#include "UT_RefArray.h"
#include "UT_String.h"
#include "UT_ValArray.h"
#include "UT_WorkBuffer.h"
#include <SYS/SYS_Types.h>
#include <boost/bind.hpp>
#include <boost/fusion/algorithm/query/any.hpp>
#include <boost/fusion/algorithm/iteration/for_each.hpp>
#include <boost/fusion/sequence.hpp>
#include <boost/ref.hpp>
#include <boost/type_traits/remove_reference.hpp>
#include <iostream.h>
#include <stddef.h>
#include <string.h>

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_SaveArchiver< ARCHIVER_T >::SaveKeyValue
class	UT_LoadArchiver< ARCHIVER_T >
class	UT_LoadArchiver< ARCHIVER_T >::LoadKeyValue
class	UT_SaveArchiverManip< OBJ_T, ARCHIVER_T >
	Manipulators for streaming archivers. More...
class	UT_LoadArchiverManip< OBJ_T, ARCHIVER_T >
Defines
#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 OBJ_T , typename ARCHIVER_T >
std::ostream &	operator<< (std::ostream &out, UT_SaveArchiverManip< OBJ_T, ARCHIVER_T > manip)
	std::ostream manipulator << overload
template<typename OBJ_T , typename ARCHIVER_T >
UT_IStream &	operator>> (UT_IStream &in, UT_LoadArchiverManip< OBJ_T, ARCHIVER_T > manip)
	UT_IStream manipulator >> overload.
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:

1. Implement instrusive serialize() class methods. eg.

                template <typename ARCHIVER_T>
                bool LIB_MyClass::serialize(ARCHIVER_T &archiver)
                {
                    using namespace boost;
                    using namespace boost::fusion;
   
                    // serialize an unordered map of key value pairs
                    if (!archiver(make_vector(
                                    make_vector("key1", myValue),
                                    make_vector("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.

2. Partially specialize UTserialize() to serialize your data. eg.

                template <typename ARCHIVER_T>
                bool
                UTserialize(ARCHIVER_T &archiver, LIB_MyClass &obj)
                {
                    using namespace boost;
                    using namespace boost::fusion;
   
                    // serialize an unordered map of key value pairs
                    if (!archiver(make_vector(
                                    make_vector("key1", myValue),
                                    make_vector("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:
  • class Input : public UT_LoadArchiver<Input>
  • class Output : public UT_SaveArchiver<Output>
• 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.

---

Define Documentation

#define UT_DECLARE_ARRAY_SERIALIZABLE

(

ARRAY_T

)

Value:

template <typename T> \
            struct UT_SaveSerializable< ARRAY_T<T> > \
                : public UT_ArraySaveSerializable<T, ARRAY_T> { }; \
            template <typename T> \
            struct UT_LoadSerializable< ARRAY_T<T> > \
                : public UT_ArrayLoadSerializable<T, ARRAY_T> { }; \

Definition at line 257 of file UT_Serialization.h.

#define UT_DECLARE_SERIALIZABLE

(

OBJ_T

)

Value:

template <typename ARCHIVER_T> \
            bool UTserialize(ARCHIVER_T &archiver, OBJ_T &obj) \
            { \
                return archiver.serializeValue(obj); \
            } \

Definition at line 174 of file UT_Serialization.h.

---

Function Documentation

template<typename OBJ_T , typename ARCHIVER_T >

std::ostream& operator<<	(	std::ostream &	out,
		UT_SaveArchiverManip< OBJ_T, ARCHIVER_T >	manip
	)			[inline]

std::ostream manipulator << overload

Definition at line 472 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
	)			[inline]

UT_IStream manipulator >> overload.

Definition at line 479 of file UT_Serialization.h.

UT_DECLARE_SERIALIZABLE

(

fpreal64

)

UT_DECLARE_SERIALIZABLE

(

fpreal32

)

UT_DECLARE_SERIALIZABLE

(

fpreal16

)

UT_DECLARE_SERIALIZABLE

(

int64

)

UT_DECLARE_SERIALIZABLE

(

int32

)

UT_DECLARE_SERIALIZABLE

(

int16

)

UT_DECLARE_SERIALIZABLE

(

int8

)

UT_DECLARE_SERIALIZABLE

(

bool

)

template<typename ARCHIVER_T , typename OBJ_T >

bool UTserialize	(	ARCHIVER_T &	archiver,
		OBJ_T &	obj
	)			[inline]

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 122 of file UT_Serialization.h.

template<typename ARCHIVER_T >

bool UTserializeLoad	(	ARCHIVER_T &	archiver,
		UT_WorkBuffer &	str
	)			[inline]

Definition at line 216 of file UT_Serialization.h.

template<typename ARCHIVER_T >

bool UTserializeLoad	(	ARCHIVER_T &	archiver,
		UT_String &	str
	)			[inline]

Definition at line 200 of file UT_Serialization.h.

template<typename ARCHIVER_T , typename OBJ_T >

bool UTserializeLoad	(	ARCHIVER_T &	archiver,
		OBJ_T &	obj
	)			[inline]

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 141 of file UT_Serialization.h.

template<typename ARCHIVER_T >

bool UTserializeSave	(	ARCHIVER_T &	archiver,
		UT_WorkBuffer &	str
	)			[inline]

Definition at line 210 of file UT_Serialization.h.

template<typename ARCHIVER_T >

bool UTserializeSave	(	ARCHIVER_T &	archiver,
		UT_String &	str
	)			[inline]

Definition at line 194 of file UT_Serialization.h.

template<typename ARCHIVER_T , typename OBJ_T >

bool UTserializeSave	(	ARCHIVER_T &	archiver,
		OBJ_T &	obj
	)			[inline]

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.