RTI Connext Traditional C++ API Version 7.3.0

A Builder allows creating and initializing variable-size data. More...

Classes

class  rti::flat::AggregationBuilder
 Base class of struct and union builders. More...
 
class  rti::flat::UnionBuilder< Discriminator >
 Base class of builders for user-defined mutable unions. More...
 
class  MyFlatMutableBuilder
 Represents the Builder for an arbitrary user-defined mutable type. More...
 
class  MyFlatUnionBuilder
 Represents the Builder for an arbitrary user-defined mutable IDL union. More...
 
class  rti::flat::AbstractBuilder
 Base class of all Builders. More...
 
class  rti::flat::AbstractListBuilder< DHeaderGen >
 Base class of all array and sequence builders. More...
 
class  rti::flat::MutableArrayBuilder< ElementBuilder, N >
 Builds an array member of variable-size elements. More...
 
class  rti::flat::AbstractSequenceBuilder< DHeaderGen >
 Base class of Builders for sequence members. More...
 
class  rti::flat::MutableSequenceBuilder< ElementBuilder >
 Builds a sequence member of variable-size elements. More...
 
class  rti::flat::FinalSequenceBuilder< ElementOffset >
 Builds a sequence member of fixed-size elements. More...
 
class  rti::flat::PrimitiveSequenceBuilder< T >
 Builds a sequence of primitive members. More...
 
class  rti::flat::StringBuilder
 Builds a string. More...
 

Functions

template<typename TopicType >
rti::flat::flat_type_traits< TopicType >::builder rti::flat::build_data (typename TopicType::DataWriter *writer)
 Begins building a new sample. More...
 
template<typename BuilderType >
void rti::flat::discard_builder (typename rti::flat::flat_type_traits< BuilderType >::flat_type::DataWriter *writer, BuilderType &builder)
 Discards a sample builder. More...
 

Detailed Description

A Builder allows creating and initializing variable-size data.

Builders allow creating variable-size FlatData samples, as described in Publishing FlatData.

There are the following Builder types:

Category Builder type
User types For example:
Arrays
Sequences
Primitive types

Builder for user types, such as MyFlatMutableBuilder, can behave as sample builders, when they build a sample, or member builders when they build a member for another Builder (such as the Builder returned by MyFlatMutableBuilder::build_my_mutable()). All the other Builder types (sequences, arrays) are always member builders (such as the Builder returned by MyFlatMutableBuilder::build_my_final_seq()).

Builders are move-only types. They cannot be copied, only moved. When you assign a Builder as the return value of a function, this happens automatically.

// the return value of 'build_data' is moved into 'builder'
Represents the Builder for an arbitrary user-defined mutable type.
Definition: Builder.hpp:206
rti::flat::flat_type_traits< TopicType >::builder build_data(typename TopicType::DataWriter *writer)
Begins building a new sample.
Definition: ndds_flat_data_cpp.ifcxx:63

To explicitly move a Builder variable in the Traditional C++ API, call its move() member function

Builder Error Management

The Traditional C++ API reports Builder errors by setting a flag that can be checked with the member function check_failure(). After each Builder operation, check_failure() must be called to check (and clear) the error flag.

In addition, in case of error, operations that return another Builder, such as MyFlatMutableBuilder::build_my_mutable(), return an invalid Builder (is_valid() is false). Operations that return an Offset, such as MyFlatMutableBuilder::add_my_final() return a "null" Offset when they fail (see Offset Error Management).

See also
MyFlatMutableBuilder for more information specific to builders for user types.

Function Documentation

◆ build_data()

template<typename TopicType >
rti::flat::flat_type_traits< TopicType >::builder rti::flat::build_data ( typename TopicType::DataWriter *  writer)

Begins building a new sample.

Template Parameters
TopicTypeA FlatData mutable type that corresponds to the type of the DataWriter argument.
Parameters
writerThe writer that will be used to write this sample.
Returns
The Builder to build the sample. For example if TopicType is MyFlatMutable, this function returns a MyFlatMutableBuilder. In case of error, this function returns an invalid Builder

Once you have completed the sample, call finish_sample() to obtain a MyFlatMutable sample that can be written with writer.

If the building of this sample needs to be aborted before calling finish_sample(), use rti::flat::discard_builder(). If, after obtaining a sample with finish_sample(), this sample is not written, then discard it with FooDataWriter::discard_loan().

See also
FooDataWriter::get_loan, the function that build_data() uses to obtain the memory required to build the sample.
Publishing FlatData

References DDS_BOOLEAN_TRUE, and DDS_RETCODE_OK.

◆ discard_builder()

template<typename BuilderType >
void rti::flat::discard_builder ( typename rti::flat::flat_type_traits< BuilderType >::flat_type::DataWriter *  writer,
BuilderType &  builder 
)

Discards a sample builder.

Template Parameters
TopicTypeAn IDL-defined FlatData type that corresponds to the type of the DataWriter argument.

This function invalidates and discards a builder before it is finished() and before the sample it would have created was written.

Parameters
writerThe writer that was used to create the builder
builderThe builder, created with rti::flat::build_data(writer);