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).
| Object (UIDChain uidChain, DataType type, const Object &parent)
| Constructor for a "meaningful" Object.
UID | uid (int index=0) const
| Unique identifier of this Object.
const UIDChain & | uidChain () const
| Unique identifier chain of this Object.
UID | parentUID () const
| Unique identifier of parent object.
const DataType & | type () const
| C/C++ data type this Object is reflecting.
const RawData & | rawData () const
| Raw data of the original native C/C++ data.
Version | version () const
| Version of original user defined C/C++ `struct` or `class`.
Version | minVersion () const
| Minimum version of original user defined C/C++ `struct` or `class`.
bool | isVersionCompatibleTo (const Object &other) const
| Check version compatibility between Object instances.
std::vector< Member > & | members ()
| All members of the original native C/C++ `struct` or `class` instance.
const std::vector< Member > & | members () const
| All members of the original native C/C++ `struct` or `class` instance (read only).
Member | memberNamed (String name) const
| Get the member of this Object with given name.
Member | memberByUID (const UID &uid) const
| Get the member of this Object with given unique identifier.
std::vector< Member > | membersOfType (const DataType &type) const
| Get all members of this Object with given data type.
int | sequenceIndexOf (const Member &member) const
| Serialization/deserialization sequence number of the requested member.
bool | isValid () const
| Check if this is a valid Object instance.
| operator bool () const
| Same as calling isValid().
bool | operator== (const Object &other) const
| Comparison for equalness.
bool | operator!= (const Object &other) const
| Comparison for inequalness.
bool | operator< (const Object &other) const
| Smaller than comparison.
bool | operator> (const Object &other) const
| Greater than comparison.
void | setNativeValueFromString (const String &s)
| Cast from string to object's data type and assign value natively.

## 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 903 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 840 of file Serialization.cpp.

References Serialization::NO_UID.

Referenced by isVersionCompatibleTo(), Object(), operator!=(), operator<(), operator==(), and operator>().

## Object() [2/2]

Serialization::Object::Object | ( | UIDChain | uidChain,
|  | DataType | type,
|  | const Object & | parent )

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

References Object(), type(), uid(), 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 882 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 1187 of file Serialization.cpp.

References minVersion(), Object(), 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 1254 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 1233 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 1093 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 1103 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 1286 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 1057 of file Serialization.cpp.

Referenced by isVersionCompatibleTo().

## operator bool()

Serialization::Object::operator bool | ( |  | ) | const

inline

Same as calling isValid().

Definition at line 923 of file Serialization.h.

References isValid().

## 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 1129 of file Serialization.cpp.

References Object(), and 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 1145 of file Serialization.cpp.

References Object().

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

References Object().

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

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

## parentUID()

UID Serialization::Object::parentUID | ( |  | ) | const

Unique identifier of parent object.

Returns the unique identifier of the parent object that contains and owns this object, which is the case for all member variables of classes and structs for example.

If the native data represented by this Object is located on the memory heap instead, i.e. not a member within the boundaries of another object, then this method will return `NO_UID` instead.

See also
  UID for more details

Definition at line 913 of file Serialization.cpp.

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

## 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 1028 of file Serialization.cpp.

## remove()

void Serialization::Object::remove | ( | const Member & | member | ) |

protected

Definition at line 1262 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);
};
Serialization::Archive
Destination container for serialization, and source container for deserialization.
Definition Serialization.h:1096

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

## setMinVersion()

void Serialization::Object::setMinVersion | ( | Version | v | ) |

protected

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

References Serialization::UID::id, and uid().

## setVersion()

void Serialization::Object::setVersion | ( | Version | v | ) |

protected

Definition at line 1196 of file Serialization.cpp.

## 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 1002 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 897 of file Serialization.cpp.

References Serialization::NO_UID.

Referenced by memberByUID(), Object(), 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 993 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 1042 of file Serialization.cpp.

Referenced by isVersionCompatibleTo().

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

- Serialization.h
- Serialization.cpp