Diff coverage report for

//

//

// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// 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)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/boostorg/json

// Official repository: https://github.com/boostorg/json

//

//

#ifndef BOOST_JSON_STREAM_PARSER_HPP

#ifndef BOOST_JSON_STREAM_PARSER_HPP

#define BOOST_JSON_STREAM_PARSER_HPP

#define BOOST_JSON_STREAM_PARSER_HPP

#include <boost/json/detail/config.hpp>

#include <boost/json/detail/config.hpp>

#include <boost/json/basic_parser.hpp>

#include <boost/json/basic_parser.hpp>

#include <boost/json/parse_options.hpp>

#include <boost/json/parse_options.hpp>

#include <boost/json/storage_ptr.hpp>

#include <boost/json/storage_ptr.hpp>

#include <boost/json/value.hpp>

#include <boost/json/value.hpp>

#include <boost/json/detail/handler.hpp>

#include <boost/json/detail/handler.hpp>

#include <type_traits>

#include <type_traits>

#include <cstddef>

#include <cstddef>

namespace boost {

namespace boost {

namespace json {

namespace json {

//----------------------------------------------------------

//----------------------------------------------------------

/** A DOM parser for JSON text contained in multiple buffers.

/** A DOM parser for JSON text contained in multiple buffers.

    This class is used to parse a JSON text contained in a series of one or

    This class is used to parse a JSON text contained in a series of one or

    more character buffers, into a @ref value container. It implements a

    more character buffers, into a @ref value container. It implements a

    [_streaming algorithm_](https://en.wikipedia.org/wiki/Streaming_algorithm),

    [_streaming algorithm_](https://en.wikipedia.org/wiki/Streaming_algorithm),

    allowing these parsing strategies:

    allowing these parsing strategies:

    @li parse a JSON file a piece at a time;

    @li parse a JSON file a piece at a time;

    @li parse incoming JSON text as it arrives, one buffer at a time;

    @li parse incoming JSON text as it arrives, one buffer at a time;

    @li parse with bounded resource consumption per cycle.

    @li parse with bounded resource consumption per cycle.

    @par Usage

    @par Usage

    To use the parser first construct it, then optionally call @ref reset to

    To use the parser first construct it, then optionally call @ref reset to

    specify a @ref storage_ptr to use for the resulting @ref value. Then call

    specify a @ref storage_ptr to use for the resulting @ref value. Then call

    @ref write one or more times to parse a single, complete JSON text. Call

    @ref write one or more times to parse a single, complete JSON text. Call

    @ref done to determine if the parse has completed. To indicate there are no

    @ref done to determine if the parse has completed. To indicate there are no

    more buffers, call @ref finish. If the parse is successful, call @ref

    more buffers, call @ref finish. If the parse is successful, call @ref

    release to take ownership of the value:

    release to take ownership of the value:

    @code

    @code

    stream_parser p;                                // construct a parser

    stream_parser p;                                // construct a parser

    p.write( "[1,2" );                              // parse some of a JSON text

    p.write( "[1,2" );                              // parse some of a JSON text

    p.write( ",3,4]" );                             // parse the rest of the JSON text

    p.write( ",3,4]" );                             // parse the rest of the JSON text

    assert( p.done() );                             // we have a complete JSON text

    assert( p.done() );                             // we have a complete JSON text

    value jv = p.release();                         // take ownership of the value

    value jv = p.release();                         // take ownership of the value

    @endcode

    @endcode

    @par Extra Data

    @par Extra Data

    When the character buffer provided as input contains additional data that

    When the character buffer provided as input contains additional data that

    is not part of the complete JSON text, an error is returned. The @ref

    is not part of the complete JSON text, an error is returned. The @ref

    write_some function is an alternative which allows the parse to finish

    write_some function is an alternative which allows the parse to finish

    early, without consuming all the characters in the buffer. This allows

    early, without consuming all the characters in the buffer. This allows

    parsing of a buffer containing multiple individual JSON texts or containing

    parsing of a buffer containing multiple individual JSON texts or containing

    different protocol data:

    different protocol data:

    @code

    @code

    stream_parser p;                                // construct a parser

    stream_parser p;                                // construct a parser

    std::size_t n;                                  // number of characters used

    std::size_t n;                                  // number of characters used

    n = p.write_some( "[1,2" );                     // parse some of a JSON text

    n = p.write_some( "[1,2" );                     // parse some of a JSON text

    assert( n == 4 );                               // all characters consumed

    assert( n == 4 );                               // all characters consumed

    n = p.write_some( ",3,4] null" );               // parse the remainder of the JSON text

    n = p.write_some( ",3,4] null" );               // parse the remainder of the JSON text

    assert( n == 6 );                               // only some characters consumed

    assert( n == 6 );                               // only some characters consumed

    assert( p.done() );                             // we have a complete JSON text

    assert( p.done() );                             // we have a complete JSON text

    value jv = p.release();                         // take ownership of the value

    value jv = p.release();                         // take ownership of the value

    @endcode

    @endcode

    @par Temporary Storage

    @par Temporary Storage

    The parser may dynamically allocate temporary storage as needed to

    The parser may dynamically allocate temporary storage as needed to

    accommodate the nesting level of the JSON text being parsed. Temporary

    accommodate the nesting level of the JSON text being parsed. Temporary

    storage is first obtained from an optional, caller-owned buffer specified

    storage is first obtained from an optional, caller-owned buffer specified

    upon construction. When that is exhausted, the next allocation uses the

    upon construction. When that is exhausted, the next allocation uses the

    @ref boost::container::pmr::memory_resource passed to the constructor; if

    @ref boost::container::pmr::memory_resource passed to the constructor; if

    no such argument is specified, the default memory resource is used.

    no such argument is specified, the default memory resource is used.

    Temporary storage is freed only when the parser is destroyed; The

    Temporary storage is freed only when the parser is destroyed; The

    performance of parsing multiple JSON texts may be improved by reusing the

    performance of parsing multiple JSON texts may be improved by reusing the

    same parser instance.

    same parser instance.

    It is important to note that the @ref

    It is important to note that the @ref

    boost::container::pmr::memory_resource supplied upon construction is used

    boost::container::pmr::memory_resource supplied upon construction is used

    for temporary storage only, and not for allocating the elements which make

    for temporary storage only, and not for allocating the elements which make

    up the parsed value. That other memory resource is optionally supplied in

    up the parsed value. That other memory resource is optionally supplied in

    each call to @ref reset.

    each call to @ref reset.

    @par Duplicate Keys

    @par Duplicate Keys

    If there are object elements with duplicate keys; that is, if multiple

    If there are object elements with duplicate keys; that is, if multiple

    elements in an object have keys that compare equal, only the last

    elements in an object have keys that compare equal, only the last

    equivalent element will be inserted.

    equivalent element will be inserted.

    @par Non-Standard JSON

    @par Non-Standard JSON

    The @ref parse_options structure optionally provided upon construction is

    The @ref parse_options structure optionally provided upon construction is

    used to customize some parameters of the parser, including which

    used to customize some parameters of the parser, including which

    non-standard JSON extensions should be allowed. A default-constructed parse

    non-standard JSON extensions should be allowed. A default-constructed parse

    options allows only standard JSON.

    options allows only standard JSON.

    @par Thread Safety

    @par Thread Safety

    Distinct instances may be accessed concurrently. Non-const member functions

    Distinct instances may be accessed concurrently. Non-const member functions

    of a shared instance may not be called concurrently with any other member

    of a shared instance may not be called concurrently with any other member

    functions of that instance.

    functions of that instance.

    @see @ref parse, @ref parser, @ref parse_options.

    @see @ref parse, @ref parser, @ref parse_options.

*/

*/

class stream_parser

class stream_parser

{

{

    basic_parser<detail::handler> p_;

    basic_parser<detail::handler> p_;

public:

public:

    /** Destructor.

    /** Destructor.

        All dynamically allocated memory, including

        All dynamically allocated memory, including

        any incomplete parsing results, is freed.

        any incomplete parsing results, is freed.

        @par Complexity

        @par Complexity

        Linear in the size of partial results

        Linear in the size of partial results

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

    */

    */

    /** Constructors.

    /** Constructors.

        Construct a new parser.

        Construct a new parser.

        The parser will only support standard JSON if overloads **(1)**

        The parser will only support standard JSON if overloads **(1)**

        or **(2)** are used. Otherwise the parser will support extensions

        or **(2)** are used. Otherwise the parser will support extensions

        specified by the parameter `opt`.

        specified by the parameter `opt`.

        The parsed value will use the \<\<default_memory_resource,default

        The parsed value will use the \<\<default_memory_resource,default

        memory resource\>\> for storage. To use a different resource, call @ref

        memory resource\>\> for storage. To use a different resource, call @ref

        reset after construction.

        reset after construction.

        The main difference between the overloads is in what the constructed

        The main difference between the overloads is in what the constructed

        parser will use for temporary storage:

        parser will use for temporary storage:

        @li **(1)** the constructed parser uses the default memory resource for

        @li **(1)** the constructed parser uses the default memory resource for

        temporary storage.

        temporary storage.

        @li **(2)**, **(3)** the constructed parser uses the memory resource of

        @li **(2)**, **(3)** the constructed parser uses the memory resource of

        `sp` for temporary storage.

        `sp` for temporary storage.

        @li **(4)**, **(6)** the constructed parser first uses the caller-owned

        @li **(4)**, **(6)** the constructed parser first uses the caller-owned

        storage `[buffer, buffer + size)` for temporary storage, falling back

        storage `[buffer, buffer + size)` for temporary storage, falling back

        to the memory resource of `sp` if needed.

        to the memory resource of `sp` if needed.

        @li **(5)**, **(7)** the constructed parser first uses the caller-owned

        @li **(5)**, **(7)** the constructed parser first uses the caller-owned

        storage `[buffer, buffer + N)` for temporary storage, falling back to

        storage `[buffer, buffer + N)` for temporary storage, falling back to

        the memory resource of `sp` if needed.

        the memory resource of `sp` if needed.

        @note Ownership of `buffer` is not transferred. The caller is

        @note Ownership of `buffer` is not transferred. The caller is

        responsible for ensuring the lifetime of the storage pointed to by

        responsible for ensuring the lifetime of the storage pointed to by

        `buffer` extends until the parser is destroyed.

        `buffer` extends until the parser is destroyed.

        Overload **(8)** is the copy constructor. The type is neither copyable

        Overload **(8)** is the copy constructor. The type is neither copyable

        nor movable, so the overload is deleted.

        nor movable, so the overload is deleted.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

        @{

        @{

    */

    */

    {

    {

    /** Overload

    /** Overload

        @param sp The memory resource to use for temporary storage.

        @param sp The memory resource to use for temporary storage.

    */

    */

    explicit

    explicit

    {

    {

    /** Overload

    /** Overload

        @param opt The parsing options to use.

        @param opt The parsing options to use.

        @param sp

        @param sp

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    stream_parser(

    stream_parser(

        storage_ptr sp,

        storage_ptr sp,

        parse_options const& opt) noexcept;

        parse_options const& opt) noexcept;

    /** Overload

    /** Overload

        @param buffer A pointer to valid storage.

        @param buffer A pointer to valid storage.

        @param size The number of valid bytes in `buffer`.

        @param size The number of valid bytes in `buffer`.

        @param sp

        @param sp

        @param opt

        @param opt

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    stream_parser(

    stream_parser(

        storage_ptr sp,

        storage_ptr sp,

        parse_options const& opt,

        parse_options const& opt,

        unsigned char* buffer,

        unsigned char* buffer,

        std::size_t size) noexcept;

        std::size_t size) noexcept;

    /** Overload

    /** Overload

        @tparam N The number of valid bytes in `buffer`.

        @tparam N The number of valid bytes in `buffer`.

        @param sp

        @param sp

        @param opt

        @param opt

        @param buffer

        @param buffer

    */

    */

    template<std::size_t N>

    template<std::size_t N>

        storage_ptr sp,

        storage_ptr sp,

        parse_options const& opt,

        parse_options const& opt,

        unsigned char(&buffer)[N]) noexcept

        unsigned char(&buffer)[N]) noexcept

    {

    {

#if defined(__cpp_lib_byte) || defined(BOOST_JSON_DOCS)

#if defined(__cpp_lib_byte) || defined(BOOST_JSON_DOCS)

    /** Overload

    /** Overload

        @param sp

        @param sp

        @param opt

        @param opt

        @param buffer

        @param buffer

        @param size

        @param size

    */

    */

    stream_parser(

    stream_parser(

        storage_ptr sp,

        storage_ptr sp,

        parse_options const& opt,

        parse_options const& opt,

        std::byte* buffer,

        std::byte* buffer,

        std::size_t size) noexcept

        std::size_t size) noexcept

        : stream_parser(sp, opt, reinterpret_cast<

        : stream_parser(sp, opt, reinterpret_cast<

            unsigned char*>(buffer), size)

            unsigned char*>(buffer), size)

    {

    {

    }

    }

    /** Overload

    /** Overload

        @tparam N

        @tparam N

        @param sp

        @param sp

        @param opt

        @param opt

        @param buffer

        @param buffer

    */

    */

    template<std::size_t N>

    template<std::size_t N>

    stream_parser(

    stream_parser(

        storage_ptr sp,

        storage_ptr sp,

        parse_options const& opt,

        parse_options const& opt,

        std::byte(&buffer)[N]) noexcept

        std::byte(&buffer)[N]) noexcept

        : stream_parser(std::move(sp),

        : stream_parser(std::move(sp),

            opt, &buffer[0], N)

            opt, &buffer[0], N)

    {

    {

    }

    }

#endif

#endif

#ifndef BOOST_JSON_DOCS

#ifndef BOOST_JSON_DOCS

    // Safety net for accidental buffer overflows

    // Safety net for accidental buffer overflows

    template<std::size_t N>

    template<std::size_t N>

    stream_parser(

    stream_parser(

        storage_ptr sp,

        storage_ptr sp,

        parse_options const& opt,

        parse_options const& opt,

        unsigned char(&buffer)[N],

        unsigned char(&buffer)[N],

        std::size_t n) noexcept

        std::size_t n) noexcept

        : stream_parser(std::move(sp),

        : stream_parser(std::move(sp),

            opt, &buffer[0], n)

            opt, &buffer[0], n)

    {

    {

        // If this goes off, check your parameters

        // If this goes off, check your parameters

        // closely, chances are you passed an array

        // closely, chances are you passed an array

        // thinking it was a pointer.

        // thinking it was a pointer.

        BOOST_ASSERT(n <= N);

        BOOST_ASSERT(n <= N);

    }

    }

#ifdef __cpp_lib_byte

#ifdef __cpp_lib_byte

    // Safety net for accidental buffer overflows

    // Safety net for accidental buffer overflows

    template<std::size_t N>

    template<std::size_t N>

    stream_parser(

    stream_parser(

        storage_ptr sp,

        storage_ptr sp,

        parse_options const& opt,

        parse_options const& opt,

        std::byte(&buffer)[N], std::size_t n) noexcept

        std::byte(&buffer)[N], std::size_t n) noexcept

        : stream_parser(std::move(sp),

        : stream_parser(std::move(sp),

            opt, &buffer[0], n)

            opt, &buffer[0], n)

    {

    {

        // If this goes off, check your parameters

        // If this goes off, check your parameters

        // closely, chances are you passed an array

        // closely, chances are you passed an array

        // thinking it was a pointer.

        // thinking it was a pointer.

        BOOST_ASSERT(n <= N);

        BOOST_ASSERT(n <= N);

    }

    }

#endif

#endif

#endif

#endif

    /// Overload

    /// Overload

    stream_parser(

    stream_parser(

        stream_parser const&) = delete;

        stream_parser const&) = delete;

    /// @}

    /// @}

    /** Assignment operator.

    /** Assignment operator.

       This type is neither copyable nor movable, so copy assignment operator

       This type is neither copyable nor movable, so copy assignment operator

       is deleted.

       is deleted.

   */

   */

    stream_parser& operator=(

    stream_parser& operator=(

        stream_parser const&) = delete;

        stream_parser const&) = delete;

    /** Reset the parser for a new JSON text.

    /** Reset the parser for a new JSON text.

        This function is used to reset the parser to prepare it for parsing

        This function is used to reset the parser to prepare it for parsing

        a new complete JSON text. Any previous partial results are destroyed.

        a new complete JSON text. Any previous partial results are destroyed.

        The new value will use the memory resource of `sp`.

        The new value will use the memory resource of `sp`.

        @par Complexity

        @par Complexity

        Constant or linear in the size of any previous partial parsing results.

        Constant or linear in the size of any previous partial parsing results.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

        @param sp A pointer to the @ref boost::container::pmr::memory_resource.

        @param sp A pointer to the @ref boost::container::pmr::memory_resource.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(storage_ptr sp = {}) noexcept;

    reset(storage_ptr sp = {}) noexcept;

    /** Check if a complete JSON text has been parsed.

    /** Check if a complete JSON text has been parsed.

        This function returns `true` when all of these conditions are met:

        This function returns `true` when all of these conditions are met:

        @li A complete serialized JSON text has been presented to the parser,

        @li A complete serialized JSON text has been presented to the parser,

        and

        and

        @li No error has occurred since the parser was constructed, or since

        @li No error has occurred since the parser was constructed, or since

        the last call to @ref reset,

        the last call to @ref reset,

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Parse a buffer containing all or part of a complete JSON text.

    /** Parse a buffer containing all or part of a complete JSON text.

        This function parses JSON text contained in the specified character

        This function parses JSON text contained in the specified character

        buffer. If parsing completes, any additional characters past the end of

        buffer. If parsing completes, any additional characters past the end of

        the complete JSON text are ignored. The function returns the actual

        the complete JSON text are ignored. The function returns the actual

        number of characters parsed, which may be less than the size of the

        number of characters parsed, which may be less than the size of the

        input. This allows parsing of a buffer containing multiple individual

        input. This allows parsing of a buffer containing multiple individual

        JSON texts or containing different protocol data.

        JSON texts or containing different protocol data.

        Overloads **(1)**, **(2)**, **(4)**, and **(5)** report errors by

        Overloads **(1)**, **(2)**, **(4)**, and **(5)** report errors by

        setting `ec`. Overloads **(3)** and **(6)** report errors by throwing

        setting `ec`. Overloads **(3)** and **(6)** report errors by throwing

        exceptions. Upon error or exception, subsequent calls will fail until

        exceptions. Upon error or exception, subsequent calls will fail until

        @ref reset is called to parse a new JSON text.

        @ref reset is called to parse a new JSON text.

        @note To indicate there are no more character buffers, such as when

        @note To indicate there are no more character buffers, such as when

        @ref done returns `false` after writing, call @ref finish.

        @ref done returns `false` after writing, call @ref finish.

        @par Example

        @par Example

        @code

        @code

        stream_parser p;                                // construct a parser

        stream_parser p;                                // construct a parser

        std::size_t n;                                  // number of characters used

        std::size_t n;                                  // number of characters used

        n = p.write_some( "[1,2" );                     // parse the first part of the JSON text

        n = p.write_some( "[1,2" );                     // parse the first part of the JSON text

        assert( n == 4 );                               // all characters consumed

        assert( n == 4 );                               // all characters consumed

        n = p.write_some( "3,4] null" );                // parse the rest of the JSON text

        n = p.write_some( "3,4] null" );                // parse the rest of the JSON text

        assert( n == 5 );                               // only some characters consumed

        assert( n == 5 );                               // only some characters consumed

        value jv = p.release();                         // take ownership of the value

        value jv = p.release();                         // take ownership of the value

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        @li **(1)**--**(3)** linear in `size`.

        @li **(1)**--**(3)** linear in `size`.

        @li **(4)**--**(6)** linear in `s.size()`.

        @li **(4)**--**(6)** linear in `s.size()`.

        @par Exception Safety

        @par Exception Safety

        Basic guarantee. Calls to `memory_resource::allocate` may throw.

        Basic guarantee. Calls to `memory_resource::allocate` may throw.

        @return The number of characters consumed from the buffer.

        @return The number of characters consumed from the buffer.

        @param data A pointer to a buffer of `size` characters to parse.

        @param data A pointer to a buffer of `size` characters to parse.

        @param size The number of characters pointed to by `data`.

        @param size The number of characters pointed to by `data`.

        @param ec Set to the error, if any occurred.

        @param ec Set to the error, if any occurred.

        @{

        @{

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    std::size_t

    std::size_t

    write_some(

    write_some(

        char const* data,

        char const* data,

        std::size_t size,

        std::size_t size,

        system::error_code& ec);

        system::error_code& ec);

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    std::size_t

    std::size_t

    write_some(

    write_some(

        char const* data,

        char const* data,

        std::size_t size,

        std::size_t size,

        std::error_code& ec);

        std::error_code& ec);

    /** Overload

    /** Overload

        @param data

        @param data

        @param size

        @param size

        @throw boost::system::system_error Thrown on error.

        @throw boost::system::system_error Thrown on error.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    std::size_t

    std::size_t

    write_some(

    write_some(

        char const* data,

        char const* data,

        std::size_t size);

        std::size_t size);

    /** Overload

    /** Overload

        @param s The character string to parse.

        @param s The character string to parse.

        @param ec

        @param ec

    */

    */

    std::size_t

    std::size_t

        string_view s,

        string_view s,

        system::error_code& ec)

        system::error_code& ec)

    {

    {

    }

    }

    /** Overload

    /** Overload

        @param s

        @param s

        @param ec

        @param ec

    */

    */

    std::size_t

    std::size_t

        string_view s,

        string_view s,

        std::error_code& ec)

        std::error_code& ec)

    {

    {

    }

    }

    /** Overload

    /** Overload

        @param s

        @param s

    */

    */

    std::size_t

    std::size_t

        string_view s)

