libgig  4.3.0
Serialization::Object Class Reference

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 UIDChainuidChain () const
 Unique identifier chain of this Object. More...
 
const DataTypetype () const
 C/C++ data type this Object is reflecting. More...
 
const RawDatarawData () 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< MembermembersOfType (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)
 

Detailed Description

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.

See also
Archive::setIntValue() as an example for modifying Object instances.

Definition at line 704 of file Serialization.h.

Constructor & Destructor Documentation

◆ Object() [1/2]

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.

See also
Archive::rootObject(), Archive::objectByUID()

Definition at line 764 of file Serialization.cpp.

◆ Object() [2/2]

Serialization::Object::Object ( UIDChain  uidChain,
DataType  type 
)

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.

See also
Archive::rootObject(), Archive::objectByUID()
Parameters
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.

References type(), and uidChain().

Member Function Documentation

◆ isValid()

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.

Referenced by operator bool().

◆ isVersionCompatibleTo()

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.

See also
Archive::setVersion() for more details about this overall topic.

Definition at line 1089 of file Serialization.cpp.

References minVersion(), and version().

◆ memberByUID()

Member Serialization::Object::memberByUID ( const UID uid) const

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.

Parameters
uid- unique identifier of the member variable being sought
Returns
abstract reflection of the sought member variable
See also
Member::isValid(), Object::members(), Object::memberNamed()

Definition at line 1156 of file Serialization.cpp.

References uid().

◆ memberNamed()

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:

struct Foo {
int a;
bool b;
double someValue;
};

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.

Parameters
name- original name of the sought serialized member variable of this Object reflection
Returns
abstract reflection of the sought member variable
See also
Member::isValid(), Object::members()

Definition at line 1135 of file Serialization.cpp.

◆ members() [1/2]

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:

struct Foo {
int a;
bool b;
double someValue;
};

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.

See also
Object::sequenceIndexOf() for more details about the precise order of members returned by this method in the same way.

Definition at line 995 of file Serialization.cpp.

Referenced by Serialization::Archive::serializeHeapMember(), and Serialization::Archive::serializeMember().

◆ members() [2/2]

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.

◆ membersOfType()

std::vector< Member > Serialization::Object::membersOfType ( const DataType type) const

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.

Parameters
type- the precise C/C++ data type of the sought member variables of this Object
Returns
vector with abstract reflections of the sought member variables
See also
Object::members(), Object::memberNamed()

Definition at line 1188 of file Serialization.cpp.

References Serialization::Member::type(), and type().

◆ minVersion()

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.

See also
Archive::setVersion() and Archive::setMinVersion() for more details about this overall topic.

Definition at line 959 of file Serialization.cpp.

Referenced by isVersionCompatibleTo().

◆ operator!=()

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.

References operator==().

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

Referenced by operator>().

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

Referenced by operator!=(), and operator>().

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

References operator<(), and operator==().

◆ rawData()

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.

See also
Archive::valueAsInt(), Archive::valueAsReal(), Archive::valueAsBool(), Archive::valueAsString()

Definition at line 930 of file Serialization.cpp.

◆ sequenceIndexOf()

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:

struct Foo {
int a;
bool b;
double c;
void serialize(Serialization::Archive* archive);
};
Destination container for serialization, and source container for deserialization.

Assuming the declaration of the user defined native C/C++ struct Foo above, and assuming the following implementation of serialize():

#define SRLZ(member) \
archive->serializeMember(*this, member, #member);
void Foo::serialize(Serialization::Archive* archive) {
SRLZ(c);
SRLZ(a);
SRLZ(b);
}

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.

◆ setNativeValueFromString()

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.

Parameters
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, and uid().

◆ type()

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 membersOfType(), Object(), Serialization::Archive::setBoolValue(), Serialization::Archive::setEnumValue(), Serialization::Archive::setIntValue(), and Serialization::Archive::setRealValue().

◆ uid()

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.

See also
UIDChain for more details about this overall topic.

Definition at line 819 of file Serialization.cpp.

References Serialization::NO_UID.

Referenced by memberByUID(), Serialization::Archive::remove(), and setNativeValueFromString().

◆ uidChain()

const UIDChain & Serialization::Object::uidChain ( ) const

Unique identifier chain of this Object.

Returns the entire unique identifier chain of this Object.

See also
uid() and UIDChain for more details about this overall topic.

Definition at line 895 of file Serialization.cpp.

Referenced by Object().

◆ version()

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.

See also
Archive::setVersion() for more details about this overall topic.

Definition at line 944 of file Serialization.cpp.

Referenced by isVersionCompatibleTo().


The documentation for this class was generated from the following files: