GCC Code Coverage Report

Line	Branch	Exec	Source
1			//
2			// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3			//
4			// Distributed under the Boost Software License, Version 1.0. (See accompanying
5			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6			//
7			// Official repository: https://github.com/boostorg/json
8			//
9
10			#ifndef BOOST_JSON_SERIALIZER_HPP
11			#define BOOST_JSON_SERIALIZER_HPP
12
13			#include <boost/json/detail/config.hpp>
14			#include <boost/json/detail/format.hpp>
15			#include <boost/json/detail/stream.hpp>
16			#include <boost/json/detail/writer.hpp>
17			#include <boost/json/serialize_options.hpp>
18			#include <boost/json/value.hpp>
19
20			namespace boost {
21			namespace json {
22
23			/** A serializer for JSON.
24
25			This class traverses an instance of a library type and emits serialized
26			JSON text by filling in one or more caller-provided buffers. To use,
27			declare a variable and call @ref reset with a pointer to the variable you
28			want to serialize. Then call @ref read over and over until @ref done
29			returns `true`.
30
31			@par Example
32			This demonstrates how the serializer may be used to print a JSON value to
33			an output stream.
34
35			@code
36			void print( std::ostream& os, value const& jv)
37			{
38			serializer sr;
39			sr.reset( &jv );
40			while( ! sr.done() )
41			{
42			char buf[ 4000 ];
43			os << sr.read( buf );
44			}
45			}
46			@endcode
47
48			@par Thread Safety
49			The same instance may not be accessed concurrently.
50
51			@par Non-Standard JSON
52			The @ref serialize_options structure optionally provided upon construction
53			is used to enable non-standard JSON extensions. A default-constructed
54			`serialize_options` doesn't enable any extensions.
55
56			@see @ref serialize.
57			*/
58			class serializer
59			: detail::writer
60			{
61			using fn_t = bool (*)(writer&, detail::stream&);
62
63			fn_t fn0_ = nullptr;
64			fn_t fn1_ = nullptr;
65			bool done_ = false;
66
67			public:
68			/** Destructor
69
70			All temporary storage is deallocated.
71
72			@par Complexity
73			Constant
74
75			@par Exception Safety
76			No-throw guarantee.
77			*/
78			#ifdef BOOST_JSON_DOCS
79			BOOST_JSON_DECL
80			~serializer() noexcept;
81			#endif // BOOST_JSON_DOCS
82
83			/** Constructors.
84
85			The serializer is constructed with no value to serialize The value may
86			be set later by calling @ref reset. If serialization is attempted with
87			no value, the output is as if a null value is serialized.
88
89			Overload **(3)** is a move constructor. The type is neither copyable
90			nor movable, so this constructor is deleted.
91
92			@par Complexity
93			Constant.
94
95			@par Exception Safety
96			No-throw guarantee.
97
98			@param opts The options for the serializer. If this parameter is
99			omitted, the serializer will output only standard JSON.
100
101			@{
102			*/
103			BOOST_JSON_DECL
104			serializer( serialize_options const& opts = {} ) noexcept;
105
106			/** Overload
107
108			@param sp A pointer to the @ref boost::container::pmr::memory_resource
109			to use when producing partial output. Shared ownership of the memory
110			resource is retained until the serializer is destroyed.
111
112			@param buf An optional static buffer to use for temporary storage when
113			producing partial output.
114
115			@param size The number of bytes of valid memory pointed to by
116			`buf`.
117
118			@param opts
119			*/
120			BOOST_JSON_DECL
121			serializer(
122			storage_ptr sp,
123			unsigned char* buf = nullptr,
124			std::size_t size = 0,
125			serialize_options const& opts = {}) noexcept;
126
127			/// Overload
128			serializer(serializer&&) = delete;
129			/// @}
130
131			/** Check if the serialization is complete.
132
133			This function returns `true` when all of the characters in the
134			serialized representation of the value have been read.
135
136			@par Complexity
137			Constant.
138
139			@par Exception Safety
140			No-throw guarantee.
141			*/
142			bool
143		26922	done() const noexcept
144			{
145		26922	return done_;
146			}
147
148			/** Reset the serializer for a new element.
149
150			This function prepares the serializer to emit a new serialized JSON
151			representing its argument: `*p` **(1)**--**(5)**, `sv` **(6)**, or
152			`np` **(7)**. Ownership is not transferred. The caller is responsible
153			for ensuring that the lifetime of the object pointed to by the argument
154			extends until it is no longer needed.
155
156			Any memory internally allocated for previous uses of this `serializer`
157			object is preserved and re-used for the new output.
158
159			Overload **(5)** uses \<\<direct_conversion,direct serialization\>\>.
160
161			@param p A pointer to the element to serialize.
162
163			@{
164			*/
165			BOOST_JSON_DECL
166			void
167			reset(value const* p) noexcept;
168
169			BOOST_JSON_DECL
170			void
171			reset(array const* p) noexcept;
172
173			BOOST_JSON_DECL
174			void
175			reset(object const* p) noexcept;
176
177			BOOST_JSON_DECL
178			void
179			reset(string const* p) noexcept;
180
181			template<class T>
182			void
183			reset(T const* p) noexcept;
184
185			/** Overload
186
187			@param sv The characters representing a string.
188			*/
189			BOOST_JSON_DECL
190			void
191			reset(string_view sv) noexcept;
192
193			/** Overload
194
195			@param np Represents a null value.
196			*/
197			BOOST_JSON_DECL
198			void
199			reset(std::nullptr_t np) noexcept;
200			/// @}
201
202			/** Read the next buffer of serialized JSON.
203
204			This function attempts to fill the caller provided buffer starting at
205			`dest` with up to `size` characters of the serialized JSON that
206			represents the value. If the buffer is not large enough, multiple calls
207			may be required.
208
209			If serialization completes during this call; that is, that all of the
210			characters belonging to the serialized value have been written to
211			caller-provided buffers, the function @ref done will return `true`.
212
213			@pre
214			@code
215			done() == false
216			@endcode
217
218			@par Complexity
219			@li **(1)** linear in `size`.
220			@li **(2)** linear in `N`.
221
222			@par Exception Safety
223			Basic guarantee. Calls to `memory_resource::allocate` may throw.
224
225			@return A @ref string_view containing the characters written, which may
226			be less than `size` or `N`.
227
228			@param dest A pointer to storage to write into.
229
230			@param size The maximum number of characters to write to the memory
231			pointed to by `dest`.
232
233			@{
234			*/
235			BOOST_JSON_DECL
236			string_view
237			read(char* dest, std::size_t size);
238
239			/** Overload
240
241			@tparam N The size of the array `dest`.
242			@param dest
243			*/
244			template<std::size_t N>
245			string_view
246		18911	read(char(&dest)[N])
247			{
248		18911	return read(dest, N);
249			}
250			/// @}
251
252			#ifndef BOOST_JSON_DOCS
253			// Safety net for accidental buffer overflows
254			template<std::size_t N>
255			string_view
256			read(char(&dest)[N], std::size_t n)
257			{
258			// If this goes off, check your parameters
259			// closely, chances are you passed an array
260			// thinking it was a pointer.
261			BOOST_ASSERT(n <= N);
262			return read(dest, n);
263			}
264			#endif
265			};
266
267			} // namespace json
268			} // namespace boost
269
270			#include <boost/json/impl/serializer.hpp>
271
272			#endif
273