Struct flatbuffers::FlatBufferBuilder

pub struct FlatBufferBuilder<'fbb, A: Allocator = DefaultAllocator> { /* private fields */ }

FlatBufferBuilder builds a FlatBuffer through manipulating its internal state. It has an owned Vec<u8> that grows as needed (up to the hardcoded limit of 2GiB, which is set by the FlatBuffers format).

Implementations

impl<'fbb> FlatBufferBuilder<'fbb, DefaultAllocator>

pub fn new() -> Self

Create a FlatBufferBuilder that is ready for writing.

pub fn new_with_capacity(size: usize) -> Self

👎Deprecated since 0.8.5: replaced with with_capacity

pub fn with_capacity(size: usize) -> Self

Create a FlatBufferBuilder that is ready for writing, with a ready-to-use capacity of the provided size.

The maximum valid value is FLATBUFFERS_MAX_BUFFER_SIZE.

pub fn from_vec(buffer: Vec<u8>) -> Self

Create a FlatBufferBuilder that is ready for writing, reusing an existing vector.

pub fn collapse(self) -> (Vec<u8>, usize)

Destroy the FlatBufferBuilder, returning its internal byte vector and the index into it that represents the start of valid data.

impl<'fbb, A: Allocator> FlatBufferBuilder<'fbb, A>

pub fn new_in(allocator: A) -> Self

Create a FlatBufferBuilder that is ready for writing with a custom Allocator.

pub fn collapse_in(self) -> (A, usize)

Destroy the FlatBufferBuilder, returning its Allocator and the index into it that represents the start of valid data.

pub fn reset(&mut self)

Reset the FlatBufferBuilder internal state. Use this method after a call to a finish function in order to re-use a FlatBufferBuilder.

This function is the only way to reset the finished state and start again.

If you are using a FlatBufferBuilder repeatedly, make sure to use this function, because it re-uses the FlatBufferBuilder’s existing heap-allocated Vec<u8> internal buffer. This offers significant speed improvements as compared to creating a new FlatBufferBuilder for every new object.

pub fn push<P: Push>(&mut self, x: P) -> WIPOffset<P::Output>

Push a Push’able value onto the front of the in-progress data.

This function uses traits to provide a unified API for writing scalars, tables, vectors, and WIPOffsets.

pub fn push_slot<X: Push + PartialEq>( &mut self, slotoff: VOffsetT, x: X, default: X )

Push a Push’able value onto the front of the in-progress data, and store a reference to it in the in-progress vtable. If the value matches the default, then this is a no-op.

pub fn push_slot_always<X: Push>(&mut self, slotoff: VOffsetT, x: X)

Push a Push’able value onto the front of the in-progress data, and store a reference to it in the in-progress vtable.

pub fn num_written_vtables(&self) -> usize

Retrieve the number of vtables that have been serialized into the FlatBuffer. This is primarily used to check vtable deduplication.

pub fn start_table(&mut self) -> WIPOffset<TableUnfinishedWIPOffset>

Start a Table write.

Asserts that the builder is not in a nested state.

Users probably want to use push_slot to add values after calling this.

pub fn end_table( &mut self, off: WIPOffset<TableUnfinishedWIPOffset> ) -> WIPOffset<TableFinishedWIPOffset>

End a Table write.

Asserts that the builder is in a nested state.

pub fn start_vector<T: Push>(&mut self, num_items: usize)

Start a Vector write.

Asserts that the builder is not in a nested state.

Most users will prefer to call create_vector. Speed optimizing users who choose to create vectors manually using this function will want to use push to add values.

pub fn end_vector<T: Push>( &mut self, num_elems: usize ) -> WIPOffset<Vector<'fbb, T>>

End a Vector write.

Note that the num_elems parameter is the number of written items, not the byte count.

Asserts that the builder is in a nested state.

