EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-07-09 08:14:14
0001 // 0002 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) 0003 // 0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying 0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 0006 // 0007 // Official repository: https://github.com/boostorg/json 0008 // 0009 0010 #ifndef BOOST_JSON_STREAM_PARSER_HPP 0011 #define BOOST_JSON_STREAM_PARSER_HPP 0012 0013 #include <boost/json/detail/config.hpp> 0014 #include <boost/json/basic_parser.hpp> 0015 #include <boost/json/parse_options.hpp> 0016 #include <boost/json/storage_ptr.hpp> 0017 #include <boost/json/value.hpp> 0018 #include <boost/json/detail/handler.hpp> 0019 #include <type_traits> 0020 #include <cstddef> 0021 0022 namespace boost { 0023 namespace json { 0024 0025 //---------------------------------------------------------- 0026 0027 /** A DOM parser for JSON text contained in multiple buffers. 0028 0029 This class is used to parse a JSON text contained in a 0030 series of one or more character buffers, into a 0031 @ref value container. It implements a 0032 <a href="https://en.wikipedia.org/wiki/Streaming_algorithm"> 0033 <em>streaming algorithm</em></a>, allowing these 0034 parsing strategies: 0035 0036 @li Parse a JSON file a piece at a time. 0037 0038 @li Parse incoming JSON text as it arrives, 0039 one buffer at a time. 0040 0041 @li Parse with bounded resource consumption 0042 per cycle. 0043 0044 @par Usage 0045 0046 To use the parser first construct it, then optionally 0047 call @ref reset to specify a @ref storage_ptr to use 0048 for the resulting @ref value. Then call @ref write 0049 one or more times to parse a single, complete JSON text. 0050 Call @ref done to determine if the parse has completed. 0051 To indicate there are no more buffers, call @ref finish. 0052 If the parse is successful, call @ref release to take 0053 ownership of the value: 0054 0055 @code 0056 stream_parser p; // construct a parser 0057 p.write( "[1,2" ); // parse some of a JSON text 0058 p.write( ",3,4]" ); // parse the rest of the JSON text 0059 assert( p.done() ); // we have a complete JSON text 0060 value jv = p.release(); // take ownership of the value 0061 @endcode 0062 0063 @par Extra Data 0064 0065 When the character buffer provided as input contains 0066 additional data that is not part of the complete 0067 JSON text, an error is returned. The @ref write_some 0068 function is an alternative which allows the parse 0069 to finish early, without consuming all the characters 0070 in the buffer. This allows parsing of a buffer 0071 containing multiple individual JSON texts or containing 0072 different protocol data: 0073 @code 0074 stream_parser p; // construct a parser 0075 std::size_t n; // number of characters used 0076 n = p.write_some( "[1,2" ); // parse some of a JSON text 0077 assert( n == 4 ); // all characters consumed 0078 n = p.write_some( ",3,4] null" ); // parse the remainder of the JSON text 0079 assert( n == 6 ); // only some characters consumed 0080 assert( p.done() ); // we have a complete JSON text 0081 value jv = p.release(); // take ownership of the value 0082 @endcode 0083 0084 @par Temporary Storage 0085 0086 The parser may dynamically allocate temporary 0087 storage as needed to accommodate the nesting level 0088 of the JSON text being parsed. Temporary storage is 0089 first obtained from an optional, caller-owned 0090 buffer specified upon construction. When that 0091 is exhausted, the next allocation uses the 0092 `boost::container::pmr::memory_resource` passed to the constructor; if 0093 no such argument is specified, the default memory 0094 resource is used. Temporary storage is freed only 0095 when the parser is destroyed; The performance of 0096 parsing multiple JSON texts may be improved by reusing 0097 the same parser instance. 0098 \n 0099 It is important to note that the `boost::container::pmr::memory_resource` 0100 supplied upon construction is used for temporary storage only, and not for 0101 allocating the elements which make up the parsed value. That other memory 0102 resource is optionally supplied in each call to @ref reset. 0103 0104 @par Duplicate Keys 0105 0106 If there are object elements with duplicate keys; 0107 that is, if multiple elements in an object have 0108 keys that compare equal, only the last equivalent 0109 element will be inserted. 0110 0111 @par Non-Standard JSON 0112 0113 The @ref parse_options structure optionally 0114 provided upon construction is used to customize 0115 some parameters of the parser, including which 0116 non-standard JSON extensions should be allowed. 0117 A default-constructed parse options allows only 0118 standard JSON. 0119 0120 @par Thread Safety 0121 0122 Distinct instances may be accessed concurrently. 0123 Non-const member functions of a shared instance 0124 may not be called concurrently with any other 0125 member functions of that instance. 0126 0127 @see 0128 @ref parse, 0129 @ref parser, 0130 @ref parse_options, 0131 */ 0132 class stream_parser 0133 { 0134 basic_parser<detail::handler> p_; 0135 0136 public: 0137 /// Copy constructor (deleted) 0138 stream_parser( 0139 stream_parser const&) = delete; 0140 0141 /// Copy assignment (deleted) 0142 stream_parser& operator=( 0143 stream_parser const&) = delete; 0144 0145 /** Destructor. 0146 0147 All dynamically allocated memory, including 0148 any incomplete parsing results, is freed. 0149 0150 @par Complexity 0151 Linear in the size of partial results 0152 0153 @par Exception Safety 0154 No-throw guarantee. 0155 */ 0156 ~stream_parser() = default; 0157 0158 /** Constructor. 0159 0160 This constructs a new parser which first uses 0161 the caller-owned storage pointed to by `buffer` 0162 for temporary storage, falling back to the memory 0163 resource `sp` if needed. The parser will use the 0164 specified parsing options. 0165 \n 0166 The parsed value will use the default memory 0167 resource for storage. To use a different resource, 0168 call @ref reset after construction. 0169 0170 @par Complexity 0171 Constant. 0172 0173 @par Exception Safety 0174 No-throw guarantee. 0175 0176 @param sp The memory resource to use for 0177 temporary storage after `buffer` is exhausted. 0178 0179 @param opt The parsing options to use. 0180 0181 @param buffer A pointer to valid memory of at least 0182 `size` bytes for the parser to use for temporary storage. 0183 Ownership is not transferred, the caller is responsible 0184 for ensuring the lifetime of the memory pointed to by 0185 `buffer` extends until the parser is destroyed. 0186 0187 @param size The number of valid bytes in `buffer`. 0188 */ 0189 BOOST_JSON_DECL 0190 stream_parser( 0191 storage_ptr sp, 0192 parse_options const& opt, 0193 unsigned char* buffer, 0194 std::size_t size) noexcept; 0195 0196 /** Constructor. 0197 0198 This constructs a new parser which uses the default 0199 memory resource for temporary storage, and accepts 0200 only strict JSON. 0201 \n 0202 The parsed value will use the default memory 0203 resource for storage. To use a different resource, 0204 call @ref reset after construction. 0205 0206 @par Complexity 0207 Constant. 0208 0209 @par Exception Safety 0210 No-throw guarantee. 0211 */ 0212 stream_parser() noexcept 0213 : stream_parser({}, {}) 0214 { 0215 } 0216 0217 /** Constructor. 0218 0219 This constructs a new parser which uses the 0220 specified memory resource for temporary storage, 0221 and is configured to use the specified parsing 0222 options. 0223 \n 0224 The parsed value will use the default memory 0225 resource for storage. To use a different resource, 0226 call @ref reset after construction. 0227 0228 @par Complexity 0229 Constant. 0230 0231 @par Exception Safety 0232 No-throw guarantee. 0233 0234 @param sp The memory resource to use for temporary storage. 0235 0236 @param opt The parsing options to use. 0237 */ 0238 BOOST_JSON_DECL 0239 stream_parser( 0240 storage_ptr sp, 0241 parse_options const& opt) noexcept; 0242 0243 /** Constructor. 0244 0245 This constructs a new parser which uses the 0246 specified memory resource for temporary storage, 0247 and accepts only strict JSON. 0248 \n 0249 The parsed value will use the default memory 0250 resource for storage. To use a different resource, 0251 call @ref reset after construction. 0252 0253 @par Complexity 0254 Constant. 0255 0256 @par Exception Safety 0257 No-throw guarantee. 0258 0259 @param sp The memory resource to use for temporary storage. 0260 */ 0261 explicit 0262 stream_parser(storage_ptr sp) noexcept 0263 : stream_parser(std::move(sp), {}) 0264 { 0265 } 0266 0267 /** Constructor. 0268 0269 This constructs a new parser which first uses the 0270 caller-owned storage `buffer` for temporary storage, 0271 falling back to the memory resource `sp` if needed. 0272 The parser will use the specified parsing options. 0273 \n 0274 The parsed value will use the default memory 0275 resource for storage. To use a different resource, 0276 call @ref reset after construction. 0277 0278 @par Complexity 0279 Constant. 0280 0281 @par Exception Safety 0282 No-throw guarantee. 0283 0284 @param sp The memory resource to use for 0285 temporary storage after `buffer` is exhausted. 0286 0287 @param opt The parsing options to use. 0288 0289 @param buffer A buffer for the parser to use for 0290 temporary storage. Ownership is not transferred, 0291 the caller is responsible for ensuring the lifetime 0292 of `buffer` extends until the parser is destroyed. 0293 */ 0294 template<std::size_t N> 0295 stream_parser( 0296 storage_ptr sp, 0297 parse_options const& opt, 0298 unsigned char(&buffer)[N]) noexcept 0299 : stream_parser(std::move(sp), 0300 opt, &buffer[0], N) 0301 { 0302 } 0303 0304 #if defined(__cpp_lib_byte) || defined(BOOST_JSON_DOCS) 0305 /** Constructor. 0306 0307 This constructs a new parser which first uses 0308 the caller-owned storage pointed to by `buffer` 0309 for temporary storage, falling back to the memory 0310 resource `sp` if needed. The parser will use the 0311 specified parsing options. 0312 \n 0313 The parsed value will use the default memory 0314 resource for storage. To use a different resource, 0315 call @ref reset after construction. 0316 0317 @par Complexity 0318 Constant. 0319 0320 @par Exception Safety 0321 No-throw guarantee. 0322 0323 @param sp The memory resource to use for 0324 temporary storage after `buffer` is exhausted. 0325 0326 @param opt The parsing options to use. 0327 0328 @param buffer A pointer to valid memory of at least 0329 `size` bytes for the parser to use for temporary storage. 0330 Ownership is not transferred, the caller is responsible 0331 for ensuring the lifetime of the memory pointed to by 0332 `buffer` extends until the parser is destroyed. 0333 0334 @param size The number of valid bytes in `buffer`. 0335 */ 0336 stream_parser( 0337 storage_ptr sp, 0338 parse_options const& opt, 0339 std::byte* buffer, 0340 std::size_t size) noexcept 0341 : stream_parser(sp, opt, reinterpret_cast< 0342 unsigned char*>(buffer), size) 0343 { 0344 } 0345 0346 /** Constructor. 0347 0348 This constructs a new parser which first uses the 0349 caller-owned storage `buffer` for temporary storage, 0350 falling back to the memory resource `sp` if needed. 0351 The parser will use the specified parsing options. 0352 \n 0353 The parsed value will use the default memory 0354 resource for storage. To use a different resource, 0355 call @ref reset after construction. 0356 0357 @par Complexity 0358 Constant. 0359 0360 @par Exception Safety 0361 No-throw guarantee. 0362 0363 @param sp The memory resource to use for 0364 temporary storage after `buffer` is exhausted. 0365 0366 @param opt The parsing options to use. 0367 0368 @param buffer A buffer for the parser to use for 0369 temporary storage. Ownership is not transferred, 0370 the caller is responsible for ensuring the lifetime 0371 of `buffer` extends until the parser is destroyed. 0372 */ 0373 template<std::size_t N> 0374 stream_parser( 0375 storage_ptr sp, 0376 parse_options const& opt, 0377 std::byte(&buffer)[N]) noexcept 0378 : stream_parser(std::move(sp), 0379 opt, &buffer[0], N) 0380 { 0381 } 0382 #endif 0383 0384 #ifndef BOOST_JSON_DOCS 0385 // Safety net for accidental buffer overflows 0386 template<std::size_t N> 0387 stream_parser( 0388 storage_ptr sp, 0389 parse_options const& opt, 0390 unsigned char(&buffer)[N], 0391 std::size_t n) noexcept 0392 : stream_parser(std::move(sp), 0393 opt, &buffer[0], n) 0394 { 0395 // If this goes off, check your parameters 0396 // closely, chances are you passed an array 0397 // thinking it was a pointer. 0398 BOOST_ASSERT(n <= N); 0399 } 0400 0401 #ifdef __cpp_lib_byte 0402 // Safety net for accidental buffer overflows 0403 template<std::size_t N> 0404 stream_parser( 0405 storage_ptr sp, 0406 parse_options const& opt, 0407 std::byte(&buffer)[N], std::size_t n) noexcept 0408 : stream_parser(std::move(sp), 0409 opt, &buffer[0], n) 0410 { 0411 // If this goes off, check your parameters 0412 // closely, chances are you passed an array 0413 // thinking it was a pointer. 0414 BOOST_ASSERT(n <= N); 0415 } 0416 #endif 0417 #endif 0418 0419 /** Reset the parser for a new JSON text. 0420 0421 This function is used to reset the parser to 0422 prepare it for parsing a new complete JSON text. 0423 Any previous partial results are destroyed. 0424 0425 @par Complexity 0426 Constant or linear in the size of any previous 0427 partial parsing results. 0428 0429 @par Exception Safety 0430 No-throw guarantee. 0431 0432 @param sp A pointer to the `boost::container::pmr::memory_resource` to 0433 use for the resulting @ref value. The parser will acquire shared 0434 ownership. 0435 */ 0436 BOOST_JSON_DECL 0437 void 0438 reset(storage_ptr sp = {}) noexcept; 0439 0440 /** Return true if a complete JSON text has been parsed. 0441 0442 This function returns `true` when all of these 0443 conditions are met: 0444 0445 @li A complete serialized JSON text has been 0446 presented to the parser, and 0447 0448 @li No error has occurred since the parser 0449 was constructed, or since the last call 0450 to @ref reset, 0451 0452 @par Complexity 0453 Constant. 0454 0455 @par Exception Safety 0456 No-throw guarantee. 0457 */ 0458 bool 0459 done() const noexcept 0460 { 0461 return p_.done(); 0462 } 0463 0464 /** Parse a buffer containing all or part of a complete JSON text. 0465 0466 This function parses JSON text contained in the 0467 specified character buffer. If parsing completes, 0468 any additional characters past the end of the 0469 complete JSON text are ignored. The function returns the 0470 actual number of characters parsed, which may be 0471 less than the size of the input. This allows parsing 0472 of a buffer containing multiple individual JSON texts or 0473 containing different protocol data. 0474 0475 @par Example 0476 @code 0477 stream_parser p; // construct a parser 0478 std::size_t n; // number of characters used 0479 n = p.write_some( "[1,2" ); // parse the first part of the JSON text 0480 assert( n == 4 ); // all characters consumed 0481 n = p.write_some( "3,4] null" ); // parse the rest of the JSON text 0482 assert( n == 5 ); // only some characters consumed 0483 value jv = p.release(); // take ownership of the value 0484 @endcode 0485 0486 @note 0487 0488 To indicate there are no more character buffers, 0489 such as when @ref done returns `false` after 0490 writing, call @ref finish. 0491 0492 @par Complexity 0493 Linear in `size`. 0494 0495 @par Exception Safety 0496 Basic guarantee. 0497 Calls to `memory_resource::allocate` may throw. 0498 Upon error or exception, subsequent calls will 0499 fail until @ref reset is called to parse a new JSON text. 0500 0501 @return The number of characters consumed from 0502 the buffer. 0503 0504 @param data A pointer to a buffer of `size` 0505 characters to parse. 0506 0507 @param size The number of characters pointed to 0508 by `data`. 0509 0510 @param ec Set to the error, if any occurred. 0511 */ 0512 /** @{ */ 0513 BOOST_JSON_DECL 0514 std::size_t 0515 write_some( 0516 char const* data, 0517 std::size_t size, 0518 system::error_code& ec); 0519 0520 BOOST_JSON_DECL 0521 std::size_t 0522 write_some( 0523 char const* data, 0524 std::size_t size, 0525 std::error_code& ec); 0526 /** @} */ 0527 0528 /** Parse a buffer containing all or part of a complete JSON text. 0529 0530 This function parses JSON text contained in the 0531 specified character buffer. If parsing completes, 0532 any additional characters past the end of the 0533 complete JSON text are ignored. The function returns the 0534 actual number of characters parsed, which may be 0535 less than the size of the input. This allows parsing 0536 of a buffer containing multiple individual JSON texts or 0537 containing different protocol data. 0538 0539 @par Example 0540 @code 0541 stream_parser p; // construct a parser 0542 std::size_t n; // number of characters used 0543 n = p.write_some( "[1,2" ); // parse the first part of the JSON text 0544 assert( n == 4 ); // all characters consumed 0545 n = p.write_some( "3,4] null" ); // parse the rest of the JSON text 0546 assert( n == 5 ); // only some characters consumed 0547 value jv = p.release(); // take ownership of the value 0548 @endcode 0549 0550 @note 0551 0552 To indicate there are no more character buffers, 0553 such as when @ref done returns `false` after 0554 writing, call @ref finish. 0555 0556 @par Complexity 0557 Linear in `size`. 0558 0559 @par Exception Safety 0560 Basic guarantee. 0561 Calls to `memory_resource::allocate` may throw. 0562 Upon error or exception, subsequent calls will 0563 fail until @ref reset is called to parse a new JSON text. 0564 0565 @return The number of characters consumed from 0566 the buffer. 0567 0568 @param data A pointer to a buffer of `size` 0569 characters to parse. 0570 0571 @param size The number of characters pointed to 0572 by `data`. 0573 0574 @throw `boost::system::system_error` Thrown on error. 0575 */ 0576 BOOST_JSON_DECL 0577 std::size_t 0578 write_some( 0579 char const* data, 0580 std::size_t size); 0581 0582 /** Parse a buffer containing all or part of a complete JSON text. 0583 0584 This function parses JSON text contained in the 0585 specified character buffer. If parsing completes, 0586 any additional characters past the end of the 0587 complete JSON text are ignored. The function returns the 0588 actual number of characters parsed, which may be 0589 less than the size of the input. This allows parsing 0590 of a buffer containing multiple individual JSON texts or 0591 containing different protocol data. 0592 0593 @par Example 0594 @code 0595 stream_parser p; // construct a parser 0596 std::size_t n; // number of characters used 0597 n = p.write_some( "[1,2" ); // parse the first part of the JSON text 0598 assert( n == 4 ); // all characters consumed 0599 n = p.write_some( "3,4] null" ); // parse the rest of the JSON text 0600 assert( n == 5 ); // only some characters consumed 0601 value jv = p.release(); // take ownership of the value 0602 @endcode 0603 0604 @note 0605 0606 To indicate there are no more character buffers, 0607 such as when @ref done returns `false` after 0608 writing, call @ref finish. 0609 0610 @par Complexity 0611 Linear in `size`. 0612 0613 @par Exception Safety 0614 Basic guarantee. 0615 Calls to `memory_resource::allocate` may throw. 0616 Upon error or exception, subsequent calls will 0617 fail until @ref reset is called to parse a new JSON text. 0618 0619 @return The number of characters consumed from 0620 the buffer. 0621 0622 @param s The character string to parse. 0623 0624 @param ec Set to the error, if any occurred. 0625 */ 0626 /** @{ */ 0627 std::size_t 0628 write_some( 0629 string_view s, 0630 system::error_code& ec) 0631 { 0632 return write_some( 0633 s.data(), s.size(), ec); 0634 } 0635 0636 std::size_t 0637 write_some( 0638 string_view s, 0639 std::error_code& ec) 0640 { 0641 return write_some( 0642 s.data(), s.size(), ec); 0643 } 0644 /** @} */ 0645 0646 /** Parse a buffer containing all or part of a complete JSON text. 0647 0648 This function parses JSON text contained in the 0649 specified character buffer. If parsing completes, 0650 any additional characters past the end of the 0651 complete JSON text are ignored. The function returns the 0652 actual number of characters parsed, which may be 0653 less than the size of the input. This allows parsing 0654 of a buffer containing multiple individual JSON texts or 0655 containing different protocol data. 0656 0657 @par Example 0658 @code 0659 stream_parser p; // construct a parser 0660 std::size_t n; // number of characters used 0661 n = p.write_some( "[1,2" ); // parse the first part of the JSON text 0662 assert( n == 4 ); // all characters consumed 0663 n = p.write_some( "3,4] null" ); // parse the rest of the JSON text 0664 assert( n == 5 ); // only some characters consumed 0665 value jv = p.release(); // take ownership of the value 0666 @endcode 0667 0668 @note 0669 0670 To indicate there are no more character buffers, 0671 such as when @ref done returns `false` after 0672 writing, call @ref finish. 0673 0674 @par Complexity 0675 Linear in `size`. 0676 0677 @par Exception Safety 0678 Basic guarantee. 0679 Calls to `memory_resource::allocate` may throw. 0680 Upon error or exception, subsequent calls will 0681 fail until @ref reset is called to parse a new JSON text. 0682 0683 @return The number of characters consumed from 0684 the buffer. 0685 0686 @param s The character string to parse. 0687 0688 @throw `boost::system::system_error` Thrown on error. 0689 */ 0690 std::size_t 0691 write_some( 0692 string_view s) 0693 { 0694 return write_some( 0695 s.data(), s.size()); 0696 } 0697 0698 /** Parse a buffer containing all or part of a complete JSON text. 0699 0700 This function parses a all or part of a JSON text 0701 contained in the specified character buffer. The 0702 entire buffer must be consumed; if there are 0703 additional characters past the end of the complete 0704 JSON text, the parse fails and an error is returned. 0705 0706 @par Example 0707 @code 0708 stream_parser p; // construct a parser 0709 std::size_t n; // number of characters used 0710 n = p.write( "[1,2" ); // parse some of the JSON text 0711 assert( n == 4 ); // all characters consumed 0712 n = p.write( "3,4]" ); // parse the rest of the JSON text 0713 assert( n == 4 ); // all characters consumed 0714 value jv = p.release(); // take ownership of the value 0715 @endcode 0716 0717 @note 0718 0719 To indicate there are no more character buffers, 0720 such as when @ref done returns `false` after 0721 writing, call @ref finish. 0722 0723 @par Complexity 0724 Linear in `size`. 0725 0726 @par Exception Safety 0727 Basic guarantee. 0728 Calls to `memory_resource::allocate` may throw. 0729 Upon error or exception, subsequent calls will 0730 fail until @ref reset is called to parse a new JSON text. 0731 0732 @return The number of characters consumed from 0733 the buffer. 0734 0735 @param data A pointer to a buffer of `size` 0736 characters to parse. 0737 0738 @param size The number of characters pointed to 0739 by `data`. 0740 0741 @param ec Set to the error, if any occurred. 0742 */ 0743 /** @{ */ 0744 BOOST_JSON_DECL 0745 std::size_t 0746 write( 0747 char const* data, 0748 std::size_t size, 0749 system::error_code& ec); 0750 0751 BOOST_JSON_DECL 0752 std::size_t 0753 write( 0754 char const* data, 0755 std::size_t size, 0756 std::error_code& ec); 0757 /** @} */ 0758 0759 /** Parse a buffer containing all or part of a complete JSON text. 0760 0761 This function parses a all or part of a JSON text 0762 contained in the specified character buffer. The 0763 entire buffer must be consumed; if there are 0764 additional characters past the end of the complete 0765 JSON text, the parse fails and an error is returned. 0766 0767 @par Example 0768 @code 0769 stream_parser p; // construct a parser 0770 std::size_t n; // number of characters used 0771 n = p.write( "[1,2" ); // parse some of the JSON text 0772 assert( n == 4 ); // all characters consumed 0773 n = p.write( "3,4]" ); // parse the rest of the JSON text 0774 assert( n == 4 ); // all characters consumed 0775 value jv = p.release(); // take ownership of the value 0776 @endcode 0777 0778 @note 0779 0780 To indicate there are no more character buffers, 0781 such as when @ref done returns `false` after 0782 writing, call @ref finish. 0783 0784 @par Complexity 0785 Linear in `size`. 0786 0787 @par Exception Safety 0788 Basic guarantee. 0789 Calls to `memory_resource::allocate` may throw. 0790 Upon error or exception, subsequent calls will 0791 fail until @ref reset is called to parse a new JSON text. 0792 0793 @return The number of characters consumed from 0794 the buffer. 0795 0796 @param data A pointer to a buffer of `size` 0797 characters to parse. 0798 0799 @param size The number of characters pointed to 0800 by `data`. 0801 0802 @throw `boost::system::system_error` Thrown on error. 0803 */ 0804 BOOST_JSON_DECL 0805 std::size_t 0806 write( 0807 char const* data, 0808 std::size_t size); 0809 0810 /** Parse a buffer containing all or part of a complete JSON text. 0811 0812 This function parses a all or part of a JSON text 0813 contained in the specified character buffer. The 0814 entire buffer must be consumed; if there are 0815 additional characters past the end of the complete 0816 JSON text, the parse fails and an error is returned. 0817 0818 @par Example 0819 @code 0820 stream_parser p; // construct a parser 0821 std::size_t n; // number of characters used 0822 n = p.write( "[1,2" ); // parse some of the JSON text 0823 assert( n == 4 ); // all characters consumed 0824 n = p.write( "3,4]" ); // parse the rest of the JSON text 0825 assert( n == 4 ); // all characters consumed 0826 value jv = p.release(); // take ownership of the value 0827 @endcode 0828 0829 @note 0830 0831 To indicate there are no more character buffers, 0832 such as when @ref done returns `false` after 0833 writing, call @ref finish. 0834 0835 @par Complexity 0836 Linear in `size`. 0837 0838 @par Exception Safety 0839 Basic guarantee. 0840 Calls to `memory_resource::allocate` may throw. 0841 Upon error or exception, subsequent calls will 0842 fail until @ref reset is called to parse a new JSON text. 0843 0844 @return The number of characters consumed from 0845 the buffer. 0846 0847 @param s The character string to parse. 0848 0849 @param ec Set to the error, if any occurred. 0850 */ 0851 /** @{ */ 0852 std::size_t 0853 write( 0854 string_view s, 0855 system::error_code& ec) 0856 { 0857 return write( 0858 s.data(), s.size(), ec); 0859 } 0860 0861 std::size_t 0862 write( 0863 string_view s, 0864 std::error_code& ec) 0865 { 0866 return write( 0867 s.data(), s.size(), ec); 0868 } 0869 /** @} */ 0870 0871 /** Parse a buffer containing all or part of a complete JSON text. 0872 0873 This function parses a all or part of a JSON text 0874 contained in the specified character buffer. The 0875 entire buffer must be consumed; if there are 0876 additional characters past the end of the complete 0877 JSON text, the parse fails and an error is returned. 0878 0879 @par Example 0880 @code 0881 stream_parser p; // construct a parser 0882 std::size_t n; // number of characters used 0883 n = p.write( "[1,2" ); // parse some of the JSON text 0884 assert( n == 4 ); // all characters consumed 0885 n = p.write( "3,4]" ); // parse the rest of the JSON text 0886 assert( n == 4 ); // all characters consumed 0887 value jv = p.release(); // take ownership of the value 0888 @endcode 0889 0890 @note 0891 0892 To indicate there are no more character buffers, 0893 such as when @ref done returns `false` after 0894 writing, call @ref finish. 0895 0896 @par Complexity 0897 Linear in `size`. 0898 0899 @par Exception Safety 0900 Basic guarantee. 0901 Calls to `memory_resource::allocate` may throw. 0902 Upon error or exception, subsequent calls will 0903 fail until @ref reset is called to parse a new JSON text. 0904 0905 @return The number of characters consumed from 0906 the buffer. 0907 0908 @param s The character string to parse. 0909 0910 @throw `boost::system::system_error` Thrown on error. 0911 */ 0912 std::size_t 0913 write( 0914 string_view s) 0915 { 0916 return write( 0917 s.data(), s.size()); 0918 } 0919 0920 /** Indicate the end of JSON input. 0921 0922 This function is used to indicate that there 0923 are no more character buffers in the current 0924 JSON text being parsed. If the resulting JSON text is 0925 incomplete, the error is set to indicate a 0926 parsing failure. 0927 0928 @par Example 0929 In the code below, @ref finish is called to 0930 indicate there are no more digits in the 0931 resulting number: 0932 @code 0933 stream_parser p; // construct a parser 0934 p.write( "3." ); // write the first part of the number 0935 p.write( "14" ); // write the second part of the number 0936 assert( ! p.done() ); // there could be more digits 0937 p.finish(); // indicate the end of the JSON input 0938 assert( p.done() ); // now we are finished 0939 value jv = p.release(); // take ownership of the value 0940 @endcode 0941 0942 @par Complexity 0943 Constant. 0944 0945 @par Exception Safety 0946 Basic guarantee. 0947 Calls to `memory_resource::allocate` may throw. 0948 Upon error or exception, subsequent calls will 0949 fail until @ref reset is called to parse a new JSON text. 0950 0951 @param ec Set to the error, if any occurred. 0952 */ 0953 /** @{ */ 0954 BOOST_JSON_DECL 0955 void 0956 finish(system::error_code& ec); 0957 0958 BOOST_JSON_DECL 0959 void 0960 finish(std::error_code& ec); 0961 /** @} */ 0962 0963 /** Indicate the end of JSON input. 0964 0965 This function is used to indicate that there 0966 are no more character buffers in the current 0967 JSON text being parsed. If the resulting JSON text is 0968 incomplete, the error is set to indicate a 0969 parsing failure. 0970 0971 @par Example 0972 In the code below, @ref finish is called to 0973 indicate there are no more digits in the 0974 resulting number: 0975 @code 0976 stream_parser p; // construct a parser 0977 p.write( "3." ); // write the first part of the number 0978 p.write( "14" ); // write the second part of the number 0979 assert( ! p.done() ); // there could be more digits 0980 p.finish(); // indicate the end of the JSON input 0981 assert( p.done() ); // now we are finished 0982 value jv = p.release(); // take ownership of the value 0983 @endcode 0984 0985 @par Complexity 0986 Constant. 0987 0988 @par Exception Safety 0989 Basic guarantee. 0990 Calls to `memory_resource::allocate` may throw. 0991 Upon error or exception, subsequent calls will 0992 fail until @ref reset is called to parse a new JSON text. 0993 0994 @throw `boost::system::system_error` Thrown on error. 0995 */ 0996 BOOST_JSON_DECL 0997 void 0998 finish(); 0999 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
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|