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 type and emits serialized

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

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

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

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

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

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

    returns `true`.

    returns `true`.

    @par Example

    @par Example

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

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

    an output stream.

    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

    @par Thread Safety

    @par Thread Safety

    The same instance may not be accessed concurrently.

    The same instance may not be accessed concurrently.

    @par Non-Standard JSON

    @par Non-Standard JSON

    The @ref serialize_options structure optionally provided upon construction

    The @ref serialize_options structure optionally provided upon construction

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

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

    `serialize_options` doesn't enable any extensions.

    `serialize_options` doesn't enable any extensions.

    @see @ref serialize.

    @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:

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

    /** Constructors.

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

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

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

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

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

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

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

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

        nor movable, so this constructor is deleted.

        nor movable, so this constructor is deleted.

        @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 is

        omitted, the serializer will output only standard JSON.

        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

    /** Overload

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

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

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

        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 use for temporary storage when

        producing partial output.

        producing partial output.

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

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

        `buf`.

        `buf`.

        @param opts

        @param opts

    */

    */

    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 size = 0,

        serialize_options const& opts = {}) noexcept;

        serialize_options const& opts = {}) noexcept;

    /// Overload

    /// Overload

    serializer(serializer&&) = delete;

    serializer(serializer&&) = delete;

    /// @}

    /// @}

    /** Check if the serialization is complete.

    /** 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 characters in the

        serialized representation of the value have been read.

        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

        This function prepares the serializer to emit a new serialized JSON

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

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

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

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

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

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

        extends until it is no longer needed.

        extends until it is no longer needed.

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

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

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

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

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

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

        @param p A pointer to the element to serialize.

        @param p A pointer to the element to serialize.

        @{

        @{

    */

    */

    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

    /** Overload

        @param sv The characters representing a string.

        @param sv The characters representing a string.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(string_view sv) noexcept;

    reset(string_view sv) noexcept;

    /** Overload

    /** Overload

        @param np Represents a null value.

        @param np Represents a null value.

    */

    */

    BOOST_JSON_DECL

    BOOST_JSON_DECL

    void

    void

    reset(std::nullptr_t np) noexcept;

    reset(std::nullptr_t np) 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 provided buffer starting at

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

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

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

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

        may be required.

        may be required.

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

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

        characters belonging to the serialized value have been written to

        characters belonging to the serialized value have been written to

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

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

        @pre

        @pre

        @code

        @code

        done() == false

        done() == false

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

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

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

        @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

        @return A @ref string_view containing the characters written, which may

        be less than `size` or `N`.

        be less than `size` or `N`.

        @param dest A pointer to storage to write into.

        @param dest A pointer to storage to write into.

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

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

        pointed to by `dest`.

        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

    /** Overload

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

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

        @param dest

        @param dest

    */

    */

    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