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_SERIALIZER_HPP

#ifndef BOOST_JSON_SERIALIZER_HPP

#define BOOST_JSON_SERIALIZER_HPP

#define BOOST_JSON_SERIALIZER_HPP

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

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

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

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

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

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

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

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

#include <boost/json/serialize_options.hpp>

#include <boost/json/serialize_options.hpp>

#include <boost/json/value.hpp>

#include <boost/json/value.hpp>

namespace boost {

namespace boost {

namespace json {

namespace json {

/** A serializer for JSON.

/** A serializer for JSON.

    This class traverses an instance of a library type and emits serialized

    This class traverses an instance of a library

    JSON text by filling in one or more caller-provided buffers. To use,

    type and emits serialized JSON text by filling

    declare a variable and call @ref reset with a pointer to the variable you

    in one or more caller-provided buffers. To use,

    want to serialize. Then call @ref read over and over until @ref done

    declare a variable and call @ref reset with

    returns `true`.

    a pointer to the variable you want to serialize.

    Then call @ref read over and over until

    @ref done returns `true`.

    @par Example

    @par Example

    This demonstrates how the serializer may be used to print a JSON value to

    an output stream.

    This demonstrates how the serializer may

    be used to print a JSON value to an output

    stream.

    @code

    @code

    void print( std::ostream& os, value const& jv)

    void print( std::ostream& os, value const& jv)

    {

    {

        serializer sr;

        serializer sr;

        sr.reset( &jv );

        sr.reset( &jv );

        while( ! sr.done() )

        while( ! sr.done() )

        {

        {

            char buf[ 4000 ];

            char buf[ 4000 ];

            os << sr.read( buf );

            os << sr.read( buf );

        }

        }

    }

    }

    @endcode

    @endcode

    The same instance may not be accessed concurrently.

    @par Thread Safety

    @par Thread Safety

    @par Non-Standard JSON

    The same instance may not be accessed concurrently.

    The @ref serialize_options structure optionally provided upon construction

    is used to enable non-standard JSON extensions. A default-constructed

    `serialize_options` doesn't enable any extensions.

    @see @ref serialize.

*/

*/

class serializer

class serializer

    : detail::writer

