1 // 2 // read_until.hpp 3 // ~~~~~~~~~~~~~~ 4 // 5 // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) 6 // 7 // Distributed under the Boost Software License, Version 1.0. (See accompanying 8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 9 // 10 11 #ifndef BOOST_ASIO_READ_UNTIL_HPP 12 #define BOOST_ASIO_READ_UNTIL_HPP 13 14 #if defined(_MSC_VER) && (_MSC_VER >= 1200) 15 # pragma once 16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) 17 18 #include <boost/asio/detail/config.hpp> 19 20 #if !defined(BOOST_ASIO_NO_IOSTREAM) 21 22 #include <cstddef> 23 #include <string> 24 #include <boost/asio/async_result.hpp> 25 #include <boost/asio/basic_streambuf.hpp> 26 #include <boost/asio/detail/regex_fwd.hpp> 27 #include <boost/asio/detail/type_traits.hpp> 28 #include <boost/asio/error.hpp> 29 30 #include <boost/asio/detail/push_options.hpp> 31 32 namespace boost { 33 namespace asio { 34 35 namespace detail 36 { 37 char (&has_result_type_helper(...))[2]; 38 39 template <typename T> 40 char has_result_type_helper(T*, typename T::result_type* = 0); 41 42 template <typename T> 43 struct has_result_type 44 { 45 enum { value = (sizeof((has_result_type_helper)((T*)(0))) == 1) }; 46 }; 47 } // namespace detail 48 49 /// Type trait used to determine whether a type can be used as a match condition 50 /// function with read_until and async_read_until. 51 template <typename T> 52 struct is_match_condition 53 { 54 #if defined(GENERATING_DOCUMENTATION) 55 /// The value member is true if the type may be used as a match condition. 56 static const bool value; 57 #else 58 enum 59 { 60 value = boost::asio::is_function< 61 typename boost::asio::remove_pointer<T>::type>::value 62 || detail::has_result_type<T>::value 63 }; 64 #endif 65 }; 66 67 /** 68 * @defgroup read_until boost::asio::read_until 69 * 70 * @brief Read data into a streambuf until it contains a delimiter, matches a 71 * regular expression, or a function object indicates a match. 72 */ 73 /*@{*/ 74 75 /// Read data into a streambuf until it contains a specified delimiter. 76 /** 77 * This function is used to read data into the specified streambuf until the 78 * streambuf's get area contains the specified delimiter. The call will block 79 * until one of the following conditions is true: 80 * 81 * @li The get area of the streambuf contains the specified delimiter. 82 * 83 * @li An error occurred. 84 * 85 * This operation is implemented in terms of zero or more calls to the stream's 86 * read_some function. If the streambuf's get area already contains the 87 * delimiter, the function returns immediately. 88 * 89 * @param s The stream from which the data is to be read. The type must support 90 * the SyncReadStream concept. 91 * 92 * @param b A streambuf object into which the data will be read. 93 * 94 * @param delim The delimiter character. 95 * 96 * @returns The number of bytes in the streambuf's get area up to and including 97 * the delimiter. 98 * 99 * @throws boost::system::system_error Thrown on failure. 100 * 101 * @note After a successful read_until operation, the streambuf may contain 102 * additional data beyond the delimiter. An application will typically leave 103 * that data in the streambuf for a subsequent read_until operation to examine. 104 * 105 * @par Example 106 * To read data into a streambuf until a newline is encountered: 107 * @code boost::asio::streambuf b; 108 * boost::asio::read_until(s, b, '\n'); 109 * std::istream is(&b); 110 * std::string line; 111 * std::getline(is, line); @endcode 112 * After the @c read_until operation completes successfully, the buffer @c b 113 * contains the delimiter: 114 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode 115 * The call to @c std::getline then extracts the data up to and including the 116 * delimiter, so that the string @c line contains: 117 * @code { 'a', 'b', ..., 'c', '\n' } @endcode 118 * The remaining data is left in the buffer @c b as follows: 119 * @code { 'd', 'e', ... } @endcode 120 * This data may be the start of a new line, to be extracted by a subsequent 121 * @c read_until operation. 122 */ 123 template <typename SyncReadStream, typename Allocator> 124 std::size_t read_until(SyncReadStream& s, 125 boost::asio::basic_streambuf<Allocator>& b, char delim); 126 127 /// Read data into a streambuf until it contains a specified delimiter. 128 /** 129 * This function is used to read data into the specified streambuf until the 130 * streambuf's get area contains the specified delimiter. The call will block 131 * until one of the following conditions is true: 132 * 133 * @li The get area of the streambuf contains the specified delimiter. 134 * 135 * @li An error occurred. 136 * 137 * This operation is implemented in terms of zero or more calls to the stream's 138 * read_some function. If the streambuf's get area already contains the 139 * delimiter, the function returns immediately. 140 * 141 * @param s The stream from which the data is to be read. The type must support 142 * the SyncReadStream concept. 143 * 144 * @param b A streambuf object into which the data will be read. 145 * 146 * @param delim The delimiter character. 147 * 148 * @param ec Set to indicate what error occurred, if any. 149 * 150 * @returns The number of bytes in the streambuf's get area up to and including 151 * the delimiter. Returns 0 if an error occurred. 152 * 153 * @note After a successful read_until operation, the streambuf may contain 154 * additional data beyond the delimiter. An application will typically leave 155 * that data in the streambuf for a subsequent read_until operation to examine. 156 */ 157 template <typename SyncReadStream, typename Allocator> 158 std::size_t read_until(SyncReadStream& s, 159 boost::asio::basic_streambuf<Allocator>& b, char delim, 160 boost::system::error_code& ec); 161 162 /// Read data into a streambuf until it contains a specified delimiter. 163 /** 164 * This function is used to read data into the specified streambuf until the 165 * streambuf's get area contains the specified delimiter. The call will block 166 * until one of the following conditions is true: 167 * 168 * @li The get area of the streambuf contains the specified delimiter. 169 * 170 * @li An error occurred. 171 * 172 * This operation is implemented in terms of zero or more calls to the stream's 173 * read_some function. If the streambuf's get area already contains the 174 * delimiter, the function returns immediately. 175 * 176 * @param s The stream from which the data is to be read. The type must support 177 * the SyncReadStream concept. 178 * 179 * @param b A streambuf object into which the data will be read. 180 * 181 * @param delim The delimiter string. 182 * 183 * @returns The number of bytes in the streambuf's get area up to and including 184 * the delimiter. 185 * 186 * @throws boost::system::system_error Thrown on failure. 187 * 188 * @note After a successful read_until operation, the streambuf may contain 189 * additional data beyond the delimiter. An application will typically leave 190 * that data in the streambuf for a subsequent read_until operation to examine. 191 * 192 * @par Example 193 * To read data into a streambuf until a newline is encountered: 194 * @code boost::asio::streambuf b; 195 * boost::asio::read_until(s, b, "\r\n"); 196 * std::istream is(&b); 197 * std::string line; 198 * std::getline(is, line); @endcode 199 * After the @c read_until operation completes successfully, the buffer @c b 200 * contains the delimiter: 201 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode 202 * The call to @c std::getline then extracts the data up to and including the 203 * delimiter, so that the string @c line contains: 204 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode 205 * The remaining data is left in the buffer @c b as follows: 206 * @code { 'd', 'e', ... } @endcode 207 * This data may be the start of a new line, to be extracted by a subsequent 208 * @c read_until operation. 209 */ 210 template <typename SyncReadStream, typename Allocator> 211 std::size_t read_until(SyncReadStream& s, 212 boost::asio::basic_streambuf<Allocator>& b, const std::string& delim); 213 214 /// Read data into a streambuf until it contains a specified delimiter. 215 /** 216 * This function is used to read data into the specified streambuf until the 217 * streambuf's get area contains the specified delimiter. The call will block 218 * until one of the following conditions is true: 219 * 220 * @li The get area of the streambuf contains the specified delimiter. 221 * 222 * @li An error occurred. 223 * 224 * This operation is implemented in terms of zero or more calls to the stream's 225 * read_some function. If the streambuf's get area already contains the 226 * delimiter, the function returns immediately. 227 * 228 * @param s The stream from which the data is to be read. The type must support 229 * the SyncReadStream concept. 230 * 231 * @param b A streambuf object into which the data will be read. 232 * 233 * @param delim The delimiter string. 234 * 235 * @param ec Set to indicate what error occurred, if any. 236 * 237 * @returns The number of bytes in the streambuf's get area up to and including 238 * the delimiter. Returns 0 if an error occurred. 239 * 240 * @note After a successful read_until operation, the streambuf may contain 241 * additional data beyond the delimiter. An application will typically leave 242 * that data in the streambuf for a subsequent read_until operation to examine. 243 */ 244 template <typename SyncReadStream, typename Allocator> 245 std::size_t read_until(SyncReadStream& s, 246 boost::asio::basic_streambuf<Allocator>& b, const std::string& delim, 247 boost::system::error_code& ec); 248 249 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \ 250 || defined(GENERATING_DOCUMENTATION) 251 252 /// Read data into a streambuf until some part of the data it contains matches 253 /// a regular expression. 254 /** 255 * This function is used to read data into the specified streambuf until the 256 * streambuf's get area contains some data that matches a regular expression. 257 * The call will block until one of the following conditions is true: 258 * 259 * @li A substring of the streambuf's get area matches the regular expression. 260 * 261 * @li An error occurred. 262 * 263 * This operation is implemented in terms of zero or more calls to the stream's 264 * read_some function. If the streambuf's get area already contains data that 265 * matches the regular expression, the function returns immediately. 266 * 267 * @param s The stream from which the data is to be read. The type must support 268 * the SyncReadStream concept. 269 * 270 * @param b A streambuf object into which the data will be read. 271 * 272 * @param expr The regular expression. 273 * 274 * @returns The number of bytes in the streambuf's get area up to and including 275 * the substring that matches the regular expression. 276 * 277 * @throws boost::system::system_error Thrown on failure. 278 * 279 * @note After a successful read_until operation, the streambuf may contain 280 * additional data beyond that which matched the regular expression. An 281 * application will typically leave that data in the streambuf for a subsequent 282 * read_until operation to examine. 283 * 284 * @par Example 285 * To read data into a streambuf until a CR-LF sequence is encountered: 286 * @code boost::asio::streambuf b; 287 * boost::asio::read_until(s, b, boost::regex("\r\n")); 288 * std::istream is(&b); 289 * std::string line; 290 * std::getline(is, line); @endcode 291 * After the @c read_until operation completes successfully, the buffer @c b 292 * contains the data which matched the regular expression: 293 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode 294 * The call to @c std::getline then extracts the data up to and including the 295 * match, so that the string @c line contains: 296 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode 297 * The remaining data is left in the buffer @c b as follows: 298 * @code { 'd', 'e', ... } @endcode 299 * This data may be the start of a new line, to be extracted by a subsequent 300 * @c read_until operation. 301 */ 302 template <typename SyncReadStream, typename Allocator> 303 std::size_t read_until(SyncReadStream& s, 304 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr); 305 306 /// Read data into a streambuf until some part of the data it contains matches 307 /// a regular expression. 308 /** 309 * This function is used to read data into the specified streambuf until the 310 * streambuf's get area contains some data that matches a regular expression. 311 * The call will block until one of the following conditions is true: 312 * 313 * @li A substring of the streambuf's get area matches the regular expression. 314 * 315 * @li An error occurred. 316 * 317 * This operation is implemented in terms of zero or more calls to the stream's 318 * read_some function. If the streambuf's get area already contains data that 319 * matches the regular expression, the function returns immediately. 320 * 321 * @param s The stream from which the data is to be read. The type must support 322 * the SyncReadStream concept. 323 * 324 * @param b A streambuf object into which the data will be read. 325 * 326 * @param expr The regular expression. 327 * 328 * @param ec Set to indicate what error occurred, if any. 329 * 330 * @returns The number of bytes in the streambuf's get area up to and including 331 * the substring that matches the regular expression. Returns 0 if an error 332 * occurred. 333 * 334 * @note After a successful read_until operation, the streambuf may contain 335 * additional data beyond that which matched the regular expression. An 336 * application will typically leave that data in the streambuf for a subsequent 337 * read_until operation to examine. 338 */ 339 template <typename SyncReadStream, typename Allocator> 340 std::size_t read_until(SyncReadStream& s, 341 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr, 342 boost::system::error_code& ec); 343 344 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) 345 // || defined(GENERATING_DOCUMENTATION) 346 347 /// Read data into a streambuf until a function object indicates a match. 348 /** 349 * This function is used to read data into the specified streambuf until a 350 * user-defined match condition function object, when applied to the data 351 * contained in the streambuf, indicates a successful match. The call will 352 * block until one of the following conditions is true: 353 * 354 * @li The match condition function object returns a std::pair where the second 355 * element evaluates to true. 356 * 357 * @li An error occurred. 358 * 359 * This operation is implemented in terms of zero or more calls to the stream's 360 * read_some function. If the match condition function object already indicates 361 * a match, the function returns immediately. 362 * 363 * @param s The stream from which the data is to be read. The type must support 364 * the SyncReadStream concept. 365 * 366 * @param b A streambuf object into which the data will be read. 367 * 368 * @param match_condition The function object to be called to determine whether 369 * a match exists. The signature of the function object must be: 370 * @code pair<iterator, bool> match_condition(iterator begin, iterator end); 371 * @endcode 372 * where @c iterator represents the type: 373 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type> 374 * @endcode 375 * The iterator parameters @c begin and @c end define the range of bytes to be 376 * scanned to determine whether there is a match. The @c first member of the 377 * return value is an iterator marking one-past-the-end of the bytes that have 378 * been consumed by the match function. This iterator is used to calculate the 379 * @c begin parameter for any subsequent invocation of the match condition. The 380 * @c second member of the return value is true if a match has been found, false 381 * otherwise. 382 * 383 * @returns The number of bytes in the streambuf's get area that have been fully 384 * consumed by the match function. 385 * 386 * @throws boost::system::system_error Thrown on failure. 387 * 388 * @note After a successful read_until operation, the streambuf may contain 389 * additional data beyond that which matched the function object. An application 390 * will typically leave that data in the streambuf for a subsequent 391 * 392 * @note The default implementation of the @c is_match_condition type trait 393 * evaluates to true for function pointers and function objects with a 394 * @c result_type typedef. It must be specialised for other user-defined 395 * function objects. 396 * 397 * @par Examples 398 * To read data into a streambuf until whitespace is encountered: 399 * @code typedef boost::asio::buffers_iterator< 400 * boost::asio::streambuf::const_buffers_type> iterator; 401 * 402 * std::pair<iterator, bool> 403 * match_whitespace(iterator begin, iterator end) 404 * { 405 * iterator i = begin; 406 * while (i != end) 407 * if (std::isspace(*i++)) 408 * return std::make_pair(i, true); 409 * return std::make_pair(i, false); 410 * } 411 * ... 412 * boost::asio::streambuf b; 413 * boost::asio::read_until(s, b, match_whitespace); 414 * @endcode 415 * 416 * To read data into a streambuf until a matching character is found: 417 * @code class match_char 418 * { 419 * public: 420 * explicit match_char(char c) : c_(c) {} 421 * 422 * template <typename Iterator> 423 * std::pair<Iterator, bool> operator()( 424 * Iterator begin, Iterator end) const 425 * { 426 * Iterator i = begin; 427 * while (i != end) 428 * if (c_ == *i++) 429 * return std::make_pair(i, true); 430 * return std::make_pair(i, false); 431 * } 432 * 433 * private: 434 * char c_; 435 * }; 436 * 437 * namespace asio { 438 * template <> struct is_match_condition<match_char> 439 * : public boost::true_type {}; 440 * } // namespace asio 441 * ... 442 * boost::asio::streambuf b; 443 * boost::asio::read_until(s, b, match_char('a')); 444 * @endcode 445 */ 446 template <typename SyncReadStream, typename Allocator, typename MatchCondition> 447 std::size_t read_until(SyncReadStream& s, 448 boost::asio::basic_streambuf<Allocator>& b, MatchCondition match_condition, 449 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0); 450 451 /// Read data into a streambuf until a function object indicates a match. 452 /** 453 * This function is used to read data into the specified streambuf until a 454 * user-defined match condition function object, when applied to the data 455 * contained in the streambuf, indicates a successful match. The call will 456 * block until one of the following conditions is true: 457 * 458 * @li The match condition function object returns a std::pair where the second 459 * element evaluates to true. 460 * 461 * @li An error occurred. 462 * 463 * This operation is implemented in terms of zero or more calls to the stream's 464 * read_some function. If the match condition function object already indicates 465 * a match, the function returns immediately. 466 * 467 * @param s The stream from which the data is to be read. The type must support 468 * the SyncReadStream concept. 469 * 470 * @param b A streambuf object into which the data will be read. 471 * 472 * @param match_condition The function object to be called to determine whether 473 * a match exists. The signature of the function object must be: 474 * @code pair<iterator, bool> match_condition(iterator begin, iterator end); 475 * @endcode 476 * where @c iterator represents the type: 477 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type> 478 * @endcode 479 * The iterator parameters @c begin and @c end define the range of bytes to be 480 * scanned to determine whether there is a match. The @c first member of the 481 * return value is an iterator marking one-past-the-end of the bytes that have 482 * been consumed by the match function. This iterator is used to calculate the 483 * @c begin parameter for any subsequent invocation of the match condition. The 484 * @c second member of the return value is true if a match has been found, false 485 * otherwise. 486 * 487 * @param ec Set to indicate what error occurred, if any. 488 * 489 * @returns The number of bytes in the streambuf's get area that have been fully 490 * consumed by the match function. Returns 0 if an error occurred. 491 * 492 * @note After a successful read_until operation, the streambuf may contain 493 * additional data beyond that which matched the function object. An application 494 * will typically leave that data in the streambuf for a subsequent 495 * 496 * @note The default implementation of the @c is_match_condition type trait 497 * evaluates to true for function pointers and function objects with a 498 * @c result_type typedef. It must be specialised for other user-defined 499 * function objects. 500 */ 501 template <typename SyncReadStream, typename Allocator, typename MatchCondition> 502 std::size_t read_until(SyncReadStream& s, 503 boost::asio::basic_streambuf<Allocator>& b, 504 MatchCondition match_condition, boost::system::error_code& ec, 505 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0); 506 507 /*@}*/ 508 /** 509 * @defgroup async_read_until boost::asio::async_read_until 510 * 511 * @brief Start an asynchronous operation to read data into a streambuf until it 512 * contains a delimiter, matches a regular expression, or a function object 513 * indicates a match. 514 */ 515 /*@{*/ 516 517 /// Start an asynchronous operation to read data into a streambuf until it 518 /// contains a specified delimiter. 519 /** 520 * This function is used to asynchronously read data into the specified 521 * streambuf until the streambuf's get area contains the specified delimiter. 522 * The function call always returns immediately. The asynchronous operation 523 * will continue until one of the following conditions is true: 524 * 525 * @li The get area of the streambuf contains the specified delimiter. 526 * 527 * @li An error occurred. 528 * 529 * This operation is implemented in terms of zero or more calls to the stream's 530 * async_read_some function, and is known as a <em>composed operation</em>. If 531 * the streambuf's get area already contains the delimiter, this asynchronous 532 * operation completes immediately. The program must ensure that the stream 533 * performs no other read operations (such as async_read, async_read_until, the 534 * stream's async_read_some function, or any other composed operations that 535 * perform reads) until this operation completes. 536 * 537 * @param s The stream from which the data is to be read. The type must support 538 * the AsyncReadStream concept. 539 * 540 * @param b A streambuf object into which the data will be read. Ownership of 541 * the streambuf is retained by the caller, which must guarantee that it remains 542 * valid until the handler is called. 543 * 544 * @param delim The delimiter character. 545 * 546 * @param handler The handler to be called when the read operation completes. 547 * Copies will be made of the handler as required. The function signature of the 548 * handler must be: 549 * @code void handler( 550 * // Result of operation. 551 * const boost::system::error_code& error, 552 * 553 * // The number of bytes in the streambuf's get 554 * // area up to and including the delimiter. 555 * // 0 if an error occurred. 556 * std::size_t bytes_transferred 557 * ); @endcode 558 * Regardless of whether the asynchronous operation completes immediately or 559 * not, the handler will not be invoked from within this function. Invocation of 560 * the handler will be performed in a manner equivalent to using 561 * boost::asio::io_service::post(). 562 * 563 * @note After a successful async_read_until operation, the streambuf may 564 * contain additional data beyond the delimiter. An application will typically 565 * leave that data in the streambuf for a subsequent async_read_until operation 566 * to examine. 567 * 568 * @par Example 569 * To asynchronously read data into a streambuf until a newline is encountered: 570 * @code boost::asio::streambuf b; 571 * ... 572 * void handler(const boost::system::error_code& e, std::size_t size) 573 * { 574 * if (!e) 575 * { 576 * std::istream is(&b); 577 * std::string line; 578 * std::getline(is, line); 579 * ... 580 * } 581 * } 582 * ... 583 * boost::asio::async_read_until(s, b, '\n', handler); @endcode 584 * After the @c async_read_until operation completes successfully, the buffer 585 * @c b contains the delimiter: 586 * @code { 'a', 'b', ..., 'c', '\n', 'd', 'e', ... } @endcode 587 * The call to @c std::getline then extracts the data up to and including the 588 * delimiter, so that the string @c line contains: 589 * @code { 'a', 'b', ..., 'c', '\n' } @endcode 590 * The remaining data is left in the buffer @c b as follows: 591 * @code { 'd', 'e', ... } @endcode 592 * This data may be the start of a new line, to be extracted by a subsequent 593 * @c async_read_until operation. 594 */ 595 template <typename AsyncReadStream, typename Allocator, typename ReadHandler> 596 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, 597 void (boost::system::error_code, std::size_t)) 598 async_read_until(AsyncReadStream& s, 599 boost::asio::basic_streambuf<Allocator>& b, 600 char delim, BOOST_ASIO_MOVE_ARG(ReadHandler) handler); 601 602 /// Start an asynchronous operation to read data into a streambuf until it 603 /// contains a specified delimiter. 604 /** 605 * This function is used to asynchronously read data into the specified 606 * streambuf until the streambuf's get area contains the specified delimiter. 607 * The function call always returns immediately. The asynchronous operation 608 * will continue until one of the following conditions is true: 609 * 610 * @li The get area of the streambuf contains the specified delimiter. 611 * 612 * @li An error occurred. 613 * 614 * This operation is implemented in terms of zero or more calls to the stream's 615 * async_read_some function, and is known as a <em>composed operation</em>. If 616 * the streambuf's get area already contains the delimiter, this asynchronous 617 * operation completes immediately. The program must ensure that the stream 618 * performs no other read operations (such as async_read, async_read_until, the 619 * stream's async_read_some function, or any other composed operations that 620 * perform reads) until this operation completes. 621 * 622 * @param s The stream from which the data is to be read. The type must support 623 * the AsyncReadStream concept. 624 * 625 * @param b A streambuf object into which the data will be read. Ownership of 626 * the streambuf is retained by the caller, which must guarantee that it remains 627 * valid until the handler is called. 628 * 629 * @param delim The delimiter string. 630 * 631 * @param handler The handler to be called when the read operation completes. 632 * Copies will be made of the handler as required. The function signature of the 633 * handler must be: 634 * @code void handler( 635 * // Result of operation. 636 * const boost::system::error_code& error, 637 * 638 * // The number of bytes in the streambuf's get 639 * // area up to and including the delimiter. 640 * // 0 if an error occurred. 641 * std::size_t bytes_transferred 642 * ); @endcode 643 * Regardless of whether the asynchronous operation completes immediately or 644 * not, the handler will not be invoked from within this function. Invocation of 645 * the handler will be performed in a manner equivalent to using 646 * boost::asio::io_service::post(). 647 * 648 * @note After a successful async_read_until operation, the streambuf may 649 * contain additional data beyond the delimiter. An application will typically 650 * leave that data in the streambuf for a subsequent async_read_until operation 651 * to examine. 652 * 653 * @par Example 654 * To asynchronously read data into a streambuf until a newline is encountered: 655 * @code boost::asio::streambuf b; 656 * ... 657 * void handler(const boost::system::error_code& e, std::size_t size) 658 * { 659 * if (!e) 660 * { 661 * std::istream is(&b); 662 * std::string line; 663 * std::getline(is, line); 664 * ... 665 * } 666 * } 667 * ... 668 * boost::asio::async_read_until(s, b, "\r\n", handler); @endcode 669 * After the @c async_read_until operation completes successfully, the buffer 670 * @c b contains the delimiter: 671 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode 672 * The call to @c std::getline then extracts the data up to and including the 673 * delimiter, so that the string @c line contains: 674 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode 675 * The remaining data is left in the buffer @c b as follows: 676 * @code { 'd', 'e', ... } @endcode 677 * This data may be the start of a new line, to be extracted by a subsequent 678 * @c async_read_until operation. 679 */ 680 template <typename AsyncReadStream, typename Allocator, typename ReadHandler> 681 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, 682 void (boost::system::error_code, std::size_t)) 683 async_read_until(AsyncReadStream& s, 684 boost::asio::basic_streambuf<Allocator>& b, const std::string& delim, 685 BOOST_ASIO_MOVE_ARG(ReadHandler) handler); 686 687 #if defined(BOOST_ASIO_HAS_BOOST_REGEX) \ 688 || defined(GENERATING_DOCUMENTATION) 689 690 /// Start an asynchronous operation to read data into a streambuf until some 691 /// part of its data matches a regular expression. 692 /** 693 * This function is used to asynchronously read data into the specified 694 * streambuf until the streambuf's get area contains some data that matches a 695 * regular expression. The function call always returns immediately. The 696 * asynchronous operation will continue until one of the following conditions 697 * is true: 698 * 699 * @li A substring of the streambuf's get area matches the regular expression. 700 * 701 * @li An error occurred. 702 * 703 * This operation is implemented in terms of zero or more calls to the stream's 704 * async_read_some function, and is known as a <em>composed operation</em>. If 705 * the streambuf's get area already contains data that matches the regular 706 * expression, this asynchronous operation completes immediately. The program 707 * must ensure that the stream performs no other read operations (such as 708 * async_read, async_read_until, the stream's async_read_some function, or any 709 * other composed operations that perform reads) until this operation 710 * completes. 711 * 712 * @param s The stream from which the data is to be read. The type must support 713 * the AsyncReadStream concept. 714 * 715 * @param b A streambuf object into which the data will be read. Ownership of 716 * the streambuf is retained by the caller, which must guarantee that it remains 717 * valid until the handler is called. 718 * 719 * @param expr The regular expression. 720 * 721 * @param handler The handler to be called when the read operation completes. 722 * Copies will be made of the handler as required. The function signature of the 723 * handler must be: 724 * @code void handler( 725 * // Result of operation. 726 * const boost::system::error_code& error, 727 * 728 * // The number of bytes in the streambuf's get 729 * // area up to and including the substring 730 * // that matches the regular. expression. 731 * // 0 if an error occurred. 732 * std::size_t bytes_transferred 733 * ); @endcode 734 * Regardless of whether the asynchronous operation completes immediately or 735 * not, the handler will not be invoked from within this function. Invocation of 736 * the handler will be performed in a manner equivalent to using 737 * boost::asio::io_service::post(). 738 * 739 * @note After a successful async_read_until operation, the streambuf may 740 * contain additional data beyond that which matched the regular expression. An 741 * application will typically leave that data in the streambuf for a subsequent 742 * async_read_until operation to examine. 743 * 744 * @par Example 745 * To asynchronously read data into a streambuf until a CR-LF sequence is 746 * encountered: 747 * @code boost::asio::streambuf b; 748 * ... 749 * void handler(const boost::system::error_code& e, std::size_t size) 750 * { 751 * if (!e) 752 * { 753 * std::istream is(&b); 754 * std::string line; 755 * std::getline(is, line); 756 * ... 757 * } 758 * } 759 * ... 760 * boost::asio::async_read_until(s, b, boost::regex("\r\n"), handler); @endcode 761 * After the @c async_read_until operation completes successfully, the buffer 762 * @c b contains the data which matched the regular expression: 763 * @code { 'a', 'b', ..., 'c', '\r', '\n', 'd', 'e', ... } @endcode 764 * The call to @c std::getline then extracts the data up to and including the 765 * match, so that the string @c line contains: 766 * @code { 'a', 'b', ..., 'c', '\r', '\n' } @endcode 767 * The remaining data is left in the buffer @c b as follows: 768 * @code { 'd', 'e', ... } @endcode 769 * This data may be the start of a new line, to be extracted by a subsequent 770 * @c async_read_until operation. 771 */ 772 template <typename AsyncReadStream, typename Allocator, typename ReadHandler> 773 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, 774 void (boost::system::error_code, std::size_t)) 775 async_read_until(AsyncReadStream& s, 776 boost::asio::basic_streambuf<Allocator>& b, const boost::regex& expr, 777 BOOST_ASIO_MOVE_ARG(ReadHandler) handler); 778 779 #endif // defined(BOOST_ASIO_HAS_BOOST_REGEX) 780 // || defined(GENERATING_DOCUMENTATION) 781 782 /// Start an asynchronous operation to read data into a streambuf until a 783 /// function object indicates a match. 784 /** 785 * This function is used to asynchronously read data into the specified 786 * streambuf until a user-defined match condition function object, when applied 787 * to the data contained in the streambuf, indicates a successful match. The 788 * function call always returns immediately. The asynchronous operation will 789 * continue until one of the following conditions is true: 790 * 791 * @li The match condition function object returns a std::pair where the second 792 * element evaluates to true. 793 * 794 * @li An error occurred. 795 * 796 * This operation is implemented in terms of zero or more calls to the stream's 797 * async_read_some function, and is known as a <em>composed operation</em>. If 798 * the match condition function object already indicates a match, this 799 * asynchronous operation completes immediately. The program must ensure that 800 * the stream performs no other read operations (such as async_read, 801 * async_read_until, the stream's async_read_some function, or any other 802 * composed operations that perform reads) until this operation completes. 803 * 804 * @param s The stream from which the data is to be read. The type must support 805 * the AsyncReadStream concept. 806 * 807 * @param b A streambuf object into which the data will be read. 808 * 809 * @param match_condition The function object to be called to determine whether 810 * a match exists. The signature of the function object must be: 811 * @code pair<iterator, bool> match_condition(iterator begin, iterator end); 812 * @endcode 813 * where @c iterator represents the type: 814 * @code buffers_iterator<basic_streambuf<Allocator>::const_buffers_type> 815 * @endcode 816 * The iterator parameters @c begin and @c end define the range of bytes to be 817 * scanned to determine whether there is a match. The @c first member of the 818 * return value is an iterator marking one-past-the-end of the bytes that have 819 * been consumed by the match function. This iterator is used to calculate the 820 * @c begin parameter for any subsequent invocation of the match condition. The 821 * @c second member of the return value is true if a match has been found, false 822 * otherwise. 823 * 824 * @param handler The handler to be called when the read operation completes. 825 * Copies will be made of the handler as required. The function signature of the 826 * handler must be: 827 * @code void handler( 828 * // Result of operation. 829 * const boost::system::error_code& error, 830 * 831 * // The number of bytes in the streambuf's get 832 * // area that have been fully consumed by the 833 * // match function. O if an error occurred. 834 * std::size_t bytes_transferred 835 * ); @endcode 836 * Regardless of whether the asynchronous operation completes immediately or 837 * not, the handler will not be invoked from within this function. Invocation of 838 * the handler will be performed in a manner equivalent to using 839 * boost::asio::io_service::post(). 840 * 841 * @note After a successful async_read_until operation, the streambuf may 842 * contain additional data beyond that which matched the function object. An 843 * application will typically leave that data in the streambuf for a subsequent 844 * async_read_until operation to examine. 845 * 846 * @note The default implementation of the @c is_match_condition type trait 847 * evaluates to true for function pointers and function objects with a 848 * @c result_type typedef. It must be specialised for other user-defined 849 * function objects. 850 * 851 * @par Examples 852 * To asynchronously read data into a streambuf until whitespace is encountered: 853 * @code typedef boost::asio::buffers_iterator< 854 * boost::asio::streambuf::const_buffers_type> iterator; 855 * 856 * std::pair<iterator, bool> 857 * match_whitespace(iterator begin, iterator end) 858 * { 859 * iterator i = begin; 860 * while (i != end) 861 * if (std::isspace(*i++)) 862 * return std::make_pair(i, true); 863 * return std::make_pair(i, false); 864 * } 865 * ... 866 * void handler(const boost::system::error_code& e, std::size_t size); 867 * ... 868 * boost::asio::streambuf b; 869 * boost::asio::async_read_until(s, b, match_whitespace, handler); 870 * @endcode 871 * 872 * To asynchronously read data into a streambuf until a matching character is 873 * found: 874 * @code class match_char 875 * { 876 * public: 877 * explicit match_char(char c) : c_(c) {} 878 * 879 * template <typename Iterator> 880 * std::pair<Iterator, bool> operator()( 881 * Iterator begin, Iterator end) const 882 * { 883 * Iterator i = begin; 884 * while (i != end) 885 * if (c_ == *i++) 886 * return std::make_pair(i, true); 887 * return std::make_pair(i, false); 888 * } 889 * 890 * private: 891 * char c_; 892 * }; 893 * 894 * namespace asio { 895 * template <> struct is_match_condition<match_char> 896 * : public boost::true_type {}; 897 * } // namespace asio 898 * ... 899 * void handler(const boost::system::error_code& e, std::size_t size); 900 * ... 901 * boost::asio::streambuf b; 902 * boost::asio::async_read_until(s, b, match_char('a'), handler); 903 * @endcode 904 */ 905 template <typename AsyncReadStream, typename Allocator, 906 typename MatchCondition, typename ReadHandler> 907 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler, 908 void (boost::system::error_code, std::size_t)) 909 async_read_until(AsyncReadStream& s, 910 boost::asio::basic_streambuf<Allocator>& b, 911 MatchCondition match_condition, BOOST_ASIO_MOVE_ARG(ReadHandler) handler, 912 typename enable_if<is_match_condition<MatchCondition>::value>::type* = 0); 913 914 /*@}*/ 915 916 } // namespace asio 917 } // namespace boost 918 919 #include <boost/asio/detail/pop_options.hpp> 920 921 #include <boost/asio/impl/read_until.hpp> 922 923 #endif // !defined(BOOST_ASIO_NO_IOSTREAM) 924 925 #endif // BOOST_ASIO_READ_UNTIL_HPP 926