RTI Connext Modern C++ API  Version 6.1.1

Represents the Builder for an arbitrary user-defined mutable type. More...

#include <Builder.hpp>

Inheritance diagram for MyFlatMutableBuilder:
rti::flat::AggregationBuilder rti::flat::AbstractBuilder

Public Types

typedef MyFlatMutableOffset Offset
 The related offset type. More...
 

Public Member Functions

 MyFlatMutableBuilder ()
 Creates an invalid Builder. More...
 
 MyFlatMutableBuilder (unsigned char *buffer, int32_t size, bool initialize_members=false)
 Construct a Builder with an arbitrary buffer. More...
 
Offset finish ()
 Finishes building a member. More...
 
MyFlatMutablefinish_sample ()
 Finishes building a sample. More...
 
bool add_my_primitive (int32_t value)
 Adds a primitive member. More...
 
bool add_my_optional_primitive (int32_t value)
 Adds a primitive member. More...
 
rti::flat::PrimitiveArrayOffset< int32_t, 10 > add_my_primitive_array ()
 Adds a primitive array member. More...
 
rti::flat::PrimitiveSequenceBuilder< int32_t > build_my_primitive_seq ()
 Begins building a primitive-sequence member. More...
 
MyFlatFinalOffset add_my_final ()
 Adds a final complex member. More...
 
rti::flat::FinalAlignedArrayOffset< MyFlatFinalOffset, 10 > add_my_final_array ()
 Adds an array member of final complex elements. More...
 
rti::flat::FinalSequenceBuilder< MyFlatFinalOffsetbuild_my_final_seq ()
 Begins building a sequence member of final complex elements. More...
 
FlatMutableBarBuilder build_my_mutable ()
 Begins building a mutable complex member. More...
 
rti::flat::MutableArrayBuilder< FlatMutableBarBuilder, 10 > build_my_mutable_array ()
 Begins building an array member of mutable complex elements. More...
 
rti::flat::MutableSequenceBuilder< FlatMutableBarBuilder > build_my_mutable_seq ()
 Begins building a sequence member of mutable complex elements. More...
 
rti::flat::StringBuilder build_my_string ()
 Begins building a string member. More...
 
rti::flat::MutableSequenceBuilder< rti::flat::StringBuilderbuild_my_string_seq ()
 Begins building a sequence member of string elements. More...
 
- Public Member Functions inherited from rti::flat::AbstractBuilder
void discard ()
 Discards a member in process of being built. More...
 
bool is_nested () const
 Returns whether this is a member Builder. More...
 
bool is_valid () const
 Whether this Builder is valid. More...
 
rti::xcdr::length_t capacity () const
 Returns the total capacity in bytes. More...
 

Additional Inherited Members

- Protected Member Functions inherited from rti::flat::AbstractBuilder
virtual ~AbstractBuilder ()
 If this is a member Builder, it calls finish(). More...
 

Detailed Description

Represents the Builder for an arbitrary user-defined mutable type.

This example type represents the Builder type that rtiddsgen would generate for MyFlatMutable and allows creating a sample or a member of that type.

The most common way to create a Builder is rti::flat::build_data(), which obtains a managed sample from a dds::pub::DataWriter as described in Publishing FlatData. It is also possible to create a Builder with an arbitrary buffer using the constructor that receives the buffer and its size.

When a Builder is created, the type is empty–it doesn't contain any members. The Builder provides functions to create each member. There are two kind of functions: add functions and build functions.

Adding fixed-size members

Fixed-size members are "added", and the corresponding function is called add_<member_name>. "Add" functions directly place the member in the buffer, and return an Offset that allows setting its values.

By default, after calling add_<member_name> the member values are uninitialized. This behavior can be changed by creating the writer with rti::core::policy::DataWriterResourceLimits::initialize_writer_loaned_sample; this is however not recommended in general because of the performance impact for large types.

MyFlatMutableBuilder builder = ...;
MyFinalFooOffset member_offset = builder.add_my_final();
member_offset.my_primitive(10);
// ... add/build more members

Building variable-size members

Variable-size members are "built", and the function is called build_<member_name>. "Build" functions return another Builder to build the member.

MyFlatMutableBuilder builder = ...;
auto member_builder = builder.build_my_mutable();
// ... use member_builder
member_builder.finish();
// ... add/build more members

While a member is being built, the parent Builder is a bound state, which prevents any changes to it until the member has been finished by calling member_builder.finish(). In particular, the member Builder must be finished before adding or building any other member, or before finishing builder.

Choosing which members are included

The add/build function for each member can be called one or zero times. That is, all members are optional, even those without the @optional IDL annotation. However @key member must be added or dds::pub::DataWriter::write() will fail.

