MyFlatMutableBuilder Class Reference

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

#include <Builder.hpp>

Inheritance diagram for MyFlatMutableBuilder:

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...
MyFlatMutable *	finish_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< MyFlatFinalOffset >	build_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::StringBuilder >	build_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

typedef MyFlatMutableOffset MyFlatMutableBuilder::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

buffer	The buffer that will be used to build the data sample
size	The size of the buffer
initialize_members	Whether 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.