libgig
4.3.0
|
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 &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) |
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... | |
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.
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 145 of file Serialization.h.
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.
Definition at line 200 of file Serialization.h.
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:
int
, double
, bool
, etc.) or a String
object.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 178 of file Serialization.h.
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.
Definition at line 188 of file Serialization.h.
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 157 of file Serialization.h.
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 130 of file Serialization.h.
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:
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:
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:
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 402 of file Serialization.h.
typedef uint32_t Serialization::Version |
Version number data type.
This data type is used for maintaining version number information of your C++ class implementations.
Definition at line 209 of file Serialization.h.
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.
Definition at line 216 of file Serialization.h.
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.
data | - the variable or object whose data type shall be checked |
Definition at line 266 of file Serialization.h.
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.
data | - the variable or object whose data type shall be checked |
Definition at line 229 of file Serialization.h.
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.
data | - the variable or object whose data type shall be checked |
Definition at line 248 of file Serialization.h.
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::Member::Member(), and Serialization::Object::uid().