Working with IDL types

How IDL types map to C++ classes. More...

Classes
class	Foo
	An example topic-type. More...

Detailed Description

How IDL types map to C++ classes.

Example IDL types

The following IDL code defines the types we will use in these examples.

struct Foo {
    long x; //@key
    long y;
};
 
struct MyType {
    long my_long;
    string<512> my_string;
    Foo my_foo;
    sequence<long, 10> my_sequence;
    Foo my_array[5];
    Foo my_optional; //@Optional
};

To generate C++ code for these types, see the Code Generator User's Manual.

Constructors and operators

C++ types generated from IDL have value semantics and provide a default constructor, a copy constructor, a move constructor <<C++11>>, a constructor with parameters to set all the type's members, a destructor, a copy-assignment operator, and a move-assignment operator <<C++11>>. Types also include equality operators, the operator << to std::ostream <<extension>> and a namespace-level swap function.

 
    // The default constructor recursively initializes all members of a sample
    MyType default_sample;
 
    // A copy constructor is also provided
    MyType copied_sample = default_sample;
 
    // For convenience, another constructor allows initializing all the members
    MyType initialized_sample (
        7, // my_long
        std::string("Hello, World!"), // my_string
        Foo(1, 2), // my_foo (initializing its members 'x' and 'y')
        std::vector<int32_t>(3, 2), // my_sequence containing 3 times the value 2
        dds::core::array<Foo, 5>(), // my_array
        Foo(2, 3) // my_optional (initialized with a non-empty value)
    );
 
    // An assignment operator is also available
    copied_sample = initialized_sample;
 
    // Equals operator (!= also available)
    if (copied_sample == initialized_sample) {
        std::cout << "Samples are equal\n";
    }
 
    // You can move a value into a member:
    std::vector<int32_t> tmp_vector {1, 2, 3, 4};
    copied_sample.my_sequence() = std::move(tmp_vector);
 
    std::cout << "You can print samples to an output stream: "
              << copied_sample
              << std::endl;
 

In addition to that, a number of traits provide additional information and utilities for IDL-generated types.

Accessing the type members

Struct members are public. Setters and getters provide access to union members.

The following table summarizes how different IDL types map to C++.

IDL type	C++ type
string	std::string
bounded sequence (sequence<T, M>)	rti::core::bounded_sequence<T, M>
unbounded sequence (sequence<T>)	std::vector<T>
array (T member[N])	std::array<T, N>
optional member (@optional T member; )	dds::core::optional<T>
external member (@external T member; )	dds::core::external<T>

The type rti::core::bounded_sequence offers similar functionality to that of a std::vector. But because it has an upper bound M, it provides two advantages:

1) A better memory management strategy for deserializing data samples in a DataReader, improving the overall performance of the middleware.

2) Its member functions check for out-of-bounds growth.

It is possible to use std::vector for bounded sequences by annotating them with @use_vector in IDL. For example:

struct SequenceExample {
    @use_vector sequence<long, 10> bounded_sequence_as_vector;
    sequence<long, 10> bounded_sequence;
    sequence<long> unbounded_sequence;
};

The type dds::core::array is just an alias of std::array if available, or an alias of boost::array otherwise.

Enumerations

IDL enums map to enum class types in C++.

Unions

IDL unions map to C++ classes with getters and setters for each member, plus a especial getter and setter for the discriminator, _d(). At any moment only one member, the one selected by the discriminator, is considered active. A member getter will throw dds::core::PreconditionNotMetError if the discriminator selects a different member.

Member setters set the correct discriminator value automatically.

The default constructor default-constructs all the members and selects the discriminator returned by the static member function default_discriminator().

The following example shows an IDL union and C++ code to manipulate it.

• IDL definition:

   
  enum MyUnionDiscriminator {
      USE_LONG,
      USE_STRING,
      USE_FOO
  };
   
  union MyUnion switch (MyUnionDiscriminator) {
  case USE_LONG:
      long my_long;
  case USE_STRING:
      string my_string;
  case USE_FOO:
      Foo my_foo;
  };

• C++ example:

   
      MyUnion my_sample;
   
      // Set a member
      my_sample.my_string("Hello, World!");
   
      // The discriminator is automatically updated
      assert (my_sample._d() == MyUnionDiscriminator::USE_STRING);
   
      // Access that member
      std::cout << my_sample.my_string() << std::endl;
   
      // Trying to access my_long() will throw an exception:
      try {
          std::cout << my_sample.my_long() << std::endl;
      } catch (const dds::core::PreconditionNotMetError&) {
          std::cout << "my_long is not selected!\n";
      }
   
      // First, set it
      my_sample.my_long(4);
      std::cout << my_sample.my_long() << std::endl;
   
      // Trying to access my_foo() to modify a nested member will also fail
      try {
          my_sample.my_foo().x(3);
      } catch (const dds::core::PreconditionNotMetError&) {
          std::cout << "my_foo is not selected!\n";
      }
   
      // First change the discriminator
      my_sample._d(MyUnionDiscriminator::USE_FOO);
      my_sample.my_foo().x(3); // now it works
   
   
      std::cout << my_sample << std::endl;