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 (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: MyFlatMutableBuilder, a mutable struct MyFlatUnionBuilder, a union Final structs are fixed-size and do not have a Builder (see for example MyFlatMutableBuilder::add_my_final()).
Arrays	rti::flat::MutableArrayBuilder Arrays of final elements are fixed-size and do not have a Builder (see for example MyFlatMutableBuilder::add_my_final_array()).
Sequences	rti::flat::MutableSequenceBuilder for sequences of mutable elements rti::flat::FinalSequenceBuilder for sequences of final elements rti::flat::PrimitiveSequenceBuilder for sequences of primitive elements rti::flat::StringBuilder
Primitive types	Primitive members are added using one of the member functions of the Builder of the type that contains them. See for example MyFlatMutableBuilder::add_my_primitive()<

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'

MyFlatMutableBuilder builder = rti::flat::build_data(writer);

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

TopicType A FlatData mutable type that corresponds to the type of the DataWriter argument.

Parameters

writer The 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

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