pub fn create_shared_string<'a: 'b, 'b>( &'a mut self, s: &'b str ) -> WIPOffset<&'fbb str>

pub fn create_string<'a: 'b, 'b>( &'a mut self, s: &'b str ) -> WIPOffset<&'fbb str>

Create a utf8 string.

The wire format represents this as a zero-terminated byte vector.

pub fn create_byte_string(&mut self, data: &[u8]) -> WIPOffset<&'fbb [u8]>

Create a zero-terminated byte vector.

pub fn create_vector<'a: 'b, 'b, T: Push + 'b>( &'a mut self, items: &'b [T] ) -> WIPOffset<Vector<'fbb, T::Output>>

Create a vector of Push-able objects.

Speed-sensitive users may wish to reduce memory usage by creating the vector manually: use start_vector, push, and end_vector.

pub fn create_vector_from_iter<T: Push>( &mut self, items: impl ExactSizeIterator<Item = T> + DoubleEndedIterator ) -> WIPOffset<Vector<'fbb, T::Output>>

Create a vector of Push-able objects.

Speed-sensitive users may wish to reduce memory usage by creating the vector manually: use start_vector, push, and end_vector.

pub fn force_defaults(&mut self, force_defaults: bool)

Set whether default values are stored.

In order to save space, fields that are set to their default value aren’t stored in the buffer. Setting force_defaults to true disables this optimization.

By default, force_defaults is false.

pub fn unfinished_data(&self) -> &[u8]

Get the byte slice for the data that has been written, regardless of whether it has been finished.

pub fn finished_data(&self) -> &[u8]

Get the byte slice for the data that has been written after a call to one of the finish functions.

Panics

Panics if the buffer is not finished.

pub fn mut_finished_buffer(&mut self) -> (&mut [u8], usize)

Returns a mutable view of a finished buffer and location of where the flatbuffer starts. Note that modifying the flatbuffer data may corrupt it.

Panics

Panics if the flatbuffer is not finished.

pub fn required( &self, tab_revloc: WIPOffset<TableFinishedWIPOffset>, slot_byte_loc: VOffsetT, assert_msg_name: &'static str )

Assert that a field is present in the just-finished Table.

This is somewhat low-level and is mostly used by the generated code.

pub fn finish_size_prefixed<T>( &mut self, root: WIPOffset<T>, file_identifier: Option<&str> )

Finalize the FlatBuffer by: aligning it, pushing an optional file identifier on to it, pushing a size prefix on to it, and marking the internal state of the FlatBufferBuilder as finished. Afterwards, users can call finished_data to get the resulting data.

pub fn finish<T>(&mut self, root: WIPOffset<T>, file_identifier: Option<&str>)

Finalize the FlatBuffer by: aligning it, pushing an optional file identifier on to it, and marking the internal state of the FlatBufferBuilder as finished. Afterwards, users can call finished_data to get the resulting data.

pub fn finish_minimal<T>(&mut self, root: WIPOffset<T>)

Finalize the FlatBuffer by: aligning it and marking the internal state of the FlatBufferBuilder as finished. Afterwards, users can call finished_data to get the resulting data.

Trait Implementations

impl<'fbb, A: Clone + Allocator> Clone for FlatBufferBuilder<'fbb, A>

fn clone(&self) -> FlatBufferBuilder<'fbb, A>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'fbb, A: Debug + Allocator> Debug for FlatBufferBuilder<'fbb, A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'fbb> Default for FlatBufferBuilder<'fbb>

fn default() -> Self

Returns the “default value” for a type.

impl<'fbb, A: PartialEq + Allocator> PartialEq for FlatBufferBuilder<'fbb, A>

fn eq(&self, other: &FlatBufferBuilder<'fbb, A>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'fbb, A: Eq + Allocator> Eq for FlatBufferBuilder<'fbb, A>

impl<'fbb, A: Allocator> StructuralPartialEq for FlatBufferBuilder<'fbb, A>