Struct Builder 

pub struct Builder<'a> { /* private fields */ }

Builds a FlatBuffers buffer from the end of a caller’s slice downwards.

A FlatBuffers buffer is built back to front: a child is written before the parent that names it, and the root offset is written last and sits at the start of the finished buffer. The builder therefore fills the slice from its end, and Builder::finish returns the finished buffer as a subslice of the slice ending at its end — which is why Encoded.bytes is a subslice rather than a prefix.

Nothing here allocates. The caller’s slice is the only storage, and a write that does not fit returns EncodeError::Capacity with the bytes the encoding needed so far.

Implementations

impl<'a> Builder<'a>

pub fn new(out: &'a mut [u8]) -> Self

A builder over out.

pub fn used(&self) -> usize

The bytes written so far, including alignment padding.

pub fn reserve( &mut self, size: usize, align: usize, ) -> Result<(Pos, &mut [u8]), EncodeError>

Reserves size bytes for an object aligned to align, and returns its position and the bytes to fill, in address order.

The reserved bytes and any padding are zeroed, so a buffer the caller handed over dirty does not leak its old contents into the encoding and two encodes of one value produce the same bytes.

impl<'a> Builder<'a>

pub fn push_u8(&mut self, value: u8) -> Result<Pos, EncodeError>

Writes a little-endian u8, aligned to its own size.

pub fn push_i8(&mut self, value: i8) -> Result<Pos, EncodeError>

Writes a little-endian i8, aligned to its own size.

pub fn push_u16(&mut self, value: u16) -> Result<Pos, EncodeError>

Writes a little-endian u16, aligned to its own size.

pub fn push_i16(&mut self, value: i16) -> Result<Pos, EncodeError>

Writes a little-endian i16, aligned to its own size.

pub fn push_u32(&mut self, value: u32) -> Result<Pos, EncodeError>

Writes a little-endian u32, aligned to its own size.

pub fn push_i32(&mut self, value: i32) -> Result<Pos, EncodeError>

Writes a little-endian i32, aligned to its own size.

pub fn push_u64(&mut self, value: u64) -> Result<Pos, EncodeError>

Writes a little-endian u64, aligned to its own size.

pub fn push_i64(&mut self, value: i64) -> Result<Pos, EncodeError>

Writes a little-endian i64, aligned to its own size.

pub fn push_f32(&mut self, value: f32) -> Result<Pos, EncodeError>

Writes a little-endian f32, aligned to its own size.

pub fn push_f64(&mut self, value: f64) -> Result<Pos, EncodeError>

Writes a little-endian f64, aligned to its own size.

pub fn push_offset(&mut self, target: Pos) -> Result<Pos, EncodeError>

Writes a uoffset_t naming target.

pub fn push_string(&mut self, value: &str) -> Result<Pos, EncodeError>

Writes a string: its length, its bytes, and the terminating zero a FlatBuffers string carries so that a reader can hand it to C.

pub fn push_vector( &mut self, elements: &[u8], stride: usize, ) -> Result<Pos, EncodeError>

Writes a vector of scalars that the caller has already encoded, each stride bytes, in element order.

When stride is eight the buffer’s own alignment must be at least eight, so Builder::finish is passed eight or more; otherwise the elements are aligned within the buffer and the buffer is not.

pub fn push_offset_vector( &mut self, targets: &[Pos], ) -> Result<Pos, EncodeError>

Writes a vector of uoffset_ts naming objects already written, in element order.

A vector of strings, of tables, or of anything else the projection places out of line is written this way: the elements are pushed first, and their positions are handed over here. Each offset is relative to its own position in the vector, which is why the caller cannot compute them itself — a Pos carries no arithmetic outside this module.

pub fn push_table( &mut self, size: usize, align: usize, slots: u16, fields: &[TableField], ) -> Result<Pos, EncodeError>

Writes a table and the vtable that describes it.

size, align, slots and each field’s offset are the projection’s facts about the type, not this builder’s: it writes the layout it is given. slots is the number of vtable entries, which is the number of fields the type declares, whether or not each one is present here.

A field the caller leaves out of fields is absent from the buffer, which is how a FlatBuffers table carries a field equal to its default.

pub fn finish(self, root: Pos, align: usize) -> Result<&'a [u8], EncodeError>

Writes the root offset and returns the finished buffer: a subslice of the caller’s slice ending at its end.

align is the buffer’s alignment, the largest any object in it needs. The finished buffer’s length is a multiple of it, which is what makes every object’s own alignment hold once the root sits at offset zero.