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