Serialization Namespace Reference

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

## 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.
template<typename T>
bool | IsUnion (const T &)
| Check whether data is a C++ `union` type.
template<typename T>
bool | IsClass (const T &)
| Check whether data is a C/C++ `struct` or C++ `class` type.
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)
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.

## 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 = 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 150 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 205 of file Serialization.h.

## Map

template<class T_key, class T_value>

using Serialization::Map = 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 183 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 193 of file Serialization.h.

## Set

template<class T>

using Serialization::Set = 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 162 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 135 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 426 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 214 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 221 of file Serialization.h.

## Function Documentation

## _encode()

String Serialization::_encode | ( | const Archive::ObjectPool & | objects | ) |

Definition at line 1624 of file Serialization.cpp.

## _stringToNumber() [1/4]

template<>

bool Serialization::_stringToNumber | ( | const String & | s | ) |

inline

Definition at line 1549 of file Serialization.cpp.

## _stringToNumber() [2/4]

template<>

double Serialization::_stringToNumber | ( | const String & | s | ) |

inline

Definition at line 1544 of file Serialization.cpp.

## _stringToNumber() [3/4]

template<>

int64_t Serialization::_stringToNumber | ( | const String & | s | ) |

inline

Definition at line 1539 of file Serialization.cpp.

## _stringToNumber() [4/4]

template<typename T>

T Serialization::_stringToNumber | ( | const String & | s | ) |

inline

Definition at line 1534 of file Serialization.cpp.

## 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 271 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 234 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 253 of file Serialization.h.

## toString() [1/4]

template<>

String Serialization::toString | ( | const double & | value | ) |

inline

Definition at line 311 of file Serialization.h.

## toString() [2/4]

template<>

String Serialization::toString | ( | const String & | value | ) |

inline

Definition at line 330 of file Serialization.h.

## toString() [3/4]

template<typename T>

String Serialization::toString | ( | const T & | value | ) |

inline

Definition at line 301 of file Serialization.h.

## toString() [4/4]

template<typename T>

String Serialization::toString | ( | T * | ptr | ) |

inline

Definition at line 322 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 53 of file Serialization.cpp.

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