FlatBuffers
An open source project by FPL.
 All Classes Namespaces Files Functions Variables Properties Groups Pages
flatbuffers::FlatBufferBuilder Class Reference

Helper class to hold data needed in creation of a FlatBuffer. More...

#include <flatbuffers.h>

Detailed Description

Helper class to hold data needed in creation of a FlatBuffer.

To serialize data, you typically call one of the Create*() functions in the generated code, which in turn call a sequence of StartTable/ PushElement/AddElement/EndTable, or the builtin CreateString/ CreateVector functions. Do this is depth-first order to build up a tree to the root. Finish() wraps up the buffer ready for transport.

Public Member Functions

void Clear ()
 Reset all the state in this FlatBufferBuilder so it can be reused to construct another buffer. More...
 
Offset< String > CreateSharedString (const char *str, size_t len)
 Store a string in the buffer, which can contain any binary data. More...
 
Offset< String > CreateSharedString (const char *str)
 Store a string in the buffer, which null-terminated. More...
 
Offset< String > CreateSharedString (const std::string &str)
 Store a string in the buffer, which can contain any binary data. More...
 
Offset< String > CreateSharedString (const String *str)
 Store a string in the buffer, which can contain any binary data. More...
 
Offset< String > CreateString (const char *str, size_t len)
 Store a string in the buffer, which can contain any binary data. More...
 
Offset< String > CreateString (const char *str)
 Store a string in the buffer, which is null-terminated. More...
 
Offset< String > CreateString (const std::string &str)
 Store a string in the buffer, which can contain any binary data. More...
 
Offset< String > CreateString (const String *str)
 Store a string in the buffer, which can contain any binary data. More...
 
template<typename T >
Offset< String > CreateString (const T &str)
 Store a string in the buffer, which can contain any binary data. More...
 
template<typename T >
Offset< const T * > CreateStruct (const T &structobj)
 Write a struct by itself, typically to be part of a union.
 
uoffset_t CreateUninitializedVector (size_t len, size_t elemsize, uint8_t **buf)
 Specialized version of CreateVector for non-copying use cases. More...
 
template<typename T >
Offset< Vector< T > > CreateUninitializedVector (size_t len, T **buf)
 Specialized version of CreateVector for non-copying use cases. More...
 
template<typename T >
Offset< Vector< T > > CreateVector (const T *v, size_t len)
 Serialize an array into a FlatBuffer vector. More...
 
template<typename T >
Offset< Vector< T > > CreateVector (const std::vector< T > &v)
 Serialize a std::vector into a FlatBuffer vector. More...
 
Offset< Vector< uint8_t > > CreateVector (const std::vector< bool > &v)
 
template<typename T >
Offset< Vector< T > > CreateVector (size_t vector_size, const std::function< T(size_t i)> &f)
 Serialize values returned by a function into a FlatBuffer vector. More...
 
template<typename T , typename S >
Offset< Vector< const T * > > CreateVectorOfNativeStructs (const S *v, size_t len)
 Serialize an array of native structs into a FlatBuffer vector. More...
 
template<typename T , typename S >
Offset< Vector< const T * > > CreateVectorOfNativeStructs (const std::vector< S > &v)
 Serialize a std::vector of native structs into a FlatBuffer vector. More...
 
template<typename T , typename S >
Offset< Vector< const T * > > CreateVectorOfSortedNativeStructs (std::vector< S > *v)
 Serialize a std::vector of native structs into a FlatBuffer vector in sorted order. More...
 
template<typename T , typename S >
Offset< Vector< const T * > > CreateVectorOfSortedNativeStructs (S *v, size_t len)
 Serialize an array of native structs into a FlatBuffer vector in sorted order. More...
 
template<typename T >
Offset< Vector< const T * > > CreateVectorOfSortedStructs (std::vector< T > *v)
 Serialize a std::vector of structs into a FlatBuffer vector in sorted order. More...
 
