Struct Builder 

pub struct Builder { /* private fields */ }

A value under construction.

Reusable: Builder::finish hands back the bytes and Builder::clear puts it back to empty with its buffers intact, so a loop over a million documents allocates a handful of times rather than a million.

Implementations

impl Builder

pub fn new() -> Builder

An empty builder.

pub fn with_capacity(bytes: usize) -> Builder

Empty, with room for bytes of value already reserved.

pub fn clear(&mut self)

Throw away everything written so far and keep the buffers.

pub fn finish(&mut self) -> Result<&[u8], Error>

The finished value.

An error here means the value is not finished: a container was begun and not ended, a key was written with no value after it, or nothing was written at all.

pub fn null(&mut self) -> Result<(), Error>

Write null.

pub fn bool(&mut self, v: bool) -> Result<(), Error>

Write a boolean.

pub fn int(&mut self, v: i64) -> Result<(), Error>

Write an integer, in as few bytes as it fits in.

pub fn float(&mut self, v: f64) -> Result<(), Error>

Write a float.

pub fn text(&mut self, v: &str) -> Result<(), Error>

Write a string.

pub fn text_bytes(&mut self, v: &[u8]) -> Result<(), Error>

Write a string that is already bytes.

The bytes are stored as they are and are not checked, so a caller that hands over something that is not UTF-8 gets a document whose Value::as_text answers None where it should have answered a string. It exists because RESP carries strings as bytes and re-checking what a client already sent is a copy nobody asked for.

pub fn embed(&mut self, v: &Value<'_>) -> Result<(), Error>

Copy a value that is already encoded.

This is how a path update writes the parts of a document it is not changing: they are already in the right form, so they are memcpy and not a re-encode.

pub fn begin_object(&mut self) -> Result<(), Error>

Begin an object. Every value inside it needs a Builder::key first.

pub fn begin_object_interned(&mut self) -> Result<(), Error>

Begin an object whose keys are ids from a collection’s intern table.

Every value inside it needs a Builder::key_id first. This is what a typed collection writes, and it is where the size of a document collection mostly goes: the same twenty field names on every document cost two bytes each here instead of their bytes.

pub fn begin_array(&mut self) -> Result<(), Error>

Begin an array.

pub fn end_object(&mut self) -> Result<(), Error>

End the object begun by the matching Builder::begin_object.

pub fn end_array(&mut self) -> Result<(), Error>

End the array begun by the matching Builder::begin_array.

pub fn key(&mut self, key: &[u8]) -> Result<(), Error>

The key the next value goes under.

Members may be written in any order, since the container sorts them when it closes. Writing the same key twice keeps the last one, which is what every JSON parser does and what JSON.SET has to do.

pub fn key_id(&mut self, id: u16) -> Result<(), Error>

The intern table id the next value goes under.

impl Builder

pub fn json(&mut self, text: &[u8]) -> Result<(), Error>

Write the one JSON value in text.

This writes a value where a value goes, so it works on an empty builder and it works just as well after a Builder::key inside an open object, which is what a path update needs: the parts of the document that are not changing are copied with Builder::embed and the part that is arrives as text.

text holds exactly one value. Anything after it, other than whitespace, is an error rather than something quietly ignored, because a client that sent two values meant something and it was not this.

Trait Implementations

impl Debug for Builder

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

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Builder

Returns the “default value” for a type.