Struct fbs::FlatBufferBuilder

pub struct FlatBufferBuilder<'fbb> { /* fields omitted */ }

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>

pub fn new() -> Self

Create a FlatBufferBuilder that is ready for writing.

pub fn new_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 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 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.

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_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_direct<'a: 'b, 'b, T: SafeSliceAccess + Push + Sized + 'b>(
    &'a mut self,
    items: &'b [T]
) -> WIPOffset<Vector<'fbb, T>>

Create a vector by memcpy'ing. This is much faster than calling create_vector, but the underlying type must be represented as little-endian on the host machine. This property is encoded in the type system through the SafeSliceAccess trait. The following types are always safe, on any platform: bool, u8, i8, and any FlatBuffers-generated struct.

pub fn create_vector_of_strings<'a, 'b>(
    &'a mut self,
    xs: &'b [&'b str]
) -> WIPOffset<Vector<'fbb, ForwardsUOffset<&'fbb str>>>

Create a vector of strings.

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<'a: 'b, 'b, T: Push + Copy + '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 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.

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> Clone for FlatBufferBuilder<'fbb>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'fbb> Debug for FlatBufferBuilder<'fbb>

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> Eq for FlatBufferBuilder<'fbb>

impl<'fbb> PartialEq<FlatBufferBuilder<'fbb>> for FlatBufferBuilder<'fbb>

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

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

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

This method tests for !=.

impl<'fbb> StructuralEq for FlatBufferBuilder<'fbb>

impl<'fbb> StructuralPartialEq for FlatBufferBuilder<'fbb>