stream_parser.hpp

100.0% Lines (31/31) 85.7% Functions (12/14) -% Branches (0/0)

Covered Uncovered

stream_parser.hpp

31 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_STREAM_PARSER_HPP
11		#define BOOST_JSON_STREAM_PARSER_HPP
12
13		#include <boost/json/detail/config.hpp>
14		#include <boost/json/basic_parser.hpp>
15		#include <boost/json/parse_options.hpp>
16		#include <boost/json/storage_ptr.hpp>
17		#include <boost/json/value.hpp>
18		#include <boost/json/detail/handler.hpp>
19		#include <type_traits>
20		#include <cstddef>
21
22		namespace boost {
23		namespace json {
24
25		//----------------------------------------------------------
26
27		/** A DOM parser for JSON text contained in multiple buffers.
28
29		This class is used to parse a JSON text contained in a
30		series of one or more character buffers, into a
31		@ref value container. It implements a
32		<a href="https://en.wikipedia.org/wiki/Streaming_algorithm">
33		<em>streaming algorithm</em></a>, allowing these
34		parsing strategies:
35
36		@li Parse a JSON file a piece at a time.
37
38		@li Parse incoming JSON text as it arrives,
39		one buffer at a time.
40
41		@li Parse with bounded resource consumption
42		per cycle.
43
44		@par Usage
45
46		To use the parser first construct it, then optionally
47		call @ref reset to specify a @ref storage_ptr to use
48		for the resulting @ref value. Then call @ref write
49		one or more times to parse a single, complete JSON text.
50		Call @ref done to determine if the parse has completed.
51		To indicate there are no more buffers, call @ref finish.
52		If the parse is successful, call @ref release to take
53		ownership of the value:
54
55		@code
56		stream_parser p; // construct a parser
57		p.write( "[1,2" ); // parse some of a JSON text
58		p.write( ",3,4]" ); // parse the rest of the JSON text
59		assert( p.done() ); // we have a complete JSON text
60		value jv = p.release(); // take ownership of the value
61		@endcode
62
63		@par Extra Data
64
65		When the character buffer provided as input contains
66		additional data that is not part of the complete
67		JSON text, an error is returned. The @ref write_some
68		function is an alternative which allows the parse
69		to finish early, without consuming all the characters
70		in the buffer. This allows parsing of a buffer
71		containing multiple individual JSON texts or containing
72		different protocol data:
73		@code
74		stream_parser p; // construct a parser
75		std::size_t n; // number of characters used
76		n = p.write_some( "[1,2" ); // parse some of a JSON text
77		assert( n == 4 ); // all characters consumed
78		n = p.write_some( ",3,4] null" ); // parse the remainder of the JSON text
79		assert( n == 6 ); // only some characters consumed
80		assert( p.done() ); // we have a complete JSON text
81		value jv = p.release(); // take ownership of the value
82		@endcode
83
84		@par Temporary Storage
85
86		The parser may dynamically allocate temporary
87		storage as needed to accommodate the nesting level
88		of the JSON text being parsed. Temporary storage is
89		first obtained from an optional, caller-owned
90		buffer specified upon construction. When that
91		is exhausted, the next allocation uses the
92		`boost::container::pmr::memory_resource` passed to the constructor; if
93		no such argument is specified, the default memory
94		resource is used. Temporary storage is freed only
95		when the parser is destroyed; The performance of
96		parsing multiple JSON texts may be improved by reusing
97		the same parser instance.
98		\n
99		It is important to note that the `boost::container::pmr::memory_resource`
100		supplied upon construction is used for temporary storage only, and not for
101		allocating the elements which make up the parsed value. That other memory
102		resource is optionally supplied in each call to @ref reset.
103
104		@par Duplicate Keys
105
106		If there are object elements with duplicate keys;
107		that is, if multiple elements in an object have
108		keys that compare equal, only the last equivalent
109		element will be inserted.
110
111		@par Non-Standard JSON
112
113		The @ref parse_options structure optionally
114		provided upon construction is used to customize
115		some parameters of the parser, including which
116		non-standard JSON extensions should be allowed.
117		A default-constructed parse options allows only
118		standard JSON.
119
120		@par Thread Safety
121
122		Distinct instances may be accessed concurrently.
123		Non-const member functions of a shared instance
124		may not be called concurrently with any other
125		member functions of that instance.
126
127		@see
128		@ref parse,
129		@ref parser,
130		@ref parse_options,
131		*/
132		class stream_parser
133		{
134		basic_parser<detail::handler> p_;
135
136		public:
137		/// Copy constructor (deleted)
138		stream_parser(
139		stream_parser const&) = delete;
140
141		/// Copy assignment (deleted)
142		stream_parser& operator=(
143		stream_parser const&) = delete;
144
145		/** Destructor.
146
147		All dynamically allocated memory, including
148		any incomplete parsing results, is freed.
149
150		@par Complexity
151		Linear in the size of partial results
152
153		@par Exception Safety
154		No-throw guarantee.
155		*/
156	75326	~stream_parser() = default;
157
158		/** Constructor.
159
160		This constructs a new parser which first uses
161		the caller-owned storage pointed to by `buffer`
162		for temporary storage, falling back to the memory
163		resource `sp` if needed. The parser will use the
164		specified parsing options.
165		\n
166		The parsed value will use the default memory
167		resource for storage. To use a different resource,
168		call @ref reset after construction.
169
170		@par Complexity
171		Constant.
172
173		@par Exception Safety
174		No-throw guarantee.
175
176		@param sp The memory resource to use for
177		temporary storage after `buffer` is exhausted.
178
179		@param opt The parsing options to use.
180
181		@param buffer A pointer to valid memory of at least
182		`size` bytes for the parser to use for temporary storage.
183		Ownership is not transferred, the caller is responsible
184		for ensuring the lifetime of the memory pointed to by
185		`buffer` extends until the parser is destroyed.
186
187		@param size The number of valid bytes in `buffer`.
188		*/
189		BOOST_JSON_DECL
190		stream_parser(
191		storage_ptr sp,
192		parse_options const& opt,
193		unsigned char* buffer,
194		std::size_t size) noexcept;
195
196		/** Constructor.
197
198		This constructs a new parser which uses the default
199		memory resource for temporary storage, and accepts
200		only strict JSON.
201		\n
202		The parsed value will use the default memory
203		resource for storage. To use a different resource,
204		call @ref reset after construction.
205
206		@par Complexity
207		Constant.
208
209		@par Exception Safety
210		No-throw guarantee.
211		*/
212	187	stream_parser() noexcept
213	187	: stream_parser({}, {})
214		{
215	187	}
216
217		/** Constructor.
218
219		This constructs a new parser which uses the
220		specified memory resource for temporary storage,
221		and is configured to use the specified parsing
222		options.
223		\n
224		The parsed value will use the default memory
225		resource for storage. To use a different resource,
226		call @ref reset after construction.
227
228		@par Complexity
229		Constant.
230
231		@par Exception Safety
232		No-throw guarantee.
233
234		@param sp The memory resource to use for temporary storage.
235
236		@param opt The parsing options to use.
237		*/
238		BOOST_JSON_DECL
239		stream_parser(
240		storage_ptr sp,
241		parse_options const& opt) noexcept;
242
243		/** Constructor.
244
245		This constructs a new parser which uses the
246		specified memory resource for temporary storage,
247		and accepts only strict JSON.
248		\n
249		The parsed value will use the default memory
250		resource for storage. To use a different resource,
251		call @ref reset after construction.
252
253		@par Complexity
254		Constant.
255
256		@par Exception Safety
257		No-throw guarantee.
258
259		@param sp The memory resource to use for temporary storage.
260		*/
261		explicit
262	2	stream_parser(storage_ptr sp) noexcept
263	2	: stream_parser(std::move(sp), {})
264		{
265	2	}
266
267		/** Constructor.
268
269		This constructs a new parser which first uses the
270		caller-owned storage `buffer` for temporary storage,
271		falling back to the memory resource `sp` if needed.
272		The parser will use the specified parsing options.
273		\n
274		The parsed value will use the default memory
275		resource for storage. To use a different resource,
276		call @ref reset after construction.
277
278		@par Complexity
279		Constant.
280
281		@par Exception Safety
282		No-throw guarantee.
283
284		@param sp The memory resource to use for
285		temporary storage after `buffer` is exhausted.
286
287		@param opt The parsing options to use.
288
289		@param buffer A buffer for the parser to use for
290		temporary storage. Ownership is not transferred,
291		the caller is responsible for ensuring the lifetime
292		of `buffer` extends until the parser is destroyed.
293		*/
294		template<std::size_t N>
295	20	stream_parser(
296		storage_ptr sp,
297		parse_options const& opt,
298		unsigned char(&buffer)[N]) noexcept
299	20	: stream_parser(std::move(sp),
300	20	opt, &buffer[0], N)
301		{
302	20	}
303
304		#if defined(__cpp_lib_byte) || defined(BOOST_JSON_DOCS)
305		/** Constructor.
306
307		This constructs a new parser which first uses
308		the caller-owned storage pointed to by `buffer`
309		for temporary storage, falling back to the memory
310		resource `sp` if needed. The parser will use the
311		specified parsing options.
312		\n
313		The parsed value will use the default memory
314		resource for storage. To use a different resource,
315		call @ref reset after construction.
316
317		@par Complexity
318		Constant.
319
320		@par Exception Safety
321		No-throw guarantee.
322
323		@param sp The memory resource to use for
324		temporary storage after `buffer` is exhausted.
325
326		@param opt The parsing options to use.
327
328		@param buffer A pointer to valid memory of at least
329		`size` bytes for the parser to use for temporary storage.
330		Ownership is not transferred, the caller is responsible
331		for ensuring the lifetime of the memory pointed to by
332		`buffer` extends until the parser is destroyed.
333
334		@param size The number of valid bytes in `buffer`.
335		*/
336		stream_parser(
337		storage_ptr sp,
338		parse_options const& opt,
339		std::byte* buffer,
340		std::size_t size) noexcept
341		: stream_parser(sp, opt, reinterpret_cast<
342		unsigned char*>(buffer), size)
343		{
344		}
345
346		/** Constructor.
347
348		This constructs a new parser which first uses the
349		caller-owned storage `buffer` for temporary storage,
350		falling back to the memory resource `sp` if needed.
351		The parser will use the specified parsing options.
352		\n
353		The parsed value will use the default memory
354		resource for storage. To use a different resource,
355		call @ref reset after construction.
356
357		@par Complexity
358		Constant.
359
360		@par Exception Safety
361		No-throw guarantee.
362
363		@param sp The memory resource to use for
364		temporary storage after `buffer` is exhausted.
365
366		@param opt The parsing options to use.
367
368		@param buffer A buffer for the parser to use for
369		temporary storage. Ownership is not transferred,
370		the caller is responsible for ensuring the lifetime
371		of `buffer` extends until the parser is destroyed.
372		*/
373		template<std::size_t N>
374		stream_parser(
375		storage_ptr sp,
376		parse_options const& opt,
377		std::byte(&buffer)[N]) noexcept
378		: stream_parser(std::move(sp),
379		opt, &buffer[0], N)
380		{
381		}
382		#endif
383
384		#ifndef BOOST_JSON_DOCS
385		// Safety net for accidental buffer overflows
386		template<std::size_t N>
387		stream_parser(
388		storage_ptr sp,
389		parse_options const& opt,
390		unsigned char(&buffer)[N],
391		std::size_t n) noexcept
392		: stream_parser(std::move(sp),
393		opt, &buffer[0], n)
394		{
395		// If this goes off, check your parameters
396		// closely, chances are you passed an array
397		// thinking it was a pointer.
398		BOOST_ASSERT(n <= N);
399		}
400
401		#ifdef __cpp_lib_byte
402		// Safety net for accidental buffer overflows
403		template<std::size_t N>
404		stream_parser(
405		storage_ptr sp,
406		parse_options const& opt,
407		std::byte(&buffer)[N], std::size_t n) noexcept
408		: stream_parser(std::move(sp),
409		opt, &buffer[0], n)
410		{
411		// If this goes off, check your parameters
412		// closely, chances are you passed an array
413		// thinking it was a pointer.
414		BOOST_ASSERT(n <= N);
415		}
416		#endif
417		#endif
418
419		/** Reset the parser for a new JSON text.
420
421		This function is used to reset the parser to
422		prepare it for parsing a new complete JSON text.
423		Any previous partial results are destroyed.
424
425		@par Complexity
426		Constant or linear in the size of any previous
427		partial parsing results.
428
429		@par Exception Safety
430		No-throw guarantee.
431
432		@param sp A pointer to the `boost::container::pmr::memory_resource` to
433		use for the resulting @ref value. The parser will acquire shared
434		ownership.
435		*/
436		BOOST_JSON_DECL
437		void
438		reset(storage_ptr sp = {}) noexcept;
439
440		/** Return true if a complete JSON text has been parsed.
441
442		This function returns `true` when all of these
443		conditions are met:
444
445		@li A complete serialized JSON text has been
446		presented to the parser, and
447
448		@li No error has occurred since the parser
449		was constructed, or since the last call
450		to @ref reset,
451
452		@par Complexity
453		Constant.
454
455		@par Exception Safety
456		No-throw guarantee.
457		*/
458		bool
459	30	done() const noexcept
460		{
461	30	return p_.done();
462		}
463
464		/** Parse a buffer containing all or part of a complete JSON text.
465
466		This function parses JSON text contained in the
467		specified character buffer. If parsing completes,
468		any additional characters past the end of the
469		complete JSON text are ignored. The function returns the
470		actual number of characters parsed, which may be
471		less than the size of the input. This allows parsing
472		of a buffer containing multiple individual JSON texts or
473		containing different protocol data.
474
475		@par Example
476		@code
477		stream_parser p; // construct a parser
478		std::size_t n; // number of characters used
479		n = p.write_some( "[1,2" ); // parse the first part of the JSON text
480		assert( n == 4 ); // all characters consumed
481		n = p.write_some( "3,4] null" ); // parse the rest of the JSON text
482		assert( n == 5 ); // only some characters consumed
483		value jv = p.release(); // take ownership of the value
484		@endcode
485
486		@note
487
488		To indicate there are no more character buffers,
489		such as when @ref done returns `false` after
490		writing, call @ref finish.
491
492		@par Complexity
493		Linear in `size`.
494
495		@par Exception Safety
496		Basic guarantee.
497		Calls to `memory_resource::allocate` may throw.
498		Upon error or exception, subsequent calls will
499		fail until @ref reset is called to parse a new JSON text.
500
501		@return The number of characters consumed from
502		the buffer.
503
504		@param data A pointer to a buffer of `size`
505		characters to parse.
506
507		@param size The number of characters pointed to
508		by `data`.
509
510		@param ec Set to the error, if any occurred.
511		*/
512		/** @{ */
513		BOOST_JSON_DECL
514		std::size_t
515		write_some(
516		char const* data,
517		std::size_t size,
518		system::error_code& ec);
519
520		BOOST_JSON_DECL
521		std::size_t
522		write_some(
523		char const* data,
524		std::size_t size,
525		std::error_code& ec);
526		/** @} */
527
528		/** Parse a buffer containing all or part of a complete JSON text.
529
530		This function parses JSON text contained in the
531		specified character buffer. If parsing completes,
532		any additional characters past the end of the
533		complete JSON text are ignored. The function returns the
534		actual number of characters parsed, which may be
535		less than the size of the input. This allows parsing
536		of a buffer containing multiple individual JSON texts or
537		containing different protocol data.
538
539		@par Example
540		@code
541		stream_parser p; // construct a parser
542		std::size_t n; // number of characters used
543		n = p.write_some( "[1,2" ); // parse the first part of the JSON text
544		assert( n == 4 ); // all characters consumed
545		n = p.write_some( "3,4] null" ); // parse the rest of the JSON text
546		assert( n == 5 ); // only some characters consumed
547		value jv = p.release(); // take ownership of the value
548		@endcode
549
550		@note
551
552		To indicate there are no more character buffers,
553		such as when @ref done returns `false` after
554		writing, call @ref finish.
555
556		@par Complexity
557		Linear in `size`.
558
559		@par Exception Safety
560		Basic guarantee.
561		Calls to `memory_resource::allocate` may throw.
562		Upon error or exception, subsequent calls will
563		fail until @ref reset is called to parse a new JSON text.
564
565		@return The number of characters consumed from
566		the buffer.
567
568		@param data A pointer to a buffer of `size`
569		characters to parse.
570
571		@param size The number of characters pointed to
572		by `data`.
573
574		@throw `boost::system::system_error` Thrown on error.
575		*/
576		BOOST_JSON_DECL
577		std::size_t
578		write_some(
579		char const* data,
580		std::size_t size);
581
582		/** Parse a buffer containing all or part of a complete JSON text.
583
584		This function parses JSON text contained in the
585		specified character buffer. If parsing completes,
586		any additional characters past the end of the
587		complete JSON text are ignored. The function returns the
588		actual number of characters parsed, which may be
589		less than the size of the input. This allows parsing
590		of a buffer containing multiple individual JSON texts or
591		containing different protocol data.
592
593		@par Example
594		@code
595		stream_parser p; // construct a parser
596		std::size_t n; // number of characters used
597		n = p.write_some( "[1,2" ); // parse the first part of the JSON text
598		assert( n == 4 ); // all characters consumed
599		n = p.write_some( "3,4] null" ); // parse the rest of the JSON text
600		assert( n == 5 ); // only some characters consumed
601		value jv = p.release(); // take ownership of the value
602		@endcode
603
604		@note
605
606		To indicate there are no more character buffers,
607		such as when @ref done returns `false` after
608		writing, call @ref finish.
609
610		@par Complexity
611		Linear in `size`.
612
613		@par Exception Safety
614		Basic guarantee.
615		Calls to `memory_resource::allocate` may throw.
616		Upon error or exception, subsequent calls will
617		fail until @ref reset is called to parse a new JSON text.
618
619		@return The number of characters consumed from
620		the buffer.
621
622		@param s The character string to parse.
623
624		@param ec Set to the error, if any occurred.
625		*/
626		/** @{ */
627		std::size_t
628	2	write_some(
629		string_view s,
630		system::error_code& ec)
631		{
632	2	return write_some(
633	2	s.data(), s.size(), ec);
634		}
635
636		std::size_t
637	2	write_some(
638		string_view s,
639		std::error_code& ec)
640		{
641	2	return write_some(
642	2	s.data(), s.size(), ec);
643		}
644		/** @} */
645
646		/** Parse a buffer containing all or part of a complete JSON text.
647
648		This function parses JSON text contained in the
649		specified character buffer. If parsing completes,
650		any additional characters past the end of the
651		complete JSON text are ignored. The function returns the
652		actual number of characters parsed, which may be
653		less than the size of the input. This allows parsing
654		of a buffer containing multiple individual JSON texts or
655		containing different protocol data.
656
657		@par Example
658		@code
659		stream_parser p; // construct a parser
660		std::size_t n; // number of characters used
661		n = p.write_some( "[1,2" ); // parse the first part of the JSON text
662		assert( n == 4 ); // all characters consumed
663		n = p.write_some( "3,4] null" ); // parse the rest of the JSON text
664		assert( n == 5 ); // only some characters consumed
665		value jv = p.release(); // take ownership of the value
666		@endcode
667
668		@note
669
670		To indicate there are no more character buffers,
671		such as when @ref done returns `false` after
672		writing, call @ref finish.
673
674		@par Complexity
675		Linear in `size`.
676
677		@par Exception Safety
678		Basic guarantee.
679		Calls to `memory_resource::allocate` may throw.
680		Upon error or exception, subsequent calls will
681		fail until @ref reset is called to parse a new JSON text.
682
683		@return The number of characters consumed from
684		the buffer.
685
686		@param s The character string to parse.
687
688		@throw `boost::system::system_error` Thrown on error.
689		*/
690		std::size_t
691	4	write_some(
692		string_view s)
693		{
694	4	return write_some(
695	3	s.data(), s.size());
696		}
697
698		/** Parse a buffer containing all or part of a complete JSON text.
699
700		This function parses a all or part of a JSON text
701		contained in the specified character buffer. The
702		entire buffer must be consumed; if there are
703		additional characters past the end of the complete
704		JSON text, the parse fails and an error is returned.
705
706		@par Example
707		@code
708		stream_parser p; // construct a parser
709		std::size_t n; // number of characters used
710		n = p.write( "[1,2" ); // parse some of the JSON text
711		assert( n == 4 ); // all characters consumed
712		n = p.write( "3,4]" ); // parse the rest of the JSON text
713		assert( n == 4 ); // all characters consumed
714		value jv = p.release(); // take ownership of the value
715		@endcode
716
717		@note
718
719		To indicate there are no more character buffers,
720		such as when @ref done returns `false` after
721		writing, call @ref finish.
722
723		@par Complexity
724		Linear in `size`.
725
726		@par Exception Safety
727		Basic guarantee.
728		Calls to `memory_resource::allocate` may throw.
729		Upon error or exception, subsequent calls will
730		fail until @ref reset is called to parse a new JSON text.
731
732		@return The number of characters consumed from
733		the buffer.
734
735		@param data A pointer to a buffer of `size`
736		characters to parse.
737
738		@param size The number of characters pointed to
739		by `data`.
740
741		@param ec Set to the error, if any occurred.
742		*/
743		/** @{ */
744		BOOST_JSON_DECL
745		std::size_t
746		write(
747		char const* data,
748		std::size_t size,
749		system::error_code& ec);
750
751		BOOST_JSON_DECL
752		std::size_t
753		write(
754		char const* data,
755		std::size_t size,
756		std::error_code& ec);
757		/** @} */
758
759		/** Parse a buffer containing all or part of a complete JSON text.
760
761		This function parses a all or part of a JSON text
762		contained in the specified character buffer. The
763		entire buffer must be consumed; if there are
764		additional characters past the end of the complete
765		JSON text, the parse fails and an error is returned.
766
767		@par Example
768		@code
769		stream_parser p; // construct a parser
770		std::size_t n; // number of characters used
771		n = p.write( "[1,2" ); // parse some of the JSON text
772		assert( n == 4 ); // all characters consumed
773		n = p.write( "3,4]" ); // parse the rest of the JSON text
774		assert( n == 4 ); // all characters consumed
775		value jv = p.release(); // take ownership of the value
776		@endcode
777
778		@note
779
780		To indicate there are no more character buffers,
781		such as when @ref done returns `false` after
782		writing, call @ref finish.
783
784		@par Complexity
785		Linear in `size`.
786
787		@par Exception Safety
788		Basic guarantee.
789		Calls to `memory_resource::allocate` may throw.
790		Upon error or exception, subsequent calls will
791		fail until @ref reset is called to parse a new JSON text.
792
793		@return The number of characters consumed from
794		the buffer.
795
796		@param data A pointer to a buffer of `size`
797		characters to parse.
798
799		@param size The number of characters pointed to
800		by `data`.
801
802		@throw `boost::system::system_error` Thrown on error.
803		*/
804		BOOST_JSON_DECL
805		std::size_t
806		write(
807		char const* data,
808		std::size_t size);
809
810		/** Parse a buffer containing all or part of a complete JSON text.
811
812		This function parses a all or part of a JSON text
813		contained in the specified character buffer. The
814		entire buffer must be consumed; if there are
815		additional characters past the end of the complete
816		JSON text, the parse fails and an error is returned.
817
818		@par Example
819		@code
820		stream_parser p; // construct a parser
821		std::size_t n; // number of characters used
822		n = p.write( "[1,2" ); // parse some of the JSON text
823		assert( n == 4 ); // all characters consumed
824		n = p.write( "3,4]" ); // parse the rest of the JSON text
825		assert( n == 4 ); // all characters consumed
826		value jv = p.release(); // take ownership of the value
827		@endcode
828
829		@note
830
831		To indicate there are no more character buffers,
832		such as when @ref done returns `false` after
833		writing, call @ref finish.
834
835		@par Complexity
836		Linear in `size`.
837
838		@par Exception Safety
839		Basic guarantee.
840		Calls to `memory_resource::allocate` may throw.
841		Upon error or exception, subsequent calls will
842		fail until @ref reset is called to parse a new JSON text.
843
844		@return The number of characters consumed from
845		the buffer.
846
847		@param s The character string to parse.
848
849		@param ec Set to the error, if any occurred.
850		*/
851		/** @{ */
852		std::size_t
853	3	write(
854		string_view s,
855		system::error_code& ec)
856		{
857	3	return write(
858	3	s.data(), s.size(), ec);
859		}
860
861		std::size_t
862	2	write(
863		string_view s,
864		std::error_code& ec)
865		{
866	2	return write(
867	2	s.data(), s.size(), ec);
868		}
869		/** @} */
870
871		/** Parse a buffer containing all or part of a complete JSON text.
872
873		This function parses a all or part of a JSON text
874		contained in the specified character buffer. The
875		entire buffer must be consumed; if there are
876		additional characters past the end of the complete
877		JSON text, the parse fails and an error is returned.
878
879		@par Example
880		@code
881		stream_parser p; // construct a parser
882		std::size_t n; // number of characters used
883		n = p.write( "[1,2" ); // parse some of the JSON text
884		assert( n == 4 ); // all characters consumed
885		n = p.write( "3,4]" ); // parse the rest of the JSON text
886		assert( n == 4 ); // all characters consumed
887		value jv = p.release(); // take ownership of the value
888		@endcode
889
890		@note
891
892		To indicate there are no more character buffers,
893		such as when @ref done returns `false` after
894		writing, call @ref finish.
895
896		@par Complexity
897		Linear in `size`.
898
899		@par Exception Safety
900		Basic guarantee.
901		Calls to `memory_resource::allocate` may throw.
902		Upon error or exception, subsequent calls will
903		fail until @ref reset is called to parse a new JSON text.
904
905		@return The number of characters consumed from
906		the buffer.
907
908		@param s The character string to parse.
909
910		@throw `boost::system::system_error` Thrown on error.
911		*/
912		std::size_t
913	9	write(
914		string_view s)
915		{
916	9	return write(
917	8	s.data(), s.size());
918		}
919
920		/** Indicate the end of JSON input.
921
922		This function is used to indicate that there
923		are no more character buffers in the current
924		JSON text being parsed. If the resulting JSON text is
925		incomplete, the error is set to indicate a
926		parsing failure.
927
928		@par Example
929		In the code below, @ref finish is called to
930		indicate there are no more digits in the
931		resulting number:
932		@code
933		stream_parser p; // construct a parser
934		p.write( "3." ); // write the first part of the number
935		p.write( "14" ); // write the second part of the number
936		assert( ! p.done() ); // there could be more digits
937		p.finish(); // indicate the end of the JSON input
938		assert( p.done() ); // now we are finished
939		value jv = p.release(); // take ownership of the value
940		@endcode
941
942		@par Complexity
943		Constant.
944
945		@par Exception Safety
946		Basic guarantee.
947		Calls to `memory_resource::allocate` may throw.
948		Upon error or exception, subsequent calls will
949		fail until @ref reset is called to parse a new JSON text.
950
951		@param ec Set to the error, if any occurred.
952		*/
953		/** @{ */
954		BOOST_JSON_DECL
955		void
956		finish(system::error_code& ec);
957
958		BOOST_JSON_DECL
959		void
960		finish(std::error_code& ec);
961		/** @} */
962
963		/** Indicate the end of JSON input.
964
965		This function is used to indicate that there
966		are no more character buffers in the current
967		JSON text being parsed. If the resulting JSON text is
968		incomplete, the error is set to indicate a
969		parsing failure.
970
971		@par Example
972		In the code below, @ref finish is called to
973		indicate there are no more digits in the
974		resulting number:
975		@code
976		stream_parser p; // construct a parser
977		p.write( "3." ); // write the first part of the number
978		p.write( "14" ); // write the second part of the number
979		assert( ! p.done() ); // there could be more digits
980		p.finish(); // indicate the end of the JSON input
981		assert( p.done() ); // now we are finished
982		value jv = p.release(); // take ownership of the value
983		@endcode
984
985		@par Complexity
986		Constant.
987
988		@par Exception Safety
989		Basic guarantee.
990		Calls to `memory_resource::allocate` may throw.
991		Upon error or exception, subsequent calls will
992		fail until @ref reset is called to parse a new JSON text.
993
994		@throw `boost::system::system_error` Thrown on error.
995		*/
996		BOOST_JSON_DECL
997		void
998		finish();
999
1000		/** Return the parsed JSON as a @ref value.
1001
1002		This returns the parsed value, or throws
1003		an exception if the parsing is incomplete or
1004		failed. It is necessary to call @ref reset
1005		after calling this function in order to parse
1006		another JSON text.
1007
1008		@par Effects
1009		@code
1010		if( ! this->done() )
1011		this->finish();
1012		@endcode
1013		@note
1014
1015		@par Complexity
1016		Constant.
1017
1018		@return The parsed value. Ownership of this
1019		value is transferred to the caller.
1020
1021		@throw `boost::system::system_error` Thrown on failure.
1022		*/
1023		BOOST_JSON_DECL
1024		value
1025		release();
1026		};
1027
1028		} // namespace json
1029		} // namespace boost
1030
1031		#endif
1032