- Generated by
1.8.13
|
libgig
4.4.1
|
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 |
All members of the original native C/C++ struct or class instance (read only). More... | |
| 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... | |
| operator bool () const | |
| Same as calling isValid(). | |
| 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... | |
| void | setNativeValueFromString (const String &s) |
| Cast from string to object's data type and assign value natively. 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 706 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 764 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 786 of file Serialization.cpp.
| 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 804 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 1089 of file Serialization.cpp.
References minVersion(), and version().
Referenced by Serialization::Archive::valueAsBool().
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 1156 of file Serialization.cpp.
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 1135 of file Serialization.cpp.
Referenced by Serialization::Archive::setMinVersion(), and Serialization::Archive::valueAsBool().
| std::vector< Member > & Serialization::Object::members | ( | ) |
All members of the original native C/C++ struct or class instance.
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.
Definition at line 995 of file Serialization.cpp.
Referenced by Serialization::Archive::rootObject(), Serialization::Archive::serializeHeapMember(), Serialization::Archive::serializeMember(), Serialization::Archive::setMinVersion(), and Serialization::Archive::valueAsBool().
| const std::vector< Member > & Serialization::Object::members | ( | ) | const |
All members of the original native C/C++ struct or class instance (read only).
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 1005 of file Serialization.cpp.
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 1188 of file Serialization.cpp.
References Serialization::Member::type().
Referenced by Serialization::Archive::valueAsBool().
| 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 (including String objects) the return value of this method has no meaning.
Definition at line 959 of file Serialization.cpp.
Referenced by isVersionCompatibleTo(), Serialization::Archive::rootObject(), and Serialization::Archive::valueAsBool().
| 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 1031 of file Serialization.cpp.
| 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 1047 of file Serialization.cpp.
| 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 1019 of file Serialization.cpp.
| 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 1067 of file Serialization.cpp.
| 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 930 of file Serialization.cpp.
Referenced by Serialization::Archive::valueAsBool().
| 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 1229 of file Serialization.cpp.
Referenced by Serialization::Archive::valueAsBool().
| void Serialization::Object::setNativeValueFromString | ( | const String & | s | ) |
Cast from string to object's data type and assign value natively.
The passed String s is decoded from its string representation to this object's corresponding native data type, then that casted value is assigned to the native memory location this Object is referring to.
Note: This method may only be called for data types which enjoy built-in support for casting from string to their native data type, which are basically primitive data types (e.g. int, bool, double, etc.) or String objects. For all other data types calling this method will cause an assertion fault at runtime.
| s | - textual string representation of the value to be assigned to this object |
Definition at line 883 of file Serialization.cpp.
References Serialization::UID::id.
Referenced by Serialization::Archive::setMinVersion().
| 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 904 of file Serialization.cpp.
Referenced by Serialization::Archive::rootObject(), Serialization::Archive::setBoolValue(), Serialization::Archive::setEnumValue(), Serialization::Archive::setIntValue(), Serialization::Archive::setRealValue(), and Serialization::Archive::valueAsBool().
| 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 819 of file Serialization.cpp.
References Serialization::DataType::isBool(), Serialization::DataType::isEnum(), Serialization::DataType::isInteger(), Serialization::DataType::isPointer(), Serialization::DataType::isPrimitive(), Serialization::DataType::isReal(), Serialization::DataType::isSigned(), Serialization::DataType::isString(), and Serialization::DataType::size().
Referenced by Serialization::Archive::remove(), Serialization::Archive::rootObject(), Serialization::Archive::setMinVersion(), and Serialization::Archive::valueAsBool().
| const UIDChain & Serialization::Object::uidChain | ( | ) | const |
Unique identifier chain of this Object.
Returns the entire unique identifier chain of this Object.
Definition at line 895 of file Serialization.cpp.
Referenced by Serialization::Archive::rootObject().
| 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 (including String objects) the return value of this method has no meaning.
Definition at line 944 of file Serialization.cpp.
Referenced by isVersionCompatibleTo(), Serialization::Archive::rootObject(), and Serialization::Archive::valueAsBool().
1.8.13