RTI Connext Modern C++ API  Version 6.1.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
 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
 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 (dds::pub::DataWriter< TopicType > &writer)
 Begins building a new sample. More...
 
template<typename TopicType >
void rti::flat::discard_builder (dds::pub::DataWriter< TopicType > &writer, typename rti::flat::flat_type_traits< TopicType >::builder &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'

To explicitly move a Builder variable use std::move() in C++11 platforms or call the move() member function in pre-C++11 platforms.

Builder Error Management

In the Modern C++ API errors are notified with exceptions. Builder operations may throw the following exceptions

See also 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 ( dds::pub::DataWriter< TopicType > &  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.

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 dds::pub::DataWriter::discard_loan().

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

References dds::pub::DataWriter< T >::get_loan().

◆ discard_builder()

template<typename TopicType >
void rti::flat::discard_builder ( dds::pub::DataWriter< TopicType > &  writer,
typename rti::flat::flat_type_traits< TopicType >::builder &  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);

References dds::pub::DataWriter< T >::discard_loan().