Serialization Namespace Reference

C++ Serialization / Deserialization Framework. More...

Classes
class	UID
	Unique identifier referring to one specific native C++ object, member, fundamental variable, or any other native C++ data. More...
class	DataType
	Abstract reflection of a native C++ data type. 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	Archive
	Destination container for serialization, and source container for deserialization. More...
class	Exception
	Will be thrown whenever an error occurs during an serialization or deserialization process. 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 &)
	Check whether data is a C/C++ enum type. More...
template<typename T >
bool	IsUnion (const T &)
	Check whether data is a C++ union type. More...
template<typename T >
bool	IsClass (const T &)
	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 double &value)
template<typename T >
String	toString (T *ptr)
template<>
String	toString (const String &value)
template<typename T >
T	_stringToNumber (const String &s)
template<>
int64_t	_stringToNumber (const String &s)

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

Detailed Description

C++ Serialization / Deserialization Framework.

The classes in this namespace allow to serialize and deserialize native C++ objects in a portable, very easy and yet flexible way.

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

Serialization is a technique that allows to capture the current state and data of native (in this case C++) objects and encoding that overall state into a serial data stream, including all other objects the "serialized" objects relate to. The data stream may then be sent over "wire", for example as file or via network connection to another computer, and finally the data stream would be "deserialized" on receiver side, that is fully automatic resembling of objects' original state and data as it was captured on sender side.

Main features of this framework:

• Very low time & effort integration: you only need to define "what" shall be (de)serialized of your own C++ classes, not "how". Which is as simple as this:

  void MyOwnClass::serialize(Serialization::Archive* archive) {
    SRLZ(memberVar1);
    SRLZ(memberVar2);
    SRLZ(memberVar3);
    ...
  }

• Standard types out of the box: fundamental data types and standard STL classes are handled out of the box. So you don't need to specify how to serialize a std::map<std::string,int> container or even a simple double variable for instance.
• No mandatory tree-structure layout of your C++ classes: it copes with cyclic dependencies (e.g. a C++ object pointing at another C++ object and vice versa) without causing endless recursion or data redundancy.
• Automatic C++ pointer handling: raw C++ pointers are handled fully automatically, i.e. automatically identifies and distinguishes "strong" from "weak" pointers, automatically creates required instances for fundamental types and arbitrary C++ objects for strong pointers on receiver side (without redundancy or dead links), and therefore fully automatically resembles even very complex C++ object layouts of applications from serialized data streams.
• Supports "partial" or "masked" deserialization: application may decide to deserialize only certain objects or even only certain members of individual objects, leaving all other existing data of live C++ objects untouched, therefore allowing for instance to implement a flexible and powerful preset or macro feature in applications very easily and with very little effort (see Gigedit's macro feature as example).
• Multiple encoding formats: the encoding format of the serialized data stream can be chosen. For instance a standard JSON text encoding is supported (see Archive::format_t).
• Reflection API: Native C++ objects can be modified live & directly via this framework's reflection API.
• Portable (de)serialization: sender side (serializing application) and receiver side (deserializing application) may run on completely different computer systems, with different hardware, OS, CPU architecture, native memory word size and endian type. This is handled automatically.
• Long-term robustness on application changes: automatically handles changes between your application's software versions. If sender and receiver are using different versions of their serialized / deserialized C++ classes, structures and data types, that is having a different, changed native data structure layout, this framework automatically adapts its deserialization process in that case, such that deserialized objects on receiver side would still reflect the overall expected states and overall data as intended by the sender, with the new native data structure layout expected by receiver side. For being able to do so, this framework automatically captures all kind of additional information about each serialized object and each data structure member, for example name of each data structure member and native offset within its containing data structure, precise data types, and much more.

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 198 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 253 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 231 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 241 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 210 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 183 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 474 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 262 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 269 of file Serialization.h.

Function Documentation

IsClass()

template<typename T >

bool Serialization::IsClass

(

const T &

)

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 319 of file Serialization.h.

IsEnum()

template<typename T >

bool Serialization::IsEnum

(

const T &

)

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 282 of file Serialization.h.

IsUnion()

template<typename T >

bool Serialization::IsUnion

(

const T &

)

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 301 of file Serialization.h.

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 55 of file Serialization.cpp.

Referenced by Serialization::Archive::Archive(), Serialization::Archive::clear(), Serialization::Member::Member(), Serialization::Object::Object(), and Serialization::Object::uid().