template<typename T >
Offset< Vector< const T * > > CreateVectorOfSortedStructs (T *v, size_t len)
 Serialize an array of structs into a FlatBuffer vector in sorted order. More...
 
template<typename T >
Offset< Vector< Offset< T > > > CreateVectorOfSortedTables (Offset< T > *v, size_t len)
 Serialize an array of table offsets as a vector in the buffer in sorted order. More...
 
template<typename T >
Offset< Vector< Offset< T > > > CreateVectorOfSortedTables (std::vector< Offset< T >> *v)
 Serialize an array of table offsets as a vector in the buffer in sorted order. More...
 
Offset< Vector< Offset< String > > > CreateVectorOfStrings (const std::vector< std::string > &v)
 Serialize a std::vector<std::string> into a FlatBuffer vector. More...
 
template<typename T >
Offset< Vector< const T * > > CreateVectorOfStructs (const T *v, size_t len)
 Serialize an array of structs into a FlatBuffer vector. More...
 
template<typename T >
Offset< Vector< const T * > > CreateVectorOfStructs (size_t vector_size, const std::function< void(size_t i, T *)> &filler)
 Serialize an array of structs into a FlatBuffer vector. More...
 
template<typename T >
Offset< Vector< const T * > > CreateVectorOfStructs (const std::vector< T > &v)
 Serialize a std::vector of structs into a FlatBuffer vector. More...
 
void DedupVtables (bool dedup)
 By default vtables are deduped in order to save space. More...
 
template<typename T >
void Finish (Offset< T > root, const char *file_identifier=nullptr)
 Finish serializing a buffer by writing the root offset. More...
 
template<typename T >
void FinishSizePrefixed (Offset< T > root, const char *file_identifier=nullptr)
 Finish a buffer with a 32 bit size field pre-fixed (size of the buffer following the size field). More...
 
 FlatBufferBuilder (uoffset_t initial_size=1024, const simple_allocator *allocator=nullptr)
 Default constructor for FlatBufferBuilder. More...
 
void ForceDefaults (bool fd)
 In order to save space, fields that are set to their default value don't get serialized into the buffer. More...
 
size_t GetBufferMinAlignment ()
 get the minimum alignment this buffer needs to be accessed properly. More...
 
uint8_t * GetBufferPointer () const
 Get the serialized buffer (after you call Finish()). More...
 
uint8_t * GetCurrentBufferPointer () const
 Get a pointer to an unfinished buffer. More...
 
uoffset_t GetSize () const
 The current size of the serialized buffer, counting from the end. More...
 
unique_ptr_t ReleaseBufferPointer ()
 Get the released pointer to the serialized buffer. More...
 

Static Public Attributes

static const size_t kFileIdentifierLength = 4
 The length of a FlatBuffer file header.
 

Constructor & Destructor Documentation

flatbuffers::FlatBufferBuilder::FlatBufferBuilder ( uoffset_t  initial_size = 1024,
const simple_allocator *  allocator = nullptr 
)
inlineexplicit

Default constructor for FlatBufferBuilder.

Parameters
[in]initial_sizeThe initial size of the buffer, in bytes. Defaults to1024.
[in]allocatorA pointer to the simple_allocator that should be used. Defaults to nullptr, which means the default_allocator will be be used.

Member Function Documentation

void flatbuffers::FlatBufferBuilder::Clear ( )
inline

Reset all the state in this FlatBufferBuilder so it can be reused to construct another buffer.

Offset<String> flatbuffers::FlatBufferBuilder::CreateSharedString ( const char *  str,
size_t  len 
)
inline

Store a string in the buffer, which can contain any binary data.

If a string with this exact contents has already been serialized before, instead simply returns the offset of the existing string.

Parameters
[in]strA const char pointer to the data to be stored as a string.
[in]lenThe number of bytes that should be stored from str.
Returns
Returns the offset in the buffer where the string starts.
Offset<String> flatbuffers::FlatBufferBuilder::CreateSharedString ( const char *  str)
inline