    : detail::writer

{

{

    using fn_t = bool (*)(writer&, detail::stream&);

    using fn_t = bool (*)(writer&, detail::stream&);

    fn_t fn0_ = nullptr;

    fn_t fn0_ = nullptr;

    fn_t fn1_ = nullptr;

    fn_t fn1_ = nullptr;

    bool done_ = false;

    bool done_ = false;

public:

public:

    /// Move constructor (deleted)

    serializer(serializer&&) = delete;

    /** Destructor

    /** Destructor

        All temporary storage is deallocated.

        All temporary storage is deallocated.

        @par Complexity

        @par Complexity

        Constant

        Constant

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

    */

    */

#ifdef BOOST_JSON_DOCS

#ifdef BOOST_JSON_DOCS

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    ~serializer() noexcept;

    ~serializer() noexcept;

#endif // BOOST_JSON_DOCS

#endif // BOOST_JSON_DOCS

    /** Constructors.

    /** Constructor

        The serializer is constructed with no value to serialize The value may

        be set later by calling @ref reset. If serialization is attempted with

        no value, the output is as if a null value is serialized.

        Overload **(3)** is a move constructor. The type is neither copyable

        This constructs a serializer with no value.

        nor movable, so this constructor is deleted.

        The value may be set later by calling @ref reset.

        If serialization is attempted with no value,

        the output is as if a null value is serialized.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

        @param opts The options for the serializer. If this parameter is

        @param opts The options for the serializer. If this parameter

        omitted, the serializer will output only standard JSON.

        is omitted, the serializer will output only standard JSON.

        @{

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    serializer( serialize_options const& opts = {} ) noexcept;

    serializer( serialize_options const& opts = {} ) noexcept;

    /** Overload

    /** Constructor

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

        This constructs a serializer with no value.

        to use when producing partial output. Shared ownership of the memory

        The value may be set later by calling @ref reset.

        If serialization is attempted with no value,

        the output is as if a null value is serialized.

        @par Complexity

        Constant.

        @par Exception Safety

        No-throw guarantee.

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

        use when producing partial output. Shared ownership of the memory

        resource is retained until the serializer is destroyed.

        resource is retained until the serializer is destroyed.

        @param buf An optional static buffer to use for temporary storage when

        @param buf An optional static buffer to

        producing partial output.

        use for temporary storage when producing

        partial output.

        @param size The number of bytes of valid memory pointed to by

        @param buf_size The number of bytes of

        `buf`.

        valid memory pointed to by `buf`.

        @param opts

        @param opts The options for the serializer. If this parameter

        is omitted, the serializer will output only standard JSON.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    serializer(

    serializer(

        storage_ptr sp,

        storage_ptr sp,

        unsigned char* buf = nullptr,

        unsigned char* buf = nullptr,

        std::size_t size = 0,

        std::size_t buf_size = 0,

        serialize_options const& opts = {}) noexcept;

        serialize_options const& opts = {}) noexcept;

    /// Overload

    /** Returns `true` if the serialization is complete

    serializer(serializer&&) = delete;

    /// @}

    /** Check if the serialization is complete.

        This function returns `true` when all of the characters in the

        This function returns `true` when all of the

        serialized representation of the value have been read.

        characters in the serialized representation of

        the value have been read.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        No-throw guarantee.

        No-throw guarantee.

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Reset the serializer for a new element.

    /** Reset the serializer for a new element

        This function prepares the serializer to emit a new serialized JSON

        representing its argument: `*p` **(1)**--**(5)**, `sv` **(6)**, or

        `np` **(7)**. Ownership is not transferred. The caller is responsible

        for ensuring that the lifetime of the object pointed to by the argument

        extends until it is no longer needed.

        Any memory internally allocated for previous uses of this `serializer`

        object is preserved and re-used for the new output.

        Overload **(5)** uses \<\<direct_conversion,direct serialization\>\>.

        This function prepares the serializer to emit

        a new serialized JSON representing `*p`.

        Any internally allocated memory is

        preserved and re-used for the new output.

        @param p A pointer to the element to serialize.

        @param p A pointer to the element to serialize.

        Ownership is not transferred; The caller is

        @{

        responsible for ensuring that the lifetime of

        `*p` extends until it is no longer needed.

    */

    */

    /** @{ */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(value const* p) noexcept;

    reset(value const* p) noexcept;

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(array const* p) noexcept;

    reset(array const* p) noexcept;

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(object const* p) noexcept;

    reset(object const* p) noexcept;

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(string const* p) noexcept;

    reset(string const* p) noexcept;

    template<class T>

    template<class T>

    void

    void

    reset(T const* p) noexcept;

    reset(T const* p) noexcept;

    /** @} */

    /** Overload

    /** Reset the serializer for a new string

        @param sv The characters representing a string.

        This function prepares the serializer to emit

        a new serialized JSON representing the string.

        Any internally allocated memory is

        preserved and re-used for the new output.

        @param sv The characters representing the string.

        Ownership is not transferred; The caller is

        responsible for ensuring that the lifetime of

        the characters reference by `sv` extends

        until it is no longer needed.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(string_view sv) noexcept;

    reset(string_view sv) noexcept;

    /** Overload

    /** Reset the serializer for std::nullptr_t

        @param np Represents a null value.

        This function prepares the serializer to emit

        a new serialized JSON representing null.

        Any internally allocated memory is

        preserved and re-used for the new output.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(std::nullptr_t np) noexcept;

    reset(std::nullptr_t) noexcept;

    /// @}

    /** Read the next buffer of serialized JSON.

    /** Read the next buffer of serialized JSON

        This function attempts to fill the caller provided buffer starting at

        This function attempts to fill the caller

        `dest` with up to `size` characters of the serialized JSON that

        provided buffer starting at `dest` with

        represents the value. If the buffer is not large enough, multiple calls

        up to `size` characters of the serialized

        JSON that represents the value. If the

        buffer is not large enough, multiple calls

        may be required.

        may be required.

\n

        If serialization completes during this call;

        that is, that all of the characters belonging

        to the serialized value have been written to

        caller-provided buffers, the function

        @ref done will return `true`.

        If serialization completes during this call; that is, that all of the

        @par Preconditions

        characters belonging to the serialized value have been written to

        caller-provided buffers, the function @ref done will return `true`.

        @pre

        @code

        @code

        done() == false

        this->done() == false

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

        Linear in `size`.

        @li **(2)** linear in `N`.

        @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 A @ref string_view containing the characters written, which may

        be less than `size` or `N`.

        @param dest A pointer to storage to write into.

        @return A @ref string_view containing the

        characters written, which may be less than

        `size`.

        @param size The maximum number of characters to write to the memory

        @param dest A pointer to valid memory of at

        pointed to by `dest`.

        least `size` bytes.

        @{

        @param size The maximum number of characters

        to write to the memory pointed to by `dest`.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    string_view

    string_view

    read(char* dest, std::size_t size);

    read(char* dest, std::size_t size);

    /** Overload

    /** Read the next buffer of serialized JSON

        @tparam N The size of the array `dest`.

        This function allows reading into a

        @param dest

        character array, with a deduced maximum size.

        @par Preconditions

        @code

        this->done() == false

        @endcode

        @par Effects

        @code

        return this->read( dest, N );

        @endcode

        @par Complexity

        Linear in `N`.

        @par Exception Safety

        Basic guarantee.

        Calls to `memory_resource::allocate` may throw.

        @return A @ref string_view containing the

        characters written, which may be less than

        `size`.

        @param dest The character array to write to.

    */

    */

    template<std::size_t N>

    template<std::size_t N>

    string_view

    string_view

    {

    {

    /// @}

    }

    }

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

    string_view

    string_view

    read(char(&dest)[N], std::size_t n)

    read(char(&dest)[N], std::size_t 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);

        return read(dest, n);

        return read(dest, n);

    }

    }

#endif

#endif

};

};

} // namespace json

} // namespace json

} // namespace boost

} // namespace boost

#include <boost/json/impl/serializer.hpp>

#include <boost/json/impl/serializer.hpp>

#endif

#endif