RTI Connext Modern C++ API
Version 7.0.0
|
<<value-type>> A data sample of any complex data type, which can be inspected and manipulated reflectively. More...
#include <dds/core/xtypes/DynamicData.hpp>
Public Member Functions | |
DynamicData (const dds::core::xtypes::DynamicType &type) | |
Creates a DynamicData instance for a type. More... | |
DynamicData (const dds::core::xtypes::DynamicType &type, const DynamicDataProperty &property) | |
Creates a DynamicData instance for a type with specific memory-management. More... | |
template<typename T > | |
void | value (const std::string &name, const T &v) |
Sets the value of a member by member name. More... | |
template<typename T > | |
void | value (uint32_t index, const T &v) |
Sets the value of a member by member index. More... | |
template<typename T > | |
T | value (const std::string &name) const |
Gets the value of a member by member name. More... | |
template<typename T > | |
T | value (uint32_t index) const |
Gets the value of a member by member index. More... | |
template<typename T > | |
void | get_values (const std::string &name, std::vector< T > &out_array) const |
Obtains the values of an array or sequence member by member name. More... | |
template<typename T > | |
void | get_values (uint32_t index, std::vector< T > &out_array) const |
Obtains the values of an array or sequence member by member index. More... | |
template<typename T > | |
std::vector< T > | get_values (uint32_t index) const |
Obtains the values of an array or sequence member by member index. More... | |
template<typename T > | |
std::vector< T > | get_values (const std::string &name) const |
Obtains the values of an array or sequence member by member name. More... | |
template<typename T > | |
void | set_values (uint32_t index, const std::vector< T > &v) |
Sets the values of an array or sequence member by member index. More... | |
template<typename T > | |
void | set_values (const std::string &name, const std::vector< T > &v) |
Sets the values of an array or sequence member by member name. More... | |
LoanedDynamicData | loan_value (const std::string &name) |
Gets a view of a complex member. More... | |
LoanedDynamicData | loan_value (uint32_t index) |
Gets a view of a complex member. More... | |
LoanedDynamicData & | loan_value (LoanedDynamicData &data, const std::string &name) |
Gets a view of a complex member. More... | |
LoanedDynamicData & | loan_value (LoanedDynamicData &data, uint32_t mid) |
Gets a view of a complex member. More... | |
uint32_t | discriminator_value () const |
Obtains the value of the union discriminator (UnionType only) More... | |
void | clear_all_members () |
Clear the contents of all data members of this object, including key members. More... | |
void | clear_optional_member (const std::string &name) |
Clear the contents of a single optional data member of this object. More... | |
void | clear_optional_member (uint32_t index) |
Clear the contents of a single optional data member of this object. More... | |
void | clear_member (const std::string &name) |
Clear the contents of a single data member of this object. More... | |
void | clear_member (uint32_t index) |
Clear the contents of a single data member of this object. More... | |
const dds::core::xtypes::DynamicType & | type () const |
Gets the data type of this DynamicData. More... | |
dds::core::xtypes::TypeKind | type_kind () const |
Gets the data type kind of this DynamicData. More... | |
uint32_t | member_count () const |
Get the number of members in this sample. More... | |
bool | member_exists (const std::string &name) const |
Indicates whether a member exists in this sample. More... | |
bool | member_exists (uint32_t index) const |
Indicates whether a member exists in this sample. More... | |
bool | member_exists_in_type (const std::string &name) const |
Indicates whether a member with a particular name exists in type() More... | |
bool | member_exists_in_type (uint32_t index) const |
Indicates whether a member of a particular index exists in type() More... | |
DynamicDataInfo | info () const |
Returns information about this sample. More... | |
rti::core::xtypes::DynamicDataMemberInfo | member_info (const std::string &name) const |
Returns information about a member. More... | |
rti::core::xtypes::DynamicDataMemberInfo | member_info (uint32_t index) const |
Returns information about a member. More... | |
uint32_t | member_index (const std::string &name) const |
Translates from member name to member index. More... | |
bool | is_member_key (const std::string &name) const |
Returns whether a member is a key. More... | |
bool | is_member_key (uint32_t index) const |
Returns whether a member is a key. More... | |
Related Functions | |
(Note that these are not member functions.) | |
std::vector< char > & | to_cdr_buffer (std::vector< char > &buffer, const DynamicData &sample, dds::core::policy::DataRepresentationId representation_id=dds::core::policy::DataRepresentation::auto_id()) |
<<extension>> Serializes a DynamicData sample into CDR format More... | |
DynamicData & | from_cdr_buffer (DynamicData &sample, const std::vector< char > &buffer) |
<<extension>> Creates a DynamicData sample by deserializing a CDR buffer' More... | |
template<typename TopicType > | |
TopicType | convert (const DynamicData &sample) |
<<extension>> Creates a typed sample from a DynamicData sample. More... | |
template<typename TopicType > | |
DynamicData | convert (const TopicType &sample) |
<<extension>> Creates a DynamicData sample from a typed sample More... | |
template<typename TopicType > | |
bool | can_convert (const DynamicData &sample) |
<<extension>> Determines if the DynamicType of this sample is equal to the DynamicType of TopicType More... | |
template<typename... Types> | |
std::tuple< Types... > | get_tuple (const dds::core::xtypes::DynamicData &data) |
<<C++11>> <<experimental>> <<extension>> Retrieves all the values of a DynamicData object into an std::tuple at once More... | |
template<typename... Types> | |
void | set_tuple (dds::core::xtypes::DynamicData &data, const std::tuple< Types... > &value) |
<<C++11>> <<experimental>> <<extension>> Assigns the values of a std::tuple to a DynamicData object at once More... | |
<<value-type>> A data sample of any complex data type, which can be inspected and manipulated reflectively.
DynamicData allows manipulating a data sample whose type is unknown at compilation time. A DynamicData object is created by passing its DynamicType, which can be a StructType, a UnionType, ArrayType, SequenceType or AliasType. DynamicData is a valid topic-type, so you can instantiate a Topic<DynamicData> (using the constructor that receives a DynamicType), and then a DataReader<DynamicData> or a DataWriter<DynamicData>.
Several overloaded versions of the function value() allow reading or writing the value of a member by name or index. Another set of functions, loan_value(), can access a non-primitive member (for reading and writing) without making a copy. For primitive arrays and sequences DynamicData also provides a way to get or set all the values at once, using set_values() and get_values().
A number of other functions allow querying information about the sample and its type.
Applications that use both statically typed data and DynamicData can benefit from the conversion between them, using rti::core::xtypes::convert().
For examples on how to use DynamicData, see Using DynamicData.
As mentioned before, to access a member you need to specify its name or its index. Depending on the DynamicType of the DynamicData sample, the name may apply or not and the index can mean different things. This table summarizes that:
DynamicType of the sample | Can access by name? | What does index mean? |
---|---|---|
StructType | Yes | The position of the member in the type (starting at 1) |
UnionType | Yes | The value of the label that selects a member, see discriminator_value() |
ArrayType | No | The position of the element in the array (1 to ArrayType::total_element_count()) |
SequenceType | No | The position of the element in the sequence (1 to member_count()) or past member_count() to increase the length of the sequence. |
Any other type | N/A | N/A |
For example, given the following IDL description of a type:
If we have a DynamicData sample
representing data of that type, we can access the member y
in two different ways:
Accessing a member by index can be more efficient, so when accessing a member repeatedly it may be beneficial to obtain its index first:
For an example on how to access a union member, see discriminator_value(), and for more examples, including how to access elements in a collection see Using DynamicData.
It is possible to refer to a nested member in a type without first having to use the loan_value() API. You can do this by using a hierarchical name. A hierarchical member name is a concatenation of member names separated by the '.' character. The hierarchical name describes the complete path from a top-level type to the nested member. For example, in the following type:
any DynamicData API that receives a member name will accept "theNestedType.theChar" to refer to the char member in MyNestedType:
In order to access the value of theChar
without using a hierarchical name, you would have to first bind to theNestedType and then get the value:
As you can see, using a hierarchical member name removes the need to call the loan_value() API, and allows for access to nested members at any depth directly from the top-level type.
The member name can also contain indexes to address members in arrays and sequences. For example, to set the third member in the array theOctetArray
, you can pass in "theNestedType.theOctetArray[2]" as the member name. The index values when used as part of the member name are 0-based.
For multi-dimensional arrays, the indexes for each dimension should be listed comma-separated in between brackets. For example, to address a member of theMultidimensionalArray
, the member name should be something like "theNestedType.theMultidimensionalArray[3,2,5]".
In complex types with arrays and sequences that contain other arrays and sequences, the hierarchical name may include multiple index values, one right after another. For example, in MyNestedType, myArrayOfSeq
is an array of sequences. In order to set the third member of the sequence in the fourth member of the array, the member name would be "myNestedType.myArrayOfSeq[3][2]".
The different DynamicData functions that access members may throw the following exceptions:
T
of the function. For example assumming that my_string_member
is a string, the two following statements are illegal: dds::core::xtypes::DynamicData::DynamicData | ( | const dds::core::xtypes::DynamicType & | type | ) |
Creates a DynamicData instance for a type.
Uses default DynamicDataProperty.
type | The type of this data sample |
dds::core::xtypes::DynamicData::DynamicData | ( | const dds::core::xtypes::DynamicType & | type, |
const DynamicDataProperty & | property | ||
) |
Creates a DynamicData instance for a type with specific memory-management.
type | The type of this data sample |
property | Memory-management configuration |
void dds::core::xtypes::DynamicData::value | ( | const std::string & | name, |
const T & | v | ||
) |
Sets the value of a member by member name.
T | The type of the member to set. The possible types are:
|
For examples on how to set member values, see Publishing data using DynamicData.
If the member is optional and unset, this function will set it. To unset it again, see clear_optional_member().
It is not always possible to rely on inferring the type T
based on the argument v
. For example, if the member being set is a short, this statement will throw an exception, because T
is deduced as int:
There are two ways to specify that the member is a short
:
name | The member name, see Member Names and Indexes. This function also allows to access nested members |
v | The value to set for that member |
See | Exceptions accessing a member |
void dds::core::xtypes::DynamicData::value | ( | uint32_t | index, |
const T & | v | ||
) |
Sets the value of a member by member index.
index | The position of the member in the type, see Member Names and Indexes. |
v | The value to set for that member |
See | Exceptions accessing a member |
T dds::core::xtypes::DynamicData::value | ( | const std::string & | name | ) | const |
Gets the value of a member by member name.
T | The type of the member. See value(const std::string&, const T&) |
For examples on how to get member values, see Subscribing to data using DynamicData.
name | The member name, see Member Names and Indexes. |
See | Exceptions accessing a member |
T dds::core::xtypes::DynamicData::value | ( | uint32_t | index | ) | const |
Gets the value of a member by member index.
T | The type of the member. See value(const std::string&, const T&) |
For examples on how to get member values, see Subscribing to data using DynamicData.
index | The position of the member in the type, see Member Names and Indexes. |
See | Exceptions accessing a member |
void dds::core::xtypes::DynamicData::get_values | ( | const std::string & | name, |
std::vector< T > & | out_array | ||
) | const |
Obtains the values of an array or sequence member by member name.
This function reuses an existing vector
T | The element type of the array or sequence. These are the possible types:
|
name | The member name, see Member Names and Indexes. |
out_array | A vector containing the values of that array or sequence. The vector will be resized accordingly. |
void dds::core::xtypes::DynamicData::get_values | ( | uint32_t | index, |
std::vector< T > & | out_array | ||
) | const |
Obtains the values of an array or sequence member by member index.
This function reuses an existing vector
T | The element type of the array or sequence. (See get_values(const std::string&, std::vector<T>&) const) |
index | The position of the array or sequence member in the type, see Member Names and Indexes. |
out_array | A vector containing the values of that array or sequence. The vector will be resized accordingly. |
std::vector<T> dds::core::xtypes::DynamicData::get_values | ( | uint32_t | index | ) | const |
Obtains the values of an array or sequence member by member index.
This function returns a new vector.
T | The element type of the array or sequence. (See get_values(const std::string&, std::vector<T>&) const) |
index | The position of the array or sequence member in the type |
std::vector<T> dds::core::xtypes::DynamicData::get_values | ( | const std::string & | name | ) | const |
Obtains the values of an array or sequence member by member name.
This function returns a new vector.
T | The element type of the array or sequence. (See get_values(const std::string&, std::vector<T>&) const) |
name | The member name, see Member Names and Indexes. |
void dds::core::xtypes::DynamicData::set_values | ( | uint32_t | index, |
const std::vector< T > & | v | ||
) |
Sets the values of an array or sequence member by member index.
T | The element type of the array or sequence. (See get_values(const std::string&, std::vector<T>&) const) |
index | The position of the array or sequence member in the type |
v | A vector containing the values to be set for that array or sequence. |
void dds::core::xtypes::DynamicData::set_values | ( | const std::string & | name, |
const std::vector< T > & | v | ||
) |
Sets the values of an array or sequence member by member name.
T | The element type of the array or sequence. (See get_values(const std::string&, std::vector<T>&) const) |
name | The member name, see Member Names and Indexes. |
v | A vector containing the values to be set for that array or sequence. |
LoanedDynamicData dds::core::xtypes::DynamicData::loan_value | ( | const std::string & | name | ) |
Gets a view of a complex member.
This function returns a new LoanedDynamicData instance.
Only a single member of a given DynamicData object may be loaned at a time. However, members of members may be recursively loaned to any depth. Furthermore, while the outer object has a bound member, it may only be modified through that bound member. That is, after loaning this member, the outer object disables all calls to set value() until the loan is returned.
This method, as opposed to value<DynamicData>() doesn't make a copy; it provides a view of the member so changes to the loaned member change the outer object.
name | The member name, see Member Names and Indexes. |
LoanedDynamicData dds::core::xtypes::DynamicData::loan_value | ( | uint32_t | index | ) |
Gets a view of a complex member.
This function returns a new LoanedDynamicData instance.
index | The position of the member in the type, see Member Names and Indexes. |
LoanedDynamicData& dds::core::xtypes::DynamicData::loan_value | ( | LoanedDynamicData & | data, |
const std::string & | name | ||
) |
Gets a view of a complex member.
This function reuses a LoanedDynamicData instance, returning its previous loan.
data | The object to access the complex member |
name | The member name, see Member Names and Indexes. |
LoanedDynamicData& dds::core::xtypes::DynamicData::loan_value | ( | LoanedDynamicData & | data, |
uint32_t | mid | ||
) |
Gets a view of a complex member.
This function reuses a LoanedDynamicData instance, returning its previous loan.
data | The object to access the complex member |
mid | The position of the member in the type, see Member Names and Indexes. |
uint32_t dds::core::xtypes::DynamicData::discriminator_value | ( | ) | const |
Obtains the value of the union discriminator (UnionType only)
Use the value that this function returns in any function expecting a member index to access the active member in this union.
For example, given the following IDL Union:
If we have a DynamicData sample
of that type whose active member is "y", we can access it as follows:
If you set a different member, the discriminator value automatically changes:
void dds::core::xtypes::DynamicData::clear_all_members | ( | ) |
Clear the contents of all data members of this object, including key members.
One | of the Standard Exceptions |
void dds::core::xtypes::DynamicData::clear_optional_member | ( | const std::string & | name | ) |
Clear the contents of a single optional data member of this object.
name | The member name, see Member Names and Indexes. |
void dds::core::xtypes::DynamicData::clear_optional_member | ( | uint32_t | index | ) |
Clear the contents of a single optional data member of this object.
index | The position of the member in the type, see Member Names and Indexes. |
void dds::core::xtypes::DynamicData::clear_member | ( | const std::string & | name | ) |
Clear the contents of a single data member of this object.
name | The member name, see Member Names and Indexes. |
void dds::core::xtypes::DynamicData::clear_member | ( | uint32_t | index | ) |
Clear the contents of a single data member of this object.
index | The position of the member in the type, see Member Names and Indexes. |
const dds::core::xtypes::DynamicType& dds::core::xtypes::DynamicData::type | ( | ) | const |
Gets the data type of this DynamicData.
dds::core::xtypes::TypeKind dds::core::xtypes::DynamicData::type_kind | ( | ) | const |
Gets the data type kind of this DynamicData.
uint32_t dds::core::xtypes::DynamicData::member_count | ( | ) | const |
Get the number of members in this sample.
For objects of type ArrayType or SequenceType, this method returns the number of elements in the collection.
For objects of type kind StructType, it returns the number of fields in the sample, which will always be the same as the number of fields in the type.
bool dds::core::xtypes::DynamicData::member_exists | ( | const std::string & | name | ) | const |
Indicates whether a member exists in this sample.
If the member doesn't exist in the type, this function returns false. In all other cases, it provides the same result as rti::core::xtypes::DynamicDataMemberInfo::member_exists(), which is retrieved with member_info()).
name | The member name, see Member Names and Indexes. |
bool dds::core::xtypes::DynamicData::member_exists | ( | uint32_t | index | ) | const |
Indicates whether a member exists in this sample.
If the member doesn't exist in the type, this function returns false. In all other cases, it provides the same result as rti::core::xtypes::DynamicDataMemberInfo::member_exists(), which is retrieved with member_info()).
index | The member index, see Member Names and Indexes. |
bool dds::core::xtypes::DynamicData::member_exists_in_type | ( | const std::string & | name | ) | const |
Indicates whether a member with a particular name exists in type()
bool dds::core::xtypes::DynamicData::member_exists_in_type | ( | uint32_t | index | ) | const |
Indicates whether a member of a particular index exists in type()
DynamicDataInfo dds::core::xtypes::DynamicData::info | ( | ) | const |
Returns information about this sample.
rti::core::xtypes::DynamicDataMemberInfo dds::core::xtypes::DynamicData::member_info | ( | const std::string & | name | ) | const |
Returns information about a member.
When name
identifies a field in a struct or union:
When name
identifies a sequence element, such as "my_sequence[i]"
:
i
is greater than the sequence's maximum length, this function throws dds::core::InvalidArgumentError.i
is greater than the sequence's current length but smaller than its maximum length, this function returns an object with rti::core::xtypes::DynamicDataMemberInfo::member_exists() set to false.i
is smaller than or equal to the current length, rti::core::xtypes::DynamicDataMemberInfo::member_exists() is true.When name
identifies an array element, such as "my_array[i]
, this function either throws when the i
is out of bounds or else returns an object with rti::core::xtypes::DynamicDataMemberInfo::member_exists() set to true.
name | The member name, see Member Names and Indexes. |
dds::core::InvalidArgumentError | if the member doesn't exist in the type, or Standard Exceptions. |
rti::core::xtypes::DynamicDataMemberInfo dds::core::xtypes::DynamicData::member_info | ( | uint32_t | index | ) | const |
Returns information about a member.
When this sample represents a struct and index
is the position of the member in the type definition, or when the sample represents a union and index
is the discriminator value:
When this sample represents a sequence and index
is the 1-based element index:
index
is greater than the sequence's maximum length, this function throws dds::core::InvalidArgumentError.index
is greater than the sequence's current length but smaller than its maximum length, this function returns an object with rti::core::xtypes::DynamicDataMemberInfo::member_exists() set to false.index
is smaller than or equal to the current length, rti::core::xtypes::DynamicDataMemberInfo::member_exists() is true.When this sample represents an array this function either throws dds::core::InvalidArgumentError when the index is out of bounds or else returns an object with rti::core::xtypes::DynamicDataMemberInfo::member_exists() set to true.
index | The member index, see Member Names and Indexes. |
dds::core::InvalidArgumentError | if the member doesn't exist in the type or the element with this index doesn't exist in this sequence. See also Standard Exceptions. |
uint32_t dds::core::xtypes::DynamicData::member_index | ( | const std::string & | name | ) | const |
Translates from member name to member index.
name | The member name, see Member Names and Indexes. |
See | Exceptions accessing a member |
bool dds::core::xtypes::DynamicData::is_member_key | ( | const std::string & | name | ) | const |
Returns whether a member is a key.
name | The member name, see Member Names and Indexes. |
See | Exceptions accessing a member |
bool dds::core::xtypes::DynamicData::is_member_key | ( | uint32_t | index | ) | const |
Returns whether a member is a key.
index | The member index, see Member Names and Indexes. |
See | Exceptions accessing a member |
|
related |
<<extension>> Serializes a DynamicData sample into CDR format
buffer | The output buffer, which will be resized to the correct size |
sample | The sample to serialize |
representation_id | The data representation used to serialize the data |
buffer
|
related |
<<extension>> Creates a DynamicData sample by deserializing a CDR buffer'
sample | The sample to deserialize. |
buffer | The buffer containing the CDR data |
sample
|
related |
<<extension>> Creates a typed sample from a DynamicData sample.
This function is useful when an application uses DynamicData and regular typed Topics at the same time.
For example, given this IDL type:
We can convert from Foo
and DynamicData:
TopicType | An IDL topic-type |
sample | The DynamicData sample to convert to type TopicType |
TopicType
containing the data in sample
.
|
related |
<<extension>> Creates a DynamicData sample from a typed sample
TopicType | An IDL topic-type |
sample | The typed sample to convert to DynamicData |
sample
|
related |
<<extension>> Determines if the DynamicType of this sample is equal to the DynamicType of TopicType
TopicType | An IDL topic-type |
TopicType
from this DynamicData object.
|
related |
<<C++11>> <<experimental>> <<extension>> Retrieves all the values of a DynamicData object into an std::tuple at once
|
related |
<<C++11>> <<experimental>> <<extension>> Assigns the values of a std::tuple to a DynamicData object at once