Line data 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
|