Store a string in the buffer, which null-terminated.

If a string with this exact contents has already been serialized before, instead simply returns the offset of the existing string.

Parameters
[in]strA const char pointer to a C-string to add to the buffer.
Returns
Returns the offset in the buffer where the string starts.
Offset<String> flatbuffers::FlatBufferBuilder::CreateSharedString ( const std::string &  str)
inline

Store a string in the buffer, which can contain any binary data.

If a string with this exact contents has already been serialized before, instead simply returns the offset of the existing string.

Parameters
[in]strA const reference to a std::string to store in the buffer.
Returns
Returns the offset in the buffer where the string starts.
Offset<String> flatbuffers::FlatBufferBuilder::CreateSharedString ( const String *  str)
inline

Store a string in the buffer, which can contain any binary data.

If a string with this exact contents has already been serialized before, instead simply returns the offset of the existing string.

Parameters
[in]strA const pointer to a String struct to add to the buffer.
Returns
Returns the offset in the buffer where the string starts
Offset<String> flatbuffers::FlatBufferBuilder::CreateString ( const char *  str,
size_t  len 
)
inline

Store a string in the buffer, which can contain any binary data.

Parameters
[in]strA const char pointer to the data to be stored as a string.
[in]lenThe number of bytes that should be stored from str.
Returns
Returns the offset in the buffer where the string starts.
Offset<String> flatbuffers::FlatBufferBuilder::CreateString ( const char *  str)
inline

Store a string in the buffer, which is null-terminated.

Parameters
[in]strA const char pointer to a C-string to add to the buffer.
Returns
Returns the offset in the buffer where the string starts.
Offset<String> flatbuffers::FlatBufferBuilder::CreateString ( const std::string &  str)
inline

Store a string in the buffer, which can contain any binary data.

Parameters
[in]strA const reference to a std::string to store in the buffer.
Returns
Returns the offset in the buffer where the string starts.
Offset<String> flatbuffers::FlatBufferBuilder::CreateString ( const String *  str)
inline

Store a string in the buffer, which can contain any binary data.

Parameters
[in]strA const pointer to a String struct to add to the buffer.
Returns
Returns the offset in the buffer where the string starts
template<typename T >
Offset<String> flatbuffers::FlatBufferBuilder::CreateString ( const T &  str)
inline

Store a string in the buffer, which can contain any binary data.

Parameters
[in]strA const reference to a std::string like type with support of T::c_str() and T::length() to store in the buffer.
Returns
Returns the offset in the buffer where the string starts.
uoffset_t flatbuffers::FlatBufferBuilder::CreateUninitializedVector ( size_t  len,
size_t  elemsize,
uint8_t **  buf 
)
inline

Specialized version of CreateVector for non-copying use cases.

Write the data any time later to the returned buffer pointer buf.

Parameters
[in]lenThe number of elements to store in the vector.
[in]elemsizeThe size of each element in the vector.
[out]bufA pointer to a uint8_t pointer that can be written to at a later time to serialize the data into a vector in the buffer.
template<typename T >
Offset<Vector<T> > flatbuffers::FlatBufferBuilder::CreateUninitializedVector ( size_t  len,
T **  buf 
)
inline

Specialized version of CreateVector for non-copying use cases.

Write the data any time later to the returned buffer pointer buf.

Template Parameters
TThe data type of the data that will be stored in the buffer as a vector.
Parameters
[in]lenThe number of elements to store in the vector.
[out]bufA pointer to a pointer of type T that can be written to at a later time to serialize the data into a vector in the buffer.
template<typename T >
Offset<Vector<T> > flatbuffers::FlatBufferBuilder::CreateVector ( const T *  v,
size_t  len 
)
inline

Serialize an array into a FlatBuffer vector.

Template Parameters
TThe data type of the array elements.
Parameters
[in]vA pointer to the array of type T to serialize into the buffer as a vector.
[in]lenThe number of elements to serialize.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<T> > flatbuffers::FlatBufferBuilder::CreateVector ( const std::vector< T > &  v)
inline

