## `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=` | Assignment operator.
`push_array` | Push an array onto the stack.
`push_bool` | Push a `bool` onto the stack.
`push_chars` | Push a part of a key or a string onto the stack.
`push_double` | Push a `double` onto the stack.
`push_int64` | Push a `std::int64_t` onto the stack.
`push_key` | Push an `object` key onto the stack.
`push_null` | Push a null onto the stack.
`push_object` | Push an object onto the stack.
`push_string` | Place a string value onto the stack.
`push_uint64` | Push a `std::uint64_t` onto the stack.
`release` | Return the top-level `value`.
`reset` | Prepare to build a new document.
`value_stack` [constructor] | Constructors.
`~value_stack` [destructor] | Destructor.

### Description

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>.

Edit this page