serializer.hpp

100.0% Lines (4/4) 50.0% Functions (2/4) -% Branches (0/0)

Covered Uncovered

serializer.hpp

4 covered 0 uncovered

Line	Hits	Source Code
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