Serialize a std::vector into a FlatBuffer vector.

Template Parameters
TThe data type of the std::vector elements.
Parameters
vA const reference to the std::vector to serialize into the buffer as a vector.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<T> > flatbuffers::FlatBufferBuilder::CreateVector ( size_t  vector_size,
const std::function< T(size_t i)> &  f 
)
inline

Serialize values returned by a function into a FlatBuffer vector.

This is a convenience function that takes care of iteration for you.

Template Parameters
TThe data type of the std::vector elements.
Parameters
fA function that takes the current iteration 0..vector_size-1 and returns any type that you can construct a FlatBuffers vector out of.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T , typename S >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfNativeStructs ( const S *  v,
size_t  len 
)
inline

Serialize an array of native structs into a FlatBuffer vector.

Template Parameters
TThe data type of the struct array elements.
SThe data type of the native struct array elements.
Parameters
[in]vA pointer to the array of type S to serialize into the buffer as a vector.
[in]lenThe number of elements to serialize.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T , typename S >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfNativeStructs ( const std::vector< S > &  v)
inline

Serialize a std::vector of native structs into a FlatBuffer vector.

Template Parameters
TThe data type of the std::vector struct elements.
SThe data type of the std::vector native struct elements.
Parameters
[in]v A const reference to the std::vector of structs to serialize into the buffer as a vector.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T , typename S >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfSortedNativeStructs ( std::vector< S > *  v)
inline

Serialize a std::vector of native structs into a FlatBuffer vector in sorted order.

Template Parameters
TThe data type of the std::vector struct elements.
SThe data type of the std::vector native struct elements.
Parameters
[in]v A const reference to the std::vector of structs to serialize into the buffer as a vector.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T , typename S >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfSortedNativeStructs ( S *  v,
size_t  len 
)
inline

Serialize an array of native structs into a FlatBuffer vector in sorted order.

Template Parameters
TThe data type of the struct array elements.
SThe data type of the native struct array elements.
Parameters
[in]vA pointer to the array of type S to serialize into the buffer as a vector.
[in]lenThe number of elements to serialize.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfSortedStructs ( std::vector< T > *  v)
inline

Serialize a std::vector of structs into a FlatBuffer vector in sorted order.

Template Parameters
TThe data type of the std::vector struct elements.
Parameters
[in]v A const reference to the std::vector of structs to serialize into the buffer as a vector.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfSortedStructs ( T *  v,
size_t  len 
)
inline

Serialize an array of structs into a FlatBuffer vector in sorted order.

Template Parameters
TThe data type of the struct array elements.
Parameters
[in]vA pointer to the array of type T to serialize into the buffer as a vector.
[in]lenThe number of elements to serialize.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<Offset<T> > > flatbuffers::FlatBufferBuilder::CreateVectorOfSortedTables ( Offset< T > *  v,
size_t  len 
)
inline

Serialize an array of table offsets as a vector in the buffer in sorted order.

Template Parameters
TThe data type that the offset refers to.
Parameters
[in]vAn array of type Offset<T> that contains the table offsets to store in the buffer in sorted order.
[in]lenThe number of elements to store in the vector.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<Offset<T> > > flatbuffers::FlatBufferBuilder::CreateVectorOfSortedTables ( std::vector< Offset< T >> *  v)
inline

Serialize an array of table offsets as a vector in the buffer in sorted order.

Template Parameters
TThe data type that the offset refers to.
Parameters
[in]vAn array of type Offset<T> that contains the table offsets to store in the buffer in sorted order.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
Offset<Vector<Offset<String> > > flatbuffers::FlatBufferBuilder::CreateVectorOfStrings ( const std::vector< std::string > &  v)
inline

Serialize a std::vector<std::string> into a FlatBuffer vector.

This is a convenience function for a common case.

Parameters
vA const reference to the std::vector to serialize into the buffer as a vector.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfStructs ( const T *  v,
size_t  len 
)
inline

