boost/json/value_stack.hpp
// // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) // // Distributed under the Boost Software License, Version 1.0. (See accompanying // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) // // Official repository: https://github.com/boostorg/json // #ifndef BOOST_JSON_VALUE_STACK_HPP #define BOOST_JSON_VALUE_STACK_HPP #include <boost/json/detail/config.hpp> #include <boost/json/error.hpp> #include <boost/json/storage_ptr.hpp> #include <boost/json/value.hpp> #include <stddef.h> namespace boost { namespace json { //---------------------------------------------------------- /** A stack of @ref value elements, for building a document. This stack of @ref 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 @ref 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. @par Usage Construct the stack with an optional initial temporary buffer, and a @ref storage_ptr to use for more storage when the initial buffer is exhausted. Then to build a @ref value, first call @ref 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 @ref release to acquire ownership of the top-level @ref value. @par 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. @par Example The following code constructs a @ref 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. @code // 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 @endcode @par 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. */ class value_stack { class stack { enum { min_size_ = 16 }; storage_ptr sp_; void* temp_; value* begin_; value* top_; value* end_; // string starts at top_+1 std::size_t chars_ = 0; bool run_dtors_ = true; public: inline ~stack(); inline stack( storage_ptr sp, void* temp, std::size_t size) noexcept; inline void run_dtors(bool b) noexcept; inline std::size_t size() const noexcept; inline bool has_chars(); inline void clear() noexcept; inline void maybe_grow(); inline void grow_one(); inline void grow(std::size_t nchars); inline void append(string_view s); inline string_view release_string() noexcept; inline value* release(std::size_t n) noexcept; template<class... Args> value& push(Args&&... args); template<class Unchecked> void exchange(Unchecked&& u); }; stack st_; storage_ptr sp_; public: /// Copy constructor (deleted) value_stack( value_stack const&) = delete; /// Copy assignment (deleted) value_stack& operator=( value_stack const&) = delete; /** Destructor. All dynamically allocated memory and partial or complete elements is freed. @par Complexity Linear in the size of partial results. @par Exception Safety No-throw guarantee. */ BOOST_JSON_DECL ~value_stack(); /** Constructor. Constructs an empty stack. Before any @ref value can be built, the function @ref reset must be called. The `sp` parameter is only used to allocate intermediate storage; it will not be used for the @ref value returned by @ref release. @param sp A pointer to the `boost::container::pmr::memory_resource` to use for intermediate storage allocations. If this argument is omitted, the default memory resource is used. @param temp_buffer A pointer to a caller-owned buffer which will be used to store temporary data used while building the value. If this pointer is null, the builder will use the storage pointer to allocate temporary data. @param temp_size The number of valid bytes of storage pointed to by `temp_buffer`. */ BOOST_JSON_DECL value_stack( storage_ptr sp = {}, unsigned char* temp_buffer = nullptr, std::size_t temp_size = 0) noexcept; /** Prepare to build a new document. This function must be called before constructing a new top-level @ref value. Any previously existing partial or complete elements are destroyed, but internal dynamically allocated memory is preserved which may be reused to build new values. @par Exception Safety No-throw guarantee. @param sp A pointer to the `boost::container::pmr::memory_resource` to use for top-level @ref value and all child values. The stack will acquire shared ownership of the memory resource until @ref release or @ref reset is called, or when the stack is destroyed. */ BOOST_JSON_DECL void reset(storage_ptr sp = {}) noexcept; /** Return the top-level @ref value. This function transfers ownership of the constructed top-level value to the caller. The behavior is undefined if there is not a single, top-level element. @par Exception Safety No-throw guarantee. @return A __value__ holding the result. Ownership of this value is transferred to the caller. Ownership of the memory resource used in the last call to @ref reset is released. */ BOOST_JSON_DECL value release() noexcept; //-------------------------------------------- /** Push an array formed by popping `n` values from the stack. This function pushes an @ref array value onto the stack. The array is formed by first popping the top `n` values from the stack. If the stack contains fewer than `n` values, or if any of the top `n` values on the stack is a key, the behavior is undefined. @par Example The following statements produce an array with the contents 1, 2, 3: @code value_stack st; // reset must be called first or else the behavior is undefined st.reset(); // Place three values on the stack st.push_int64( 1 ); st.push_int64( 2 ); st.push_int64( 3 ); // Remove the 3 values, and push an array with those 3 elements on the stack st.push_array( 3 ); // Pop the object from the stack and take ownership. value jv = st.release(); assert( serialize(jv) == "[1,2,3]" ); // At this point, reset must be called again to use the stack @endcode @param n The number of values to pop from the top of the stack to form the array. */ BOOST_JSON_DECL void push_array(std::size_t n); /** Push an object formed by popping `n` key/value pairs from the stack. This function pushes an @ref object value onto the stack. The object is formed by first popping the top `n` key/value pairs from the stack. If the stack contains fewer than `n` key/value pairs, or if any of the top `n` key/value pairs on the stack does not consist of exactly one key followed by one value, the behavior is undefined. @note A key/value pair is formed by pushing a key, and then pushing a value. @par Example The following code creates an object on the stack with a single element, where key is "x" and value is true: @code value_stack st; // reset must be called first or else the behavior is undefined st.reset(); // Place a key/value pair onto the stack st.push_key( "x" ); st.push_bool( true ); // Replace the key/value pair with an object containing a single element st.push_object( 1 ); // Pop the object from the stack and take ownership. value jv = st.release(); assert( serialize(jv) == "{\"x\",true}" ); // At this point, reset must be called again to use the stack @endcode @par Duplicate Keys If there are object elements with duplicate keys; that is, if multiple elements in an object have keys that compare equal, only the last equivalent element will be inserted. @param n The number of key/value pairs to pop from the top of the stack to form the array. */ BOOST_JSON_DECL void push_object(std::size_t n); /** Push part of a key or string onto the stack. This function pushes the characters in `s` onto the stack, appending to any existing characters or creating new characters as needed. Once a string part is placed onto the stack, the only valid stack operations are: @li @ref push_chars to append additional characters to the key or string being built, @li @ref push_key or @ref push_string to finish building the key or string and place the value onto the stack. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. @param s The characters to append. This may be empty. */ BOOST_JSON_DECL void push_chars( string_view s); /** Push a key onto the stack. This function notionally removes all the characters currently on the stack, then pushes a @ref value containing a key onto the stack formed by appending `s` to the removed characters. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. @param s The characters to append. This may be empty. */ BOOST_JSON_DECL void push_key( string_view s); /** Place a string value onto the stack. This function notionally removes all the characters currently on the stack, then pushes a @ref value containing a @ref string onto the stack formed by appending `s` to the removed characters. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. @param s The characters to append. This may be empty. */ BOOST_JSON_DECL void push_string( string_view s); /** Push a number onto the stack This function pushes a number value onto the stack. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. @param i The number to insert. */ BOOST_JSON_DECL void push_int64( int64_t i); /** Push a number onto the stack This function pushes a number value onto the stack. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. @param u The number to insert. */ BOOST_JSON_DECL void push_uint64( uint64_t u); /** Push a number onto the stack This function pushes a number value onto the stack. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. @param d The number to insert. */ BOOST_JSON_DECL void push_double( double d); /** Push a `bool` onto the stack This function pushes a boolean value onto the stack. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. @param b The boolean to insert. */ BOOST_JSON_DECL void push_bool( bool b); /** Push a null onto the stack This function pushes a boolean value onto the stack. @par Exception Safety Basic guarantee. Calls to `memory_resource::allocate` may throw. */ BOOST_JSON_DECL void push_null(); }; } // namespace json } // namespace boost #endif