FlatData Builders

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.

Parameters

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