libgig
4.2.0
|
Abstract reflection of some native serialized C/C++ data. More...
#include <Serialization.h>
Public Member Functions | |
Object () | |
Default constructor (for an "invalid" Object). More... | |
Object (UIDChain uidChain, DataType type) | |
Constructor for a "meaningful" Object. More... | |
UID | uid (int index=0) const |
Unique identifier of this Object. More... | |
const UIDChain & | uidChain () const |
Unique identifier chain of this Object. More... | |
const DataType & | type () const |
C/C++ data type this Object is reflecting. More... | |
const RawData & | rawData () const |
Raw data of the original native C/C++ data. More... | |
Version | version () const |
Version of original user defined C/C++ struct or class . More... | |
Version | minVersion () const |
Minimum version of original user defined C/C++ struct or class . More... | |
bool | isVersionCompatibleTo (const Object &other) const |
Check version compatibility between Object instances. More... | |
std::vector< Member > & | members () |
All members of the original native C/C++ struct or class instance. More... | |
const std::vector< Member > & | members () const |
Member | memberNamed (String name) const |
Get the member of this Object with given name. More... | |
Member | memberByUID (const UID &uid) const |
Get the member of this Object with given unique identifier. More... | |
std::vector< Member > | membersOfType (const DataType &type) const |
Get all members of this Object with given data type. More... | |
int | sequenceIndexOf (const Member &member) const |
Serialization/deserialization sequence number of the requested member. More... | |
bool | isValid () const |
Check if this is a valid Object instance. More... | |
bool | operator== (const Object &other) const |
Comparison for equalness. More... | |
bool | operator!= (const Object &other) const |
Comparison for inequalness. More... | |
bool | operator< (const Object &other) const |
Smaller than comparison. More... | |
bool | operator> (const Object &other) const |
Greater than comparison. More... | |
Protected Member Functions | |
void | remove (const Member &member) |
void | setVersion (Version v) |
void | setMinVersion (Version v) |
Abstract reflection of some native serialized C/C++ data.
When your native C++ objects are serialized, all native data is translated and reflected by such an Object reflection. So each instance of your serialized native C++ class objects become available as an Object, but also each member variable of your C++ objects is translated into an Object, and any other native C/C++ data. So essentially every native data is turned into its own Object and accessible by this API.
For each one of those Object reflections, this class provides detailed information about their native origin. For example if an Object represents a native C++ class instante, then it provides access to its C++ class/struct name, to its C++ member variables, its native memory size and much more.
Even though this framework allows you to adjust abstract Object instances to a certain extent, most of the methods of this Object class are read-only though and the actual modifyable methods are made available not as part of this Object class, but as part of the Archive class instead. This design decision was made for performance and safety reasons.
Definition at line 540 of file Serialization.h.
Serialization::Object::Object | ( | ) |
Default constructor (for an "invalid" Object).
Initializes an Object instance as being an "invalid" Object. Thus calling isValid(), after creating an Object instance with this constructor, would return false
.
Usually you are not supposed to create (meaningful) Object instances on your own. They are typically constructed by the Archive class for you.
Definition at line 640 of file Serialization.cpp.
Constructor for a "meaningful" Object.
Initializes a "meaningful" Object instance as being. Thus calling isValid(), after creating an Object instance with this constructor, should return true
, provided that the arguments passed to this constructor construe a valid object representation.
Usually you are not supposed to create (meaningful) Object instances on your own. They are typically constructed by the Archive class for you.
uidChain | - unique identifier chain of the object to be constructed |
type | - C/C++ data type of the actual native object this abstract Object instance should reflect after calling this constructor |
Definition at line 662 of file Serialization.cpp.
References type(), and uidChain().
bool Serialization::Object::isValid | ( | ) | const |
Check if this is a valid Object instance.
Returns true
if this Object instance is reflecting a "valid" Object. The default constructor creates Object instances initialized to be "invalid" Objects by default. That way one can detect whether an Object instance was ever assigned to something meaningful.
Note that this class also implements the bool
operator, both return the same boolean result value.
Definition at line 680 of file Serialization.cpp.
bool Serialization::Object::isVersionCompatibleTo | ( | const Object & | other | ) | const |
Check version compatibility between Object instances.
Use this method to check whether the two original C/C++ instances those two Objects are reflecting, were using a C/C++ data type which are version compatible with each other. By default all C/C++ Objects are considered to be version compatible. They might only be version incompatible if you enforced a certain backward compatibility constraint with your serialize() method implementation of your custom C/C++ struct
or class
types.
You must only call this method on two Object instances which are representing the same data type, for example if both Objects reflect instances of the same user defined C++ class. Calling this method on completely different data types does not cause an error or exception, but its result would simply be useless for any purpose.
Definition at line 898 of file Serialization.cpp.
References minVersion(), and version().
Get the member of this Object with given unique identifier.
This method behaves similar like method memberNamed() described above, but instead of searching for a member variable by name, it searches for a member with an abstract unique identifier instead. For primitive, fundamental C/C++ data types, for invalid or unknown unique identifiers, and for members which are actually not member instances of the original C/C++ struct
or class
instance this Object is reflecting, this method returns an "invalid" Member instance instead.
uid | - unique identifier of the member variable being sought |
Definition at line 965 of file Serialization.cpp.
References uid().
Member Serialization::Object::memberNamed | ( | String | name | ) | const |
Get the member of this Object with given name.
In case this Object is reflecting a native C/C++ struct
or class
type, then this method returns the abstract reflection of the requested member variable of the original native C/C++ struct
or class
instance. For primitive, fundamental C/C++ data types this method always returns an "invalid" Member instance instead.
Example:
Consider that you serialized the native C/C++ struct
as shown in this example, and assuming that you implemented the respective serialize() method of this C++ struct
to serialize all its members, then you might call memberNamed("someValue") to get the details of the third member in this example for instance. In case the passed name is an unknown member name, then this method will return an "invalid" Member object instead.
name | - original name of the sought serialized member variable of this Object reflection |
Definition at line 944 of file Serialization.cpp.
const std::vector< Member > & Serialization::Object::members | ( | ) |
All members of the original native C/C++ struct
or class
instance.
All members of the original native C/C++ struct
or class
instance (read only).
In case this Object is reflecting a native C/C++ struct
or class
type, then this method returns all member variables of that original native C/C++ struct
or class
instance. For primitive, fundamental C/C++ data types this method returns an empty vector instead.
Example:
Considering above's C++ code, a serialized Object representation of such a native Foo
class would have 3 members a
, b
and someValue
.
Note that the respective serialize() method implementation of that fictional C++ struct
Foo
actually defines which members are going to be serialized and deserialized for instances of class Foo
. So in practice the members returned by method members() here might return a different set of members as actually defined in the original C/C++ struct header declaration.
The precise sequence of the members returned by this method here depends on the actual serialize() implementation of the user defined C/C++ struct
or class
.
Returns the same result as overridden members() method above, it just returns a read-only result instead. See above's method description for details for the return value of this method instead.
Definition at line 804 of file Serialization.cpp.
Referenced by Serialization::Archive::serializeMember().
Get all members of this Object with given data type.
In case this Object is reflecting a native C/C++ struct
or class
type, then this method returns all member variables of that original native C/C++ struct
or class
instance which are matching the given requested data type. If this Object is reflecting a primitive, fundamental data type, or if there are no members of this Object with the requested precise C/C++ data type, then this method returns an empty vector instead.
type | - the precise C/C++ data type of the sought member variables of this Object |
Definition at line 997 of file Serialization.cpp.
References Serialization::Member::type(), and type().
Version Serialization::Object::minVersion | ( | ) | const |
Minimum version of original user defined C/C++ struct
or class
.
In case this Object is reflecting a native C/C++ struct
or class
type, then this method returns the "minimum" version of that native C/C++ struct
or class
layout or implementation which it may be compatible with. For primitive, fundamental C/C++ data types the return value of this method has no meaning.
Definition at line 768 of file Serialization.cpp.
Referenced by isVersionCompatibleTo().
bool Serialization::Object::operator!= | ( | const Object & | other | ) | const |
Comparison for inequalness.
Returns the inverse result of what Object::operator==() would return. So refer to the latter for more details.
Definition at line 840 of file Serialization.cpp.
References operator==().
bool Serialization::Object::operator< | ( | const Object & | other | ) | const |
Smaller than comparison.
Returns true
if this Object instance can be consider to be "smaller" than the other Object instance being compared with. This operator is actually quite arbitrarily implemented and may change at any time, and thus result for the same Object representations may change in future at any time.
This operator is basically implemented for allowing this DataType class to be used with various standard template library (STL) classes, which require sorting operators to be implemented.
Definition at line 856 of file Serialization.cpp.
Referenced by operator>().
bool Serialization::Object::operator== | ( | const Object & | other | ) | const |
Comparison for equalness.
Returns true
if the two Object instances being compared can be considered to be "equal" native C/C++ object instances. They are considered to be equal if they are representing the same original C/C++ data instance, which is essentially the case if the original reflecting native C/C++ data are sharing the same memory address and memory size (thus the exact same memory space) and originally had the exact same native C/C++ types.
Definition at line 828 of file Serialization.cpp.
Referenced by operator!=(), and operator>().
bool Serialization::Object::operator> | ( | const Object & | other | ) | const |
Greater than comparison.
Returns true
if this Object instance can be consider to be "greater" than the other Object instance being compared with. This operator is actually quite arbitrarily implemented and may change at any time, and thus result for the same Object representations may change in future at any time.
This operator is basically implemented for allowing this DataType class to be used with various standard template library (STL) classes, which require sorting operators to be implemented.
Definition at line 876 of file Serialization.cpp.
References operator<(), and operator==().
const RawData & Serialization::Object::rawData | ( | ) | const |
Raw data of the original native C/C++ data.
Returns the raw data value of the original C/C++ data this Object is reflecting. So the precise raw data value, layout and size is dependent to the precise C/C++ data type of the original native C/C++ data. However potentially required endian correction is already automatically applied for you. That means you can safely, directly C-cast the raw data returned by this method to the respective native C/C++ data type in order to access and use the value for some purpose, at least if the respective data is of any fundamental, primitive C/C++ data type, or also to a certain extent if the type is user defined enum
type.
However directly C-casting this raw data for user defined struct
or class
types is not possible. For those user defined data structures this method always returns empty raw data instead.
Note however that there are more convenient methods in the Archive class to get the right value for the individual data types instead.
Definition at line 740 of file Serialization.cpp.
int Serialization::Object::sequenceIndexOf | ( | const Member & | member | ) | const |
Serialization/deserialization sequence number of the requested member.
Returns the precise serialization/deserialization sequence number of the requested member variable.
Example:
Assuming the declaration of the user defined native C/C++ struct
Foo
above, and assuming the following implementation of serialize():
then sequenceIndexOf
(obj.memberNamed("a")) returns 1, sequenceIndexOf
(obj.memberNamed("b")) returns 2, and sequenceIndexOf
(obj.memberNamed("c")) returns 0.
Definition at line 1038 of file Serialization.cpp.
const DataType & Serialization::Object::type | ( | ) | const |
C/C++ data type this Object is reflecting.
Returns the precise original C/C++ data type of the original native C/C++ object or data this Object instance is reflecting.
Definition at line 714 of file Serialization.cpp.
Referenced by membersOfType(), Object(), Serialization::Archive::setBoolValue(), Serialization::Archive::setEnumValue(), Serialization::Archive::setIntValue(), and Serialization::Archive::setRealValue().
UID Serialization::Object::uid | ( | int | index = 0 | ) | const |
Unique identifier of this Object.
Returns the unique identifier for the original native C/C++ data this abstract Object instance is reflecting. If this Object is representing a C/C++ pointer (of first degree) then uid()
(or uid(0)
) returns the unique identifier of the pointer itself, whereas uid(1)
returns the unique identifier of the original C/C++ data that pointer was actually pointing to.
Definition at line 695 of file Serialization.cpp.
References Serialization::NO_UID.
Referenced by memberByUID(), and Serialization::Archive::remove().
const UIDChain & Serialization::Object::uidChain | ( | ) | const |
Version Serialization::Object::version | ( | ) | const |
Version of original user defined C/C++ struct
or class
.
In case this Object is reflecting a native C/C++ struct
or class
type, then this method returns the version of that native C/C++ struct
or class
layout or implementation. For primitive, fundamental C/C++ data types the return value of this method has no meaning.
Definition at line 753 of file Serialization.cpp.
Referenced by isVersionCompatibleTo().