Serialization Namespace Reference

Serialization / deserialization framework. More...

Classes
class	Archive
	Destination container for serialization, and source container for deserialization. More...
class	DataType
	Abstract reflection of a native C++ data type. More...
class	Exception
	Will be thrown whenever an error occurs during an serialization or deserialization process. More...
class	Member
	Abstract reflection of a native C++ class/struct's member variable. More...
class	Object
	Abstract reflection of some native serialized C/C++ data. More...
class	UID
	Unique identifier referring to one specific native C++ object, member, fundamental variable, or any other native C++ data. More...

Typedefs
typedef std::string	String
	Textual string. More...
template<class T >
using	Array = std::vector< T >
	Array<> template. More...
template<class T >
using	Set = std::set< T >
	Set<> template. More...
template<class T_key , class T_value >
using	Map = std::map< T_key, T_value >
	Map<> template. More...
typedef std::vector< uint8_t >	RawData
	Raw data stream of serialized C++ objects. More...
typedef void *	ID
	Abstract identifier for serialized C++ objects. More...
typedef uint32_t	Version
	Version number data type. More...
typedef std::vector< UID >	UIDChain
	Chain of UIDs. More...

Enumerations
enum	time_base_t { LOCAL_TIME, UTC_TIME }
	To which time zone a certain timing information relates to. More...

Functions
template<typename T >
bool	IsEnum (const T &data)
	Check whether data is a C/C++ enum type. More...
template<typename T >
bool	IsUnion (const T &data)
	Check whether data is a C++ union type. More...
template<typename T >
bool	IsClass (const T &data)
	Check whether data is a C/C++ struct or C++ class type. More...
template<typename T >
String	toString (const T &value)
template<>
String	toString (const String &value)
template<typename T >
T	_stringToNumber (const String &s)
template<>
int64_t	_stringToNumber (const String &s)
template<>
double	_stringToNumber (const String &s)
template<>
bool	_stringToNumber (const String &s)
String	_encode (const Archive::ObjectPool &objects)

Variables
const UID	NO_UID = _createNullUID()
	Reflects an invalid UID and behaves similar to NULL as invalid value for pointer types. More...

Detailed Description

Serialization / deserialization framework.

See class Archive as starting point for how to implement serialization and deserialization with your application.

The classes in this namespace allow to serialize and deserialize native C++ objects in a portable, easy and flexible way. Serialization is a technique that allows to transform the current state and data of native (in this case C++) objects into a data stream (including all other objects the "serialized" objects relate to); the data stream may then be sent over "wire" (for example via network connection to another computer, which might also have a different OS, CPU architecture, native memory word size and endian type); and finally the data stream would be "deserialized" on that receiver side, that is transformed again to modify all objects and data structures on receiver side to resemble the objects' state and data as it was originally on sender side.

In contrast to many other already existing serialization frameworks, this implementation has a strong focus on robustness regarding long-term changes to the serialized C++ classes of the serialized objects. So even if sender and receiver are using different versions of their serialized/deserialized C++ classes, structures and data types (thus having different data structure layout to a certain extent), this framework aims trying to automatically adapt its serialization and deserialization process in that case so that the deserialized objects on receiver side would still reflect the overall expected states and overall data as intended by the sender. For being able to do so, this framework stores all kind of additional information about each serialized object and each data structure member (for example name of each data structure member, but also the offset of each member within its containing data structure, precise data types, and more).

Like most other serialization frameworks, this frameworks does not require a tree-structured layout of the serialized data structures. So it automatically handles also cyclic dependencies between serialized data structures correctly, without i.e. causing endless recursion or redundancy.

Additionally this framework also allows partial deserialization. Which means the receiver side may for example decide that it wants to restrict deserialization so that it would only modify certain objects or certain members by the deserialization process, leaving all other ones untouched. So this partial deserialization technique for example allows to implement flexible preset features for applications in a powerful and easy way.

Typedef Documentation

Array

template<class T >

using Serialization::Array = typedef std::vector<T>

Array<> template.

This type is used for built-in automatic serialization / deserialization of C++ array containers (a.k.a. std::vector from the STL). This framework supports serializing this common data type out of the box, with only one constraint: the precise element type used with arrays must be serializable. So the array's element type should either be a) any primitive data type (e.g. int, double, etc.) or b) any other data structure or class types enjoying out of the box serialization support by this framework, or c) if it is a custom struct or class then it must have a serialize() method implementation.

Definition at line 147 of file Serialization.h.

ID

typedef void* Serialization::ID

Abstract identifier for serialized C++ objects.

This data type is used for identifying serialized C++ objects and members of your C++ objects. It is important to know that such an ID might not necessarily be unique. For example the ID of one C++ object might often be identical to the ID of the first member of that particular C++ object. That's why there is additionally the concept of an UID in this framework.

See also

UID

Definition at line 202 of file Serialization.h.

Map

template<class T_key , class T_value >

using Serialization::Map = typedef std::map<T_key,T_value>

Map<> template.

This type is used for built-in automatic serialization / deserialization of C++ associative sorted map containers (a.k.a. std::map from the STL). This framework supports serializing this common data type out of the box, with the following 2 constraints:

1. The precise key type (i.e. 1st template parameter) used with maps must be either a primitive data type (e.g. int, double, bool, etc.) or a String object.
2. The value type (i.e. 2nd template parameter) must be serializable. So the map's value type should either be a) any primitive data type (e.g. int, double, etc.) or b) any other data structure or class types enjoying out of the box serialization support by this framework, or c) if it is a custom struct or class then it must have a serialize() method implementation.

Definition at line 180 of file Serialization.h.

RawData

typedef std::vector<uint8_t> Serialization::RawData

Raw data stream of serialized C++ objects.

This data type is used for the data stream as a result of serializing your C++ objects with Archive::serialize(), and for native raw data representation of individual serialized C/C++ objects, members and variables.

See also

Archive::rawData(), Object::rawData()

Definition at line 190 of file Serialization.h.

Set

template<class T >

using Serialization::Set = typedef std::set<T>

Set<> template.

This type is used for built-in automatic serialization / deserialization of C++ unique data set containers (a.k.a. std::set from the STL). This framework supports serializing this common data type out of the box, with the following constraint: the precise key type used with sets must be either a primitive data type (e.g. int, double, bool, etc.) or a String object.

Definition at line 159 of file Serialization.h.

String

typedef std::string Serialization::String

Textual string.

This type is used for built-in automatic serialization / deserialization of C++ String objects (a.k.a. std::string from the STL). This framework supports serializing this common data type out of the box and is handled by this framework as it was a primitive C++ data type.

Definition at line 123 of file Serialization.h.

UIDChain

typedef std::vector<UID> Serialization::UIDChain

Chain of UIDs.

This data type is used for native C++ pointers. The first member of the UID chain is the unique identifier of the C++ pointer itself, then the following UIDs are the respective objects or variables the pointer is pointing to. The size (the amount of elements) of the UIDChain depends solely on the degree of the pointer type. For example the following C/C++ pointer:

int* pNumber;

is an integer pointer of first degree. Such a pointer would have a UIDChain with 2 members: the first element would be the UID of the pointer itself, the second element of the chain would be the integer data that pointer is pointing to. In the following example:

bool*** pppSomeFlag;

That boolean pointer would be of third degree, and thus its UIDChain would have a size of 4 (elements).

Accordingly a non pointer type like:

float f;

would yield in a UIDChain of size 1.

Since however this serialization framework currently only supports pointers of first degree yet, all UIDChains are currently either of size 1 or 2, which might change in future though.

Definition at line 404 of file Serialization.h.

Version

typedef uint32_t Serialization::Version

Version number data type.

This data type is used for maintaining version number information of your C++ class implementations.

See also

Archive::setVersion() and Archive::setMinVersion()

Definition at line 211 of file Serialization.h.

Enumeration Type Documentation

time_base_t

enum Serialization::time_base_t

To which time zone a certain timing information relates to.

The constants in this enum type are used to define to which precise time zone a time stamp relates to.

Enumerator
LOCAL_TIME	The time stamp relates to the machine's local time zone. Request a time stamp in local time if you want to present that time stamp to the end user.
UTC_TIME	The time stamp relates to "Greenwhich Mean Time" zone, also known as "Coordinated Universal Time". Request time stamp with UTC if you want to compare that time stamp with other time stamps.

Definition at line 218 of file Serialization.h.

Function Documentation

IsClass()

template<typename T >

bool Serialization::IsClass

(

const T &

data

)

Check whether data is a C/C++ struct or C++ class type.

Returns true if the supplied C++ variable or object is of C/C++ struct or C++ class type. Note that if you are using a C++ compiler which does have built-in type traits support, then this function will also return true on C/C++ union types.

Parameters

data	- the variable or object whose data type shall be checked

Definition at line 268 of file Serialization.h.

Referenced by Serialization::DataType::dataTypeOf().

IsEnum()

template<typename T >

bool Serialization::IsEnum

(

const T &

data

)

Check whether data is a C/C++ enum type.

Returns true if the supplied C++ variable or object is of a C/C++ enum type.

Parameters

data	- the variable or object whose data type shall be checked

Definition at line 231 of file Serialization.h.

Referenced by Serialization::DataType::dataTypeOf().

IsUnion()

template<typename T >

bool Serialization::IsUnion

(

const T &

data

)

Check whether data is a C++ union type.

Returns true if the supplied C++ variable or object is of a C/C++ union type. Note that the result of this function is only reliable if the C++ compiler you are using has support for built-in type traits. If your C++ compiler does not have built-in type traits support, then this function will simply return false on all your calls.

Parameters

data	- the variable or object whose data type shall be checked

Definition at line 250 of file Serialization.h.

Referenced by Serialization::DataType::dataTypeOf().

Variable Documentation

NO_UID

const UID Serialization::NO_UID = _createNullUID()

Reflects an invalid UID and behaves similar to NULL as invalid value for pointer types.

All UID objects are first initialized with this value, and it essentially an all zero object.

Definition at line 53 of file Serialization.cpp.

Referenced by Serialization::Archive::Archive(), Serialization::Archive::clear(), Serialization::UID::from(), and Serialization::Member::Member().