Serialize an array of structs into a FlatBuffer vector.

Template Parameters
TThe data type of the struct array elements.
Parameters
[in]vA pointer to the array of type T to serialize into the buffer as a vector.
[in]lenThe number of elements to serialize.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
template<typename T >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfStructs ( size_t  vector_size,
const std::function< void(size_t i, T *)> &  filler 
)
inline

Serialize an array of structs into a FlatBuffer vector.

Template Parameters
TThe data type of the struct array elements.
Parameters
[in]fA function that takes the current iteration 0..vector_size-1 and a pointer to the struct that must be filled.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored. This is mostly useful when flatbuffers are generated with mutation accessors.
template<typename T >
Offset<Vector<const T *> > flatbuffers::FlatBufferBuilder::CreateVectorOfStructs ( const std::vector< T > &  v)
inline

Serialize a std::vector of structs into a FlatBuffer vector.

Template Parameters
TThe data type of the std::vector struct elements.
Parameters
[in]v A const reference to the std::vector of structs to serialize into the buffer as a vector.
Returns
Returns a typed Offset into the serialized data indicating where the vector is stored.
void flatbuffers::FlatBufferBuilder::DedupVtables ( bool  dedup)
inline

By default vtables are deduped in order to save space.

Parameters
[in]booldedup When set to true, dedup vtables.
template<typename T >
void flatbuffers::FlatBufferBuilder::Finish ( Offset< T >  root,
const char *  file_identifier = nullptr 
)
inline

Finish serializing a buffer by writing the root offset.

Parameters
[in]file_identifierIf a file_identifier is given, the buffer will be prefixed with a standard FlatBuffers file header.
template<typename T >
void flatbuffers::FlatBufferBuilder::FinishSizePrefixed ( Offset< T >  root,
const char *  file_identifier = nullptr 
)
inline

Finish a buffer with a 32 bit size field pre-fixed (size of the buffer following the size field).

These buffers are NOT compatible with standard buffers created by Finish, i.e. you can't call GetRoot on them, you have to use GetSizePrefixedRoot instead. All >32 bit quantities in this buffer will be aligned when the whole size pre-fixed buffer is aligned. These kinds of buffers are useful for creating a stream of FlatBuffers.

void flatbuffers::FlatBufferBuilder::ForceDefaults ( bool  fd)
inline

In order to save space, fields that are set to their default value don't get serialized into the buffer.

Parameters
[in]boolfd When set to true, always serializes default values.
size_t flatbuffers::FlatBufferBuilder::GetBufferMinAlignment ( )
inline

get the minimum alignment this buffer needs to be accessed properly.

This is only known once all elements have been written (after you call Finish()). You can use this information if you need to embed a FlatBuffer in some other buffer, such that you can later read it without first having to copy it into its own buffer.

uint8_t* flatbuffers::FlatBufferBuilder::GetBufferPointer ( ) const
inline

Get the serialized buffer (after you call Finish()).

Returns
Returns an uint8_t pointer to the FlatBuffer data inside the buffer.
uint8_t* flatbuffers::FlatBufferBuilder::GetCurrentBufferPointer ( ) const
inline

Get a pointer to an unfinished buffer.

Returns
Returns a uint8_t pointer to the unfinished buffer.
uoffset_t flatbuffers::FlatBufferBuilder::GetSize ( ) const
inline

The current size of the serialized buffer, counting from the end.

Returns
Returns an uoffset_t with the current size of the buffer.
unique_ptr_t flatbuffers::FlatBufferBuilder::ReleaseBufferPointer ( )
inline

Get the released pointer to the serialized buffer.

Warning
Do NOT attempt to use this FlatBufferBuilder afterwards!
Returns
The unique_ptr returned has a special allocator that knows how to deallocate this pointer (since it points to the middle of an allocation). Thus, do not mix this pointer with other unique_ptr's, or call release()/reset() on it.

The documentation for this class was generated from the following file: