RTI Connext Modern C++ API  Version 5.2.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::core::xtypes::DynamicData Class Reference

<<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.
 
 DynamicData (const dds::core::xtypes::DynamicType &type, const DynamicDataProperty &property)
 Creates a DynamicData instance for a type with specific memory-management.
 
template<typename T >
void value (const std::string &name, const T &v)
 Sets the value of a member by member name.
 
template<typename T >
void value (uint32_t index, const T &v)
 Sets the value of a member by member index.
 
template<typename T >
value (const std::string &name) const
 Gets the value of a member by member name.
 
template<typename T >
value (uint32_t index) const
 Gets the value of a member by member index.
 
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.
 
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.
 
template<typename T >
std::vector< T > get_values (uint32_t index) const
 Obtains the values of an array or sequence member by member index.
 
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.
 
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.
 
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.
 
LoanedDynamicData loan_value (const std::string &name)
 Gets a view of a complex member.
 
LoanedDynamicData loan_value (uint32_t index)
 Gets a view of a complex member.
 
LoanedDynamicData & loan_value (LoanedDynamicData &data, const std::string &name)
 Gets a view of a complex member.
 
LoanedDynamicData & loan_value (LoanedDynamicData &data, uint32_t mid)
 Gets a view of a complex member.
 
uint32_t discriminator_value () const
 Obtains the value of the union discriminator (UnionType only)
 
void clear_all_members ()
 Clear the contents of all data members of this object, including key members.
 
void clear_optional_member (const std::string &name)
 Clear the contents of a single optional data member of this object.
 
void clear_optional_member (uint32_t index)
 Clear the contents of a single optional data member of this object.
 
void set_buffer (uint8_t *storage, int32_t size)
 Associate a buffer with this dynamic data object.
 
int32_t estimated_max_buffer_size () const
 Get the estimated maximum buffer size for a DynamicData object.
 
const
dds::core::xtypes::DynamicType
type () const
 Gets the data type of this DynamicData.
 
dds::core::xtypes::TypeKind type_kind () const
 Gets the data type kind of this DynamicData.
 
uint32_t member_count () const
 Get the number of members in this sample.
 
bool member_exists (const std::string &name) const
 Determines if an optional member is set by member name.
 
bool member_exists (uint32_t index) const
 Determines if an optional member is set by member index.
 
bool member_exists_in_type (const std::string &name) const
 Indicates whether a member with a particular name exists in type()
 
bool member_exists_in_type (uint32_t index) const
 Indicates whether a member of a particular index exists in type()
 
DynamicDataInfo info () const
 Returns information about this sample.
 
DynamicDataMemberInfo member_info (const std::string &name) const
 Returns information about a member.
 
DynamicDataMemberInfo member_info (uint32_t index) const
 Returns information about a member.
 
uint32_t member_index (const std::string &name) const
 Translates from member name to member index.
 
bool is_member_key (const std::string &name) const
 Returns whether a member is a key.
 
bool is_member_key (uint32_t index) const
 Returns whether a member is a key.
 

Related Functions

(Note that these are not member functions.)

std::vector< char > & to_cdr_buffer (std::vector< char > &buffer, const DynamicData &sample)
 <<extension>> Serializes a DynamicData sample into CDR format
 
DynamicDatafrom_cdr_buffer (DynamicData &sample, const std::vector< char > &buffer)
 <<extension>> Creates a DynamicData sample by deserializing a CDR buffer'
 
template<typename TopicType >
TopicType convert (const DynamicData &sample)
 <<extension>> Creates a typed sample from a DynamicData sample.
 
template<typename TopicType >
DynamicData convert (const TopicType &sample)
 <<extension>> Creates a DynamicData sample from a typed sample
 
template<typename TopicType >
bool can_convert (const DynamicData &sample)
 <<extension>> Determines if the DynamicType of this sample is equal to the DynamicType of TopicType
 
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
 
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
 

Detailed Description

<<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.

Member Names and Indexes

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:

struct Foo {
long x;
long y;
};

If we have a DynamicData sample representing data of that type, we can access the member y in two different ways:

sample.value("y", 33); // Set value to 33
sample.value(2, 33); // Same effect

Accessing a member by index can be more efficient, so when accessing a member repeatedly it may be beneficial to obtain its index first:

const uint32_t y_index = sample.member_index("y");
while (...) {
int32_t y_value = sample.value<int32_t>(y_index);
// ...
}

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.

Exceptions accessing a member

The different DynamicData functions that access members may throw the following exceptions:

  • dds::core::InvalidArgumentError when attempting to get the value a member that doesn't exist in the type, is optional and is not set, or is part of a union and not currently selected (see discriminator_value). Attempting to set an unset optional member or an unselected union member is legal and will set the optional member or change the active union member.
  • dds::core::IllegalOperationError when attempting to get or set a member of the wrong type–that is, when the DynamicType of that member doesn't match the template type T of the function. For example assumming that my_string_member is a string, the two following statements are illegal:
    data.value("my_string_member", 3);
    int v = data.value<int>("my_string_member");
See Also
Using DynamicData

Constructor & Destructor Documentation

dds::core::xtypes::DynamicData::DynamicData ( const dds::core::xtypes::DynamicType type)

Creates a DynamicData instance for a type.

Uses default DynamicDataProperty.

Precondition
!is_primitive(type) – a DynamicData object cannot encapsulate a primitive type.
Parameters
typeThe 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.

Precondition
!is_primitive(type) – a DynamicData object cannot encapsulate a primitive type.
Parameters
typeThe type of this data sample
propertyMemory-management configuration

Member Function Documentation

template<typename T >
void dds::core::xtypes::DynamicData::value ( const std::string &  name,
const T &  v 
)

Sets the value of a member by member name.

Template Parameters
TThe type of the member to set. The possible types are: those accepted by PrimitiveType, std::string or dds::core::string, and DynamicData.

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().

Note that 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:

sample.value("my_short", 10);

To solve this problem we have two options:

sample.value<short>("my_short", 10);
sample.value("my_short", (short) 10);
Parameters
nameThe member name, see Member Names and Indexes. This function also allows to access nested members
vThe value to set for that member
Exceptions
SeeExceptions accessing a member
See Also
member_exists(const std::string&) const
Publishing data using DynamicData
template<typename T >
void dds::core::xtypes::DynamicData::value ( uint32_t  index,
const T &  v 
)

Sets the value of a member by member index.

Parameters
indexThe position of the member in the type, see Member Names and Indexes.
vThe value to set for that member
Exceptions
SeeExceptions accessing a member
See Also
value(const std::string&, const T&)
Member Names and Indexes
template<typename T >
T dds::core::xtypes::DynamicData::value ( const std::string &  name) const

Gets the value of a member by member name.

Template Parameters
TThe 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.

Parameters
nameThe member name, see Member Names and Indexes.
Returns
The value of that member
Exceptions
SeeExceptions accessing a member
See Also
value(const std::string&, const T&)
Subscribing to data using DynamicData
template<typename T >
T dds::core::xtypes::DynamicData::value ( uint32_t  index) const

Gets the value of a member by member index.

Template Parameters
TThe 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.

Parameters
indexThe position of the member in the type, see Member Names and Indexes.
Returns
The value of that member
Exceptions
SeeExceptions accessing a member
See Also
value(const std::string&, const T&)
Member Names and Indexes
template<typename T >
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

Template Parameters
TThe element type of the array or sequence. These are the possible types: char, (u)int8_t, (u)int16_t, DDS_Long, DDS_UnsignedLong, DDS_LongLong, DDS_UnsignedLongLong, float, double. The types int and unsigned int may be used instead of DDS_Long and DDS_UnsignedLong except in some platforms (VxWorks).
Parameters
nameThe member name, see Member Names and Indexes.
out_arrayA vector containing the values of that array or sequence. The vector will be resized accordingly.
template<typename T >
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

Template Parameters
TThe element type of the array or sequence.
Parameters
indexThe position of the array or sequence member in the type, see Member Names and Indexes.
out_arrayA vector containing the values of that array or sequence. The vector will be resized accordingly.
See Also
Member Names and Indexes
get_values(const std::string& name, std::vector<T>& out_array) const
template<typename T >
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.

Template Parameters
TThe element type of the array or sequence
Parameters
indexThe position of the array or sequence member in the type
Returns
A vector containing the values of that array or sequence.
See Also
Member Names and Indexes
get_values(const std::string& name, std::vector<T>& out_array) const
template<typename T >
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.

Template Parameters
TThe element type of the array or sequence
Parameters
nameThe member name, see Member Names and Indexes.
Returns
A vector containing the values of that array or sequence.
See Also
get_values(const std::string& name, std::vector<T>& out_array) const
template<typename T >
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.

Template Parameters
TThe element type of the array or sequence
Parameters
indexThe position of the array or sequence member in the type
vA vector containing the values to be set for that array or sequence.
See Also
Member Names and Indexes
get_values(const std::string& name, std::vector<T>& out_array) const
template<typename T >
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.

Template Parameters
TThe element type of the array or sequence.
Parameters
nameThe member name, see Member Names and Indexes.
vA vector containing the values to be set for that array or sequence.
See Also
get_values(const std::string& name, std::vector<T>& out_array) const
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.

Parameters
nameThe member name, see Member Names and Indexes.
Returns
The object to access the complex member
See Also
rti::core::xtypes::LoanedDynamicData
Using DynamicData.
LoanedDynamicData dds::core::xtypes::DynamicData::loan_value ( uint32_t  index)

Gets a view of a complex member.

This function returns a new LoanedDynamicData instance.

Parameters
indexThe position of the member in the type, see Member Names and Indexes.
Returns
The object to access the complex member
See Also
loan_value(const std::string&)
rti::core::xtypes::LoanedDynamicData
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.

Parameters
dataThe object to access the complex member
nameThe member name, see Member Names and Indexes.
See Also
loan_value(const std::string&)
rti::core::xtypes::LoanedDynamicData
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.

Parameters
dataThe object to access the complex member
midThe position of the member in the type, see Member Names and Indexes.
See Also
loan_value(const std::string&)
rti::core::xtypes::LoanedDynamicData
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:

union Foo switch (short) {
case 1:
long x;
case 2:
case 3:
string y;
};

If we have a DynamicData sample of that type whose active member is "y", we can access it as follows:

std::string y_value = sample.value<std::string>(sample.discriminator_value());
y_value = sample.value<std::string>("y"); // Same effect
y_value = sample.value<std::string>(3); // Same effect

If you set a different member, the discriminator value automatically changes:

sample.value("x", 10);
assert (sample.discriminator_value() == 1);
Precondition
type().kind() == TypeKind::UNION_TYPE – Only applies to samples of a UnionType.
Returns
The value of this sample's discriminator.
void dds::core::xtypes::DynamicData::clear_all_members ( )

Clear the contents of all data members of this object, including key members.

MT Safety:
UNSAFE.
Exceptions
Oneof the Standard Exceptions
See Also
DynamicData::clear_optional_member
void dds::core::xtypes::DynamicData::clear_optional_member ( const std::string &  name)

Clear the contents of a single optional data member of this object.

Parameters
nameThe 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.

Parameters
indexThe position of the member in the type, see Member Names and Indexes.
void dds::core::xtypes::DynamicData::set_buffer ( uint8_t *  storage,
int32_t  size 
)

Associate a buffer with this dynamic data object.

The DynamicData object will use the input buffer to store its value.

If the DynamicData object already has a value, this function will clear the contents of all data members.

The memory of the buffer being replaced will be freed, unless the buffer was assigned by a previous call to this method.

If the size of the input buffer is not big enough to hold the future value of the DynamicData object, the set operations will return dds::core::OutOfResourcesError when the size is exceeded.

The internal representation of a DynamicData object is based on CDR encapsulation and introduces additional overhead beyond the data representation of the equivalent C structure. When providing an input buffer, try to account for that overhead.

The method DynamicData::get_estimated_max_buffer_size can be used to obtain an estimated maximum size for the input buffer. This size is calculated based on an assignment pattern where the value of a data member is set a single time between calls to DynamicData::clear_all_members.

MT Safety:
UNSAFE.
Parameters
storage<<in>> Storage buffer.
size<<in>> Buffer size in bytes.
Exceptions
Oneof the Standard Exceptions
int32_t dds::core::xtypes::DynamicData::estimated_max_buffer_size ( ) const

Get the estimated maximum buffer size for a DynamicData object.

This method gets the estimated maximum buffer size of a DynamicData object based on the associated type.

The output size is calculated based on an assignment pattern where the value of a data member is set a single time between calls to DynamicData::clear_all_members.

If this is not the case (for example, the value of a string member is set multiple times), the maximum size returned by this method may not be representative.

This method can be used to obtain the size of the buffer provided to the method DynamicData::set_buffer.

MT Safety:
UNSAFE.
Exceptions
Oneof the Standard Exceptions
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.

Returns
this->type().kind().
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

Determines if an optional member is set by member name.

For a non-optional member this function always returns the same result as member_exists_in_type().

bool dds::core::xtypes::DynamicData::member_exists ( uint32_t  index) const

Determines if an optional member is set by member index.

For a non-optional member this function always returns the same result as member_exists_in_type().

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.

DynamicDataMemberInfo dds::core::xtypes::DynamicData::member_info ( const std::string &  name) const

Returns information about a member.

Parameters
nameThe member name.
Returns
Information about the member.
Exceptions
SeeExceptions accessing a member
DynamicDataMemberInfo dds::core::xtypes::DynamicData::member_info ( uint32_t  index) const

Returns information about a member.

Parameters
indexThe member index, see Member Names and Indexes.
Returns
Information about the member.
Exceptions
SeeExceptions accessing a member
uint32_t dds::core::xtypes::DynamicData::member_index ( const std::string &  name) const

Translates from member name to member index.

Parameters
nameThe member name, see Member Names and Indexes.
Returns
The member index for the member with that name
Exceptions
SeeExceptions accessing a member
bool dds::core::xtypes::DynamicData::is_member_key ( const std::string &  name) const

Returns whether a member is a key.

Parameters
nameThe member name, see Member Names and Indexes.
Exceptions
SeeExceptions accessing a member
bool dds::core::xtypes::DynamicData::is_member_key ( uint32_t  index) const

Returns whether a member is a key.

Parameters
indexThe member index, see Member Names and Indexes.
Exceptions
SeeExceptions accessing a member

Friends And Related Function Documentation

std::vector< char > & to_cdr_buffer ( std::vector< char > &  buffer,
const DynamicData sample 
)
related

<<extension>> Serializes a DynamicData sample into CDR format

Parameters
bufferThe output buffer, which will be resized to the correct size
sampleThe sample to serialize
Returns
A reference to buffer
DynamicData & from_cdr_buffer ( DynamicData sample,
const std::vector< char > &  buffer 
)
related

<<extension>> Creates a DynamicData sample by deserializing a CDR buffer'

Parameters
sampleThe sample to deserialize.
bufferThe buffer containing the CDR data
Returns
A reference to sample
template<typename TopicType >
TopicType convert ( const DynamicData 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:

struct Foo {
long x;
};

We can convert from Foo and DynamicData:

// Receive a DynamicData sample
assert (samples.size() > 0);
// Create a Foo sample
const DynamicData& dynamic_data = samples[0].data();
assert (can_convert<Foo>(dynamic_data));
Foo typed_data = convert<Foo>(dynamic_data);
assert (typed_data.x() == dynamic_data.value<int32_t>("x"));
Precondition
can_convert<TopicType>(sample), otherwise the behavior is undefined.
Template Parameters
TopicTypeAn IDL topic-type
Parameters
sampleThe DynamicData sample to convert to type TopicType
Returns
An instance of TopicType containing the data in sample.
template<typename TopicType >
DynamicData convert ( const TopicType &  sample)
related

<<extension>> Creates a DynamicData sample from a typed sample

Template Parameters
TopicTypeAn IDL topic-type
Parameters
sampleThe typed sample to convert to DynamicData
Returns
A new DynamicData object whose type is rti::topic::dynamic_type<TopicType> and contains the data from sample
template<typename TopicType >
bool can_convert ( const DynamicData sample)
related

<<extension>> Determines if the DynamicType of this sample is equal to the DynamicType of TopicType

Template Parameters
TopicTypeAn IDL topic-type
Returns
True if the DynamicType of TopicType is the same as this sample's and therefore it is possible to create an instance of TopicType from this DynamicData object.
See Also
convert()
template<typename... Types>
std::tuple< Types...> get_tuple ( const dds::core::xtypes::DynamicData data)
related

<<C++11>> <<experimental>> <<extension>> Retrieves all the values of a DynamicData object into an std::tuple at once

See Also
Manipulating data reflectively using C++ tuples
template<typename... Types>
void set_tuple ( dds::core::xtypes::DynamicData data,
const std::tuple< Types...> &  value 
)
related

<<C++11>> <<experimental>> <<extension>> Assigns the values of a std::tuple to a DynamicData object at once

See Also
Manipulating data reflectively using C++ tuples

RTI Connext Modern C++ API Version 5.2.0 Copyright © Sun Jun 21 2015 Real-Time Innovations, Inc