value_stack

A stack of value elements, for building a document.

Synopsis

Defined in header <boost/json/value_stack.hpp>

class value_stack;

Member Functions

Name	Description
operator=	Copy assignment (deleted)
push_array	Push an array formed by popping `n` values from the stack.
push_bool	Push a `bool` onto the stack.
push_chars	Push part of a key or string onto the stack.
push_double	Push a number onto the stack.
push_int64	Push a number onto the stack.
push_key	Push a key onto the stack.
push_null	Push a null onto the stack.
push_object	Push an object formed by popping `n` key/value pairs from the stack.
push_string	Place a string value onto the stack.
push_uint64	Push a number onto the stack.
release	Return the top-level `value`.
reset	Prepare to build a new document.
value_stack [constructor]	Copy constructor (deleted) — Constructor.
~value_stack [destructor]	Destructor.

This stack of value allows iterative construction of a JSON document in memory. The implementation uses temporary internal storage to buffer elements so that arrays, objects, and strings in the document are constructed using a single memory allocation. This improves performance and makes efficient use of the boost::container::pmr::memory_resource used to create the resulting value.

Temporary storage used by the implementation initially comes from an optional memory buffer owned by the caller. If that storage is exhausted, then memory is obtained dynamically from the boost::container::pmr::memory_resource provided on construction.

Usage

Construct the stack with an optional initial temporary buffer, and a storage_ptr to use for more storage when the initial buffer is exhausted. Then to build a value, first call reset and optionally specify the boost::container::pmr::memory_resource which will be used for the value. Then push elements onto the stack by calling the corresponding functions. After the document has been fully created, call release to acquire ownership of the top-level value.

Performance

The initial buffer and any dynamically allocated temporary buffers are retained until the stack is destroyed. This improves performance when using a single stack instance to produce multiple values.

Example

The following code constructs a value which when serialized produces a JSON object with three elements. It uses a local buffer for the temporary storage, and a separate local buffer for the storage of the resulting value. No memory is dynamically allocated; this shows how to construct a value without using the heap.

// This example builds a json::value without any dynamic memory allocations:

// Construct the value stack using a local buffer
unsigned char temp[4096];
value_stack st( storage_ptr(), temp, sizeof(temp) );

// Create a static resource with a local initial buffer
unsigned char buf[4096];
static_resource mr( buf, sizeof(buf) );

// All values on the stack will use `mr`
st.reset(&mr);

// Push the key/value pair "a":1.
st.push_key("a");
st.push_int64(1);

// Push "b":null
st.push_key("b");
st.push_null();

// Push "c":"hello"
st.push_key("c");
st.push_string("hello");

// Pop the three key/value pairs and push an object with those three values.
st.push_object(3);

// Pop the object from the stack and take ownership.
value jv = st.release();

assert( serialize(jv) == "{\"a\":1,\"b\":null,\"c\":\"hello\"}" );

// At this point we could re-use the stack by calling reset

Thread Safety

Distinct instances may be accessed concurrently. Non-const member functions of a shared instance may not be called concurrently with any other member functions of that instance.

Convenience header <boost/json.hpp>