FlatData samples received by dds::sub::DataReader will not contain the members that were not added/built–the corresponding member getters return a null Offset. A dds::sub::DataReader for an equivalent non-FlatData (plain) definition of this type will assign default values to any non-optional members that were not present in the sample when written.

It is not permitted to add a member more than once, but builders don't enforce this. Trying to build/add a member more than once may cause the Builder to overflow (see Builder Error Management). If it doesn't, it may be possible to write and read the data samples, but the duplicate members will be ignored.

See also
FlatData Builders

Member Typedef Documentation

◆ Offset

The related offset type.

Constructor & Destructor Documentation

◆ MyFlatMutableBuilder() [1/2]

MyFlatMutableBuilder::MyFlatMutableBuilder ( )
inline

Creates an invalid Builder.

Postcondition
!is_valid()
Note
Top-level builders are created with rti::flat::build_data(), and member builders are created with the corresponding build_<member> function.

◆ MyFlatMutableBuilder() [2/2]

MyFlatMutableBuilder::MyFlatMutableBuilder ( unsigned char *  buffer,
int32_t  size,
bool  initialize_members = false 
)
inline

Construct a Builder with an arbitrary buffer.

Note
The recommended way to create a Builder is rti::flat::build_data() as described in Publishing FlatData. This constructor provides an alternative option to use an arbitrary data buffer.
Parameters
bufferThe buffer that will be used to build the data sample
sizeThe size of the buffer
initialize_membersWhether fixed-size elements added to this Builder will be initialized to their default values or will be left uninitialized (more efficient).

If the sample being built overflows the buffer size, the add/build operations will fail. See Builder Error Management.

Member Function Documentation

◆ finish()

Offset MyFlatMutableBuilder::finish ( )

Finishes building a member.

Returns
The Offset to the member (normally it can be ignored)
Precondition
is_nested(). That is, this object must be a member Builder, not a sample Builder.

◆ finish_sample()

MyFlatMutable* MyFlatMutableBuilder::finish_sample ( )

Finishes building a sample.

Precondition
!is_nested(). That is, this object must be a sample Builder, not a member Builder.
Postcondition
!is_valid(). That is, this Builder can no longer be used.
Returns
The sample, ready to be written.

This function completes and returns the sample built with this Builder.

See also
rti::flat::build_data(), the function to create a dds::pub::DataWriter-managed sample Builder.

◆ add_my_primitive()

bool MyFlatMutableBuilder::add_my_primitive ( int32_t  value)

Adds a primitive member.

◆ add_my_optional_primitive()

bool MyFlatMutableBuilder::add_my_optional_primitive ( int32_t  value)

Adds a primitive member.

◆ add_my_primitive_array()

rti::flat::PrimitiveArrayOffset<int32_t, 10> MyFlatMutableBuilder::add_my_primitive_array ( )

Adds a primitive array member.

Returns
The Offset to the array, which can be used to set its values.

◆ build_my_primitive_seq()

rti::flat::PrimitiveSequenceBuilder<int32_t> MyFlatMutableBuilder::build_my_primitive_seq ( )

Begins building a primitive-sequence member.

◆ add_my_final()

MyFlatFinalOffset MyFlatMutableBuilder::add_my_final ( )

Adds a final complex member.

Returns
The Offset to the member, which can be used to set its values.

◆ add_my_final_array()

rti::flat::FinalAlignedArrayOffset<MyFlatFinalOffset, 10> MyFlatMutableBuilder::add_my_final_array ( )

Adds an array member of final complex elements.

Returns
The Offset to the array, which can be used to set its values.

◆ build_my_final_seq()

rti::flat::FinalSequenceBuilder<MyFlatFinalOffset> MyFlatMutableBuilder::build_my_final_seq ( )

Begins building a sequence member of final complex elements.

◆ build_my_mutable()

FlatMutableBarBuilder MyFlatMutableBuilder::build_my_mutable ( )

Begins building a mutable complex member.

FlatMutableBar represents another arbitrary mutable FlatData type.

◆ build_my_mutable_array()

rti::flat::MutableArrayBuilder<FlatMutableBarBuilder, 10> MyFlatMutableBuilder::build_my_mutable_array ( )

Begins building an array member of mutable complex elements.

◆ build_my_mutable_seq()

rti::flat::MutableSequenceBuilder<FlatMutableBarBuilder > MyFlatMutableBuilder::build_my_mutable_seq ( )

Begins building a sequence member of mutable complex elements.

◆ build_my_string()

rti::flat::StringBuilder MyFlatMutableBuilder::build_my_string ( )

Begins building a string member.

◆ build_my_string_seq()

rti::flat::MutableSequenceBuilder<rti::flat::StringBuilder > MyFlatMutableBuilder::build_my_string_seq ( )

Begins building a sequence member of string elements.