        string_view s)

    {

    {

    }

    }

    /// @}

    /// @}

    /** Parse a buffer containing all or part of a complete JSON text.

    /** Parse a buffer containing all or part of a complete JSON text.

        This function parses all or part of a JSON text contained in the

        This function parses all or part of a JSON text contained in the

        specified character buffer. The entire buffer must be consumed; if

        specified character buffer. The entire buffer must be consumed; if

        there are additional characters past the end of the complete JSON text,

        there are additional characters past the end of the complete JSON text,

        the parse fails and an error is returned.

        the parse fails and an error is returned.

        Overloads **(1)**, **(2)**, **(4)**, and **(5)** report errors by

        Overloads **(1)**, **(2)**, **(4)**, and **(5)** report errors by

        setting `ec`. Overloads **(3)** and **(6)** report errors by throwing

        setting `ec`. Overloads **(3)** and **(6)** report errors by throwing

        exceptions. Upon error or exception, subsequent calls will fail until

        exceptions. Upon error or exception, subsequent calls will fail until

        @ref reset is called to parse a new JSON text.

        @ref reset is called to parse a new JSON text.

        @note To indicate there are no more character buffers, such as when

        @note To indicate there are no more character buffers, such as when

        @ref done returns `false` after writing, call @ref finish.

        @ref done returns `false` after writing, call @ref finish.

        @par Example

        @par Example

        @code

        @code

        stream_parser p;                                // construct a parser

        stream_parser p;                                // construct a parser

        std::size_t n;                                  // number of characters used

        std::size_t n;                                  // number of characters used

        n = p.write( "[1,2" );                          // parse some of the JSON text

        n = p.write( "[1,2" );                          // parse some of the JSON text

        assert( n == 4 );                               // all characters consumed

        assert( n == 4 );                               // all characters consumed

        n = p.write( "3,4]" );                          // parse the rest of the JSON text

        n = p.write( "3,4]" );                          // parse the rest of the JSON text

        assert( n == 4 );                               // all characters consumed

        assert( n == 4 );                               // all characters consumed

        value jv = p.release();                         // take ownership of the value

        value jv = p.release();                         // take ownership of the value

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        @li **(1)**--**(3)** linear in `size`.

        @li **(1)**--**(3)** linear in `size`.

        @li **(4)**--**(6)** linear in `s.size()`.

        @li **(4)**--**(6)** linear in `s.size()`.

        @par Exception Safety

        @par Exception Safety

        Basic guarantee. Calls to `memory_resource::allocate` may throw.

        Basic guarantee. Calls to `memory_resource::allocate` may throw.

        @return The number of characters consumed from the buffer.

        @return The number of characters consumed from the buffer.

        @param data A pointer to a buffer of `size` characters to parse.

        @param data A pointer to a buffer of `size` characters to parse.

        @param size The number of characters pointed to by `data`.

        @param size The number of characters pointed to by `data`.

        @param ec Set to the error, if any occurred.

        @param ec Set to the error, if any occurred.

        @{

        @{

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    std::size_t

    std::size_t

    write(

    write(

        char const* data,

        char const* data,

        std::size_t size,

        std::size_t size,

        system::error_code& ec);

        system::error_code& ec);

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    std::size_t

    std::size_t

    write(

    write(

        char const* data,

        char const* data,

        std::size_t size,

        std::size_t size,

        std::error_code& ec);

        std::error_code& ec);

    /** Overload

    /** Overload

        @param data

        @param data

        @param size

        @param size

        @throw boost::system::system_error Thrown on error.

        @throw boost::system::system_error Thrown on error.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    std::size_t

    std::size_t

    write(

    write(

        char const* data,

        char const* data,

        std::size_t size);

        std::size_t size);

    /** Overload

    /** Overload

        @param s The character string to parse.

        @param s The character string to parse.

        @param ec

        @param ec

    */

    */

    std::size_t

